Hermes Agent + Kilo Code — Troubleshooting & FAQ

Server / SSH issues

"I clicked Console in the Hetzner dashboard and it just says login:"

The web console is a real virtual terminal — it has no idea who you are. At the login: prompt it expects a Linux username (root) and a password. If you only added an SSH key during server creation and never set a root password, root has no password and the web console cannot let you in until you set one.

Fix: SSH in via PowerShell using your key, then run passwd to set a root password. Write it down offline. Use only via the web console as a recovery channel.

"ssh root@ip says Permission denied (publickey)"

The SSH key your local machine is presenting is not the one Hetzner has on file. Compare:

cat $HOME\.ssh\id_ed25519.pub

against Hetzner Cloud → Security → SSH Keys. If your local key isn't listed, either add it to Hetzner (and rebuild the server, or paste it manually after recovering via the web console) or reset the root password from Hetzner and access via the web console.

"ssh times out / connection refused"

Three usual causes:

1. The Hetzner Cloud Firewall is denying inbound 22. Check Cloud → Firewalls.
2. UFW on the server is denying 22 (only relevant if it was enabled before allowing 22 — see "I locked myself out" below).
3. The server is rebooting. Wait 60 seconds.

"I'm locked out — UFW or sshd config broke me"

The Hetzner web console is your escape hatch. Log in there with the root password you set in passwd. Then either fix the offending file or ufw disable. SSH should come back immediately.

If you never set a root password, this is why we keep harping on Phase 1.1 of the VPS install guide.

"My SSH session keeps timing out mid-task"

By default Ubuntu's sshd does not send keepalives. Add to /etc/ssh/sshd_config:

ClientAliveInterval 60
ClientAliveCountMax 10080

And to ~/.ssh/config on your local machine:

Host hetzner
    ServerAliveInterval 60
    ServerAliveCountMax 10080

Then run agent jobs inside tmux so even an actual disconnect doesn't kill them.

"Connection reset" / client_loop: send disconnect

Almost always a network-level interruption (your wifi, a NAT gateway). Reconnect. If frequent, install mosh as a more disconnection-tolerant alternative to SSH. tmux + keepalives usually solves it.

User-isolation issues

"I switched to the hermes user and apt install does not work"

By design. The hermes user has no sudo. Anything system-wide must be run from a separate root SSH window. The two-window pattern (one for root, one for the agent user) is normal and good.

"I want hermes to be able to install packages"

You don't, actually. Giving an autonomous agent sudo defeats the entire isolation model. If a specific binary is genuinely missing, install it as root once and everyone uses it. The system Python, Node, ripgrep, ffmpeg, and tmux cover 95% of what either agent needs.

If you really need a per-user system-package install, look at nix (user-mode Nix), pkgsrc, or linuxbrew — none require root and all work fine in a user's home directory.

Hermes install issues

"The installer asks Install build tools? [Y/n] and I'm running as hermes (no sudo)"

Answer n. The build-essential package is already installed system-wide if you followed Phase 3. Almost no Python packages will need to compile — they ship pre-built wheels for linux/amd64. Hermes will install correctly.

"Playwright is asking for sudo password"

Press Ctrl+C to abort that step. The Hermes Python install completes without it. Then, in a second window as root:

/home/hermes/.hermes/hermes-agent/node_modules/.bin/playwright install-deps chromium

That's the same Playwright the installer dropped, but executed as root, which lets it apt-install the Chromium system libraries (libnss3, libxkbcommon0, etc.). Takes 30–60 seconds.

"After install, hermes is not on PATH (Command 'hermes' not found)"

The installer modifies ~/.bashrc to source ~/.local/bin/env, but if you Ctrl+C'd during Playwright the install may not have symlinked the binary into ~/.local/bin/. Fix:

ln -s /home/hermes/.hermes/hermes-agent/venv/bin/hermes ~/.local/bin/hermes
which hermes
hermes --version

"Where is my installation?"

/home/hermes/.hermes/                    # Hermes' home
├── hermes-agent/                        # The repo
│   ├── venv/bin/hermes                  # The actual binary
│   ├── node_modules/.bin/playwright     # Playwright (Node-based)
│   └── ...
├── .env                                 # Secrets file (mode 600)
└── config.yaml                          # Behavior config

The user-level systemd unit lives at ~/.config/systemd/user/hermes-gateway.service.

Hermes runtime issues

"I run hermes and it doesn't start any wizard, just says [Y/n] to launch chat"

Setup already ran (probably during install). To re-run the wizard:

hermes setup           # full
hermes setup model     # only LLM
hermes setup gateway   # only messaging
hermes config          # view current settings
hermes config edit     # open config in editor

"401 Unauthorized" from OpenRouter

The API key is wrong, expired, or deleted. Check grep OPENROUTER ~/.hermes/.env. Replace if stale. Restart the gateway: systemctl --user restart hermes-gateway.

"402 Payment Required"

Your OpenRouter account has zero credit. Add at least $5–10 (this also raises the free-tier rate limit from ~200/day to ~1000/day). The agent will then fall back to a paid model when free-tier is rate-limited, which is usually what you want.

"429 Too Many Requests" from OpenRouter

You've hit the free-tier daily cap (~200/day unfunded, ~1000/day funded). Either wait until UTC midnight or switch the default model to a paid one. In hermes setup model, pick anthropic/claude-sonnet-4-6 or similar.

"Hermes is responding really slowly"

Free-tier models on OpenRouter can take 30–90 seconds for the first call after a cold start. Subsequent calls are faster. Models that ship with :free suffix are also routed to whichever provider has free capacity — quality and latency vary per call.

If consistent slowness is a problem, switch to a paid model. anthropic/claude-sonnet-4-6 or openai/gpt-5 will be 2–5 seconds per turn.

"ESM updates can be applied" message every login

These are extra Ubuntu Pro security backports. Free for personal use; not required. Either subscribe with pro attach or ignore the message — unattended-upgrades is already handling normal security updates.

Discord gateway issues

For the comprehensive Discord guide, see Hermes Discord Gateway — The Definitive Setup. The most common failures, distilled:

"Failed to connect to bus: No medium found"

User systemd is not running for the hermes user, and XDG_RUNTIME_DIR is unset. Fix:

# As root:
loginctl enable-linger hermes

# As hermes:
export XDG_RUNTIME_DIR=/run/user/$UID
echo 'export XDG_RUNTIME_DIR=/run/user/$UID' >> ~/.bashrc

"Bot is online but reacts with checkmark and never sends words"

You hit the auto_thread trap. Edit ~/.hermes/config.yaml:

discord:
  auto_thread: false

Restart the gateway.

"Bot replies in #general but not in #news-home"

Channel-specific permission override. Either fix permissions on the channel (gear icon → Permissions → bot's role → green-check View/Send/Read/Embed) or delete and recreate the channel.

"Slash command sync timed out after 30s"

Benign on first start. The bot still works for @mentions and DMs. If slash commands are missing after a few minutes, restart the gateway once.

"Anyone in any server can talk to my bot"

DISCORD_ALLOWED_USERS is empty in your .env. Add your numeric Discord user ID (Settings → Advanced → Developer Mode → right-click yourself → Copy User ID). Restart the gateway.

"I asked the bot which channels it can see and it gave a generic answer"

The LLM is hallucinating — it has no introspective view of the Discord gateway. To know what's configured, do not ask the bot in chat. Inspect the actual files:

grep -E '^DISCORD' /home/hermes/.hermes/.env
cat /home/hermes/.hermes/config.yaml | grep -A 20 discord

That's ground truth.

systemd / linger / service issues

"Service starts then dies one second later (status=1/FAILURE)"

Check the journal for the actual error: journalctl --user -u hermes-gateway -n 100 --no-pager. Most common causes:

• Two gateway processes fighting for the same Discord token. Discord allows only one connection per token. Check ps aux | grep hermes.
• Bad token or disabled Message Content Intent — login fails, gateway exits.
• Out of memory on a 4 GB box if you also have a heavy build running. Check with free -h.

"Service won't auto-start on boot"

loginctl show-user hermes | grep Linger    # must be: Linger=yes
systemctl --user is-enabled hermes-gateway # must be: enabled

If lingering is off, the service stops the moment you log out. Run loginctl enable-linger hermes as root.

"I want to see incoming Discord messages in the logs"

Default log level is WARNING. Edit ~/.hermes/config.yaml and bump the relevant logger to INFO or DEBUG. Restart. The log will become much chattier.

Kilo Code issues

"npm i -g fails with EACCES / permission denied"

The npm prefix isn't set. As the kilo user:

mkdir -p ~/.npm-global
npm config set prefix "$HOME/.npm-global"
echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc
npm i -g @kilocode/cli

This installs to ~/.npm-global/, no sudo required.

"kilo: command not found after install"

Same fix as Hermes — PATH is not picking up ~/.npm-global/bin. Ensure that line is in .bashrc, then source ~/.bashrc or log out and back in.

"Kilo asks me which model to use every time I run it"

It hasn't saved a default. Inside Kilo: pick a model, then look for a "set as default" option. Or set via env file:

echo 'OPENROUTER_MODEL=anthropic/claude-sonnet-4-6' >> ~/.config/kilo/env

"How do I run Kilo non-interactively?"

kilo run "your task here"

This is the CI-friendly mode — single shot, exits when done. Useful inside scripts or scheduled jobs.

Operational FAQ

"How do I rotate my OpenRouter key?"

1. OpenRouter dashboard → Keys → create a new key.
2. Edit /home/hermes/.hermes/.env (and /home/kilo/.config/kilo/env) — replace OPENROUTER_API_KEY=.
3. Restart relevant services (systemctl --user restart hermes-gateway).
4. OpenRouter dashboard → revoke the old key.

Total downtime: about 5 seconds per agent.

"How do I rotate the Discord bot token?"

1. Discord Developer Portal → your app → Bot → Reset Token. Copy the new one.
2. Edit /home/hermes/.hermes/.env — replace DISCORD_BOT_TOKEN=.
3. systemctl --user restart hermes-gateway.

The old token is invalidated immediately by Discord on reset.

"How do I monitor what the agent is actually doing?"

# Live log tail
journalctl --user -u hermes-gateway -f

# What files has the agent touched lately?
find /home/hermes/projects -mtime -1 -type f

# OpenRouter spend
# Check the OpenRouter dashboard — the agent's API key shows daily spend

"Can the two agents see each other?"

No. That's the whole point of Phase 2. Verify any time:

sudo -u kilo ls /home/hermes 2>&1     # must say Permission denied
sudo -u hermes ls /home/kilo 2>&1     # must say Permission denied

"What if the agent does something destructive in its own home directory?"

Worst case: the agent corrupts or wipes everything in /home/<agent>/. To recover:

deluser --remove-home hermes
adduser --disabled-password --gecos "" hermes
chmod 700 /home/hermes
# Then re-run Phase 4 (Hermes install) for that user

Total time: ~15 minutes. Keep a copy of .env (off-server) so you don't have to regenerate API keys.

"How do I back up my agent's work?"

The agent's project files are under /home/<agent>/projects/. The simplest backup:

sudo tar czf /root/backup-hermes-$(date +%Y%m%d).tar.gz /home/hermes/projects

Better: have the agent push to a private GitHub repo (git push from inside its project, with credentials in ~/.netrc mode 600). That gives you both backup and version history.

"Can I run more than two agents on this box?"

On a 4 GB CX23, two is the practical limit if both run heavy builds simultaneously. For each additional agent:

1. New Linux user (adduser, chmod 700).
2. loginctl enable-linger <user>.
3. Re-do Phase 4 / Phase 6 under that user with that agent's installer.

Watch RAM with free -h while both run. If you hit swap thrashing, upgrade the VPS to CPX22 (8 GB) — Hetzner upgrades are zero-downtime.

"How do I know which version I have?"

sudo -u hermes /home/hermes/.local/bin/hermes --version
sudo -u kilo bash -lc 'kilo --version'

Hermes prints version, build date, project path, Python version, and OpenAI SDK version, plus an "Up to date" flag if it's current. Kilo prints just version.

When all else fails

1. Read the journal. journalctl --user -u hermes-gateway -n 200 --no-pager is right almost every time.
2. Restart the service. Half of all "weird" issues clear with systemctl --user restart hermes-gateway.
3. Reboot the VPS. Effective; embarrassing; works.
4. Rebuild the user. deluser --remove-home <user>, then redo install. 15 minutes.
5. File an issue on the project's GitHub: NousResearch/hermes-agent for Hermes, Kilo-Org/kilocode for Kilo. Include --version, the journal output, and exact reproduction steps.

Project versions verified for this guide: Hermes Agent v0.11.0 (release v2026.4.23), Kilo Code CLI v7.2.x, Ubuntu 24.04.4 LTS, kernel 6.8.0-110, Node 20.20.2, Python 3.12.3.