Oracle Cloud Free Tier — Hermes Agent Setup Guide

Deploy a 24/7 AI agent on Oracle Cloud’s always-free infrastructure. Free forever: 2 x 1GB VMs, 200GB storage, 10TB outbound data per month.

Overview
Prerequisites
Create Oracle Cloud Account
Create a VM Instance (Always Free)
SSH Into the VM
Install Docker
Install Hermes Agent
Configure a Telegram Bot
Configure a Model Provider
Start the Gateway (24/7)
Useful Commands
Troubleshooting
Pricing & Limits

Overview

This guide walks through deploying Hermes Agent 24/7 on Oracle Cloud Free Tier.

What you’ll get:

A private AI agent running in the cloud — always online
Accessible via Telegram, Discord, or CLI
Zero cost for the VM (1 GB RAM, free tier)
~500 MB free RAM for the agent after OS overhead

Architecture:

You (Telegram) ──→ Oracle Cloud VM ──→ Hermes Gateway ──→ AI Model API
                                              (OpenRouter / Ollama Cloud)

1. Create Oracle Cloud Account

Go to https://www.oracle.com/cloud/free/
Click “Start for free”
Provide email, password, country
Verify your email
Do NOT add payment method — select the “Always Free” tier option
Wait for account activation (~10-30 minutes)

2. Create a VM Instance (Always Free)

⚠️ Critical: Choose the right OS image

Image	RAM After Boot	Verdict
Canonical Ubuntu 24.04 Minimal	~300 MB used	✅ Use this
Canonical Ubuntu 22.04 Minimal	~350 MB used	✅ Works
Oracle Linux 9.7	~500 MB used	❌ aarch64 only, incompatible with free tier shapes

Never use Oracle Linux 9.7 Minimal on VM.Standard.E2 shapes — the E2 series is x86_64, but OL9.7 Minimal is aarch64-only and will fail to launch.

Pick a shape

Shape	RAM	Notes
`VM.Standard.E2.1.Micro`	1 GB	✅ Always available — recommended
`VM.Standard.A1.Flex`	6 GB	Often out of capacity; check your region

Step-by-step

Log into OCI Console: https://cloud.oracle.com
Hamburger Menu → Compute → Instances
Click “Create Instance”
Configure:
- Name: hermes-agent (or anything you like)
- Image: Canonical Ubuntu 24.04 Minimal — this is important
- Shape: VM.Standard.E2.1.Micro
- SSH Keys: Upload your local ~/.ssh/id_ed25519.pub (generate one with ssh-keygen -t ed25519 if you don’t have it)
- Networking: Let it create a new VCN and public subnet automatically (defaults work fine)
Click Create — the instance will provision in ~30 seconds
Note the public IP address shown after creation

3. SSH Into the VM

From your local machine:

ssh -o StrictHostKeyChecking=no ubuntu@<PUBLIC_IP>

If you used a non-default key:

ssh -i ~/.ssh/my_custom_key ubuntu@<PUBLIC_IP>

Wait for boot: The VM shows RUNNING before SSH is ready. Wait 30-60 seconds after RUNNING for cloud-init to configure SSH keys. If you get Connection refused or Connection timed out, wait a bit and retry.

4. Install Docker

⚠️ Never use apt install docker.io on a 1GB VM. The package manager triggers full dependency resolution and exhausts all RAM, freezing the machine for 5-10 minutes. Use the official binary script instead.

# Install Docker (binary — no apt used)
curl -fsSL https://get.docker.com | sh

# Add your user to the docker group
sudo usermod -aG docker ubuntu

# Start Docker
sudo systemctl enable --now docker

# Verify
docker --version

Docker is optional — Hermes Agent works perfectly without it. The pip install method is actually lighter on RAM.

5. Install Hermes Agent

Step 1: Install pip (Ubuntu Minimal doesn’t ship it)

curl -fsSL https://github.com/pypa/get-pip/raw/main/public/get-pip.py -o /tmp/get-pip.py
python3 /tmp/get-pip.py --break-system-packages

Step 2: Download and install Hermes Agent

⚠️ Do NOT try docker pull ghcr.io/nousresearch/hermes-agent — GitHub Container Registry denies unauthenticated pulls. Install from the source tarball instead.

# Add ~/.local/bin to PATH
export PATH=$HOME/.local/bin:$PATH

# Download the source
curl -L https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.tar.gz -o /tmp/hermes.tar.gz

# Extract
cd /tmp && tar xzf hermes.tar.gz

# Install
cd hermes-agent-main
pip install -e . --break-system-packages

# Verify
hermes --version

Expected output: Hermes Agent v0.12.0 (2026.4.30)

Note: --break-system-packages is needed because Ubuntu 24.04 ships with a PEP 668 lock on system Python. This is safe for a single-purpose VM.

6. Configure a Telegram Bot

Create a Telegram bot

Open Telegram and message @BotFather
Send /newbot and follow the prompts
Choose a name and username (e.g., MyAgentBot → @MyAgentBot)
BotFather will give you a token — save it: 123456:ABCdefGHIjklMNOpqrsTUVwxyz

Get your user ID

Open Telegram and message @userinfobot
It replies with your numeric user ID (e.g., 123456789)

Create config files on the VM

SSH into the VM and create the Hermes config directory:

mkdir -p ~/.hermes

Create ~/.hermes/config.yaml:

model:
  default: openai/gpt-4o-mini
  provider: openrouter
gateway:
  telegram:
    token: "YOUR_BOT_TOKEN_HERE"
display:
  personality: helpful
terminal:
  backend: local
memory:
  memory_enabled: true
  user_profile_enabled: true

Create ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=YOUR_BOT_TOKEN_HERE
TELEGRAM_ALLOWED_USERS=YOUR_TELEGRAM_USER_ID

TELEGRAM_ALLOWED_USERS: Set this to your numeric Telegram user ID (from @userinfobot). This is a security measure — only these users can talk to the bot. Omit this (or set GATEWAY_ALLOW_ALL_USERS=true) for open access.

7. Configure a Model Provider

The gateway needs an AI model to respond to messages. Choose one option:

Option A: OpenRouter (simplest, free tier available)

Get an API key from https://openrouter.ai/keys, then:

model:
  default: openai/gpt-4o-mini
  provider: openrouter
providers:
  openrouter:
    api_key: _env:OPENROUTER_API_KEY
    default_model: openai/gpt-4o-mini
    models:
      - openai/gpt-4o-mini
      - anthropic/claude-sonnet-4-5

Add to ~/.hermes/.env:

OPENROUTER_API_KEY=sk-or-v1-YOUR_KEY_HERE

Option B: Ollama Cloud

model:
  default: deepseek-v4-flash
  provider: ollama-cloud
  base_url: https://ollama.com/v1
providers:
  ollama-cloud:
    api_key: YOUR_OLLAMA_CLOUD_KEY
    default_model: deepseek-v4-flash
    models:
      - deepseek-v4-flash
      - deepseek-v4-pro

Option C: Google Gemini (free)

model:
  default: gemini-1.5-flash
  provider: google-gemini-cli

Add to ~/.hermes/.env:

GOOGLE_GEMINI_CLI_API_KEY=AIza...

Option D: OpenAI

model:
  default: gpt-4o-mini
  provider: openai
providers:
  openai:
    api_key: _env:OPENAI_API_KEY

8. Start the Gateway (24/7)

Make sure you’re SSH’d into the VM, then:

# Make sure ~/.local/bin is in PATH
export PATH=$HOME/.local/bin:$PATH

# Install as a systemd user service (auto-start on boot)
hermes gateway install

# Enable "linger" so the service survives logout
sudo loginctl enable-linger $(whoami)

# Start the gateway
hermes gateway start

# Check status
hermes gateway status

Expected output:

● hermes-gateway.service - Hermes Agent Gateway - Messaging Platform Integration
   Active: active (running) since ...
✓ User gateway service is running
✓ Systemd linger is enabled (service survives logout)

Test it

Message your bot on Telegram — it should reply.

9. Useful Commands

# Check gateway status
hermes gateway status

# View live logs
journalctl --user -u hermes-gateway -f

# View last 50 log lines
journalctl --user -u hermes-gateway --no-pager -n 50

# Stop the gateway
hermes gateway stop

# Restart the gateway (after config changes)
hermes gateway restart

# Reinstall the systemd service (after Hermes update)
hermes gateway install

10. Troubleshooting

Symptom	Likely Cause	Solution
`ssh: Connection timed out`	VM still booting	Wait 30-60s after RUNNING state
`ssh: Permission denied (publickey)`	Wrong SSH key	Make sure you added your public key at instance creation
SSH freezes after a command	apt consumed all RAM	Wait 5-10 minutes; never run apt on a 1GB VM
`hermes: command not found`	PATH not set	Run `export PATH=$HOME/.local/bin:$PATH`
`pip: command not found`	No pip on Minimal image	Run the get-pip.py bootstrap (see step 5)
`pip install` fails: “not writeable”	PEP 668 system lock	Add `--break-system-packages` flag
Gateway: “No messaging platforms”	Missing Telegram token	Set `gateway.telegram.token` in config.yaml
Gateway: “No user allowlists”	Missing TELEGRAM_ALLOWED_USERS	Set env var to your numeric Telegram ID
Agent OOM or crashes	RAM too tight	Stop any Docker containers; pip install is lighter than Docker
`docker pull ghcr.io/...` denied	Unauthenticated to GHCR	Install from GitHub tarball instead
OL9.7 instance won’t launch	aarch64 on E2 (x86_64) shape	Use Ubuntu Minimal x86_64 instead
Instance stuck in STOPPING	OOM killed ACPI signal	Force terminate and create a new instance

Golden rules for 1 GB VMs

✅ Use Ubuntu 24.04 Minimal (~300 MB base RAM)
✅ Use curl -fsSL https://get.docker.com | sh for Docker
✅ Install Hermes via pip from GitHub tarball
❌ Never run apt update or apt upgrade — it exhausts RAM and freezes the VM
❌ Never use Oracle Linux 9.7 on VM.Standard.E2 shapes (arch mismatch)
❌ Don’t run Docker containers alongside the gateway (RAM overhead)

11. Pricing & Limits

Oracle Cloud’s Always Free tier includes:

Resource	Limit
Compute instances	2 x VM.Standard.E2.1.Micro (or A1.Flex)
Storage	200 GB total (boot volumes)
Outbound data	10 TB/month
Load balancer	1 x 10 Mbps
VCN	Up to 5

No credit card required for the basic always-free tier. You can run a Hermes Agent 24/7/365 at zero cost.

Next Steps

Add Discord: Configure gateway.discord.token in your config
Add skills: Run /skills on Telegram to see available capabilities
Cron jobs: Schedule recurring tasks with hermes cron create
Backup: Regularly back up ~/.hermes/config.yaml and ~/.hermes/.env

Generated by Hermes Agent • Guide v1.0 • Hermes Agent Docs

Table of Contents