5.1. Setting Up Hermes¶

Hermes is the container-based autonomous agent runtime in Backend.AI GO. The setup wizard walks you through seven steps to get from zero to a running agent. All of Hermes runs inside a container so nothing is installed on your host.

Prerequisites¶

Docker Desktop (macOS, Windows, Linux) or Apple Container (macOS arm64)
At least one model loaded in Backend.AI GO (needed for Step 5 — LLM bridge)
An internet connection to pull the Hermes image on first run

Opening the wizard¶

Open Backend.AI GO.
Click Autonomous Agents in the left sidebar.
Click Set up Hermes (or the provider card if Hermes is already listed).

The wizard opens and starts at Step 1. If you close it mid-way, it remembers your progress and resumes from the same step when you reopen it.

Wizard steps¶

Step 1 — Runtime check¶

The wizard detects whether a supported container runtime (Docker or Apple Container) is installed and responsive. If the runtime is missing, a link to the Docker Desktop download page is shown.

If this step shows an error:

Make sure Docker Desktop is running (look for the whale icon in the menu bar or taskbar).
On Linux, verify your user is in the docker group (sudo usermod -aG docker $USER, then log out and back in).
On Apple Silicon, you can alternatively install Apple Container instead of Docker Desktop.

Step 2 — Image pull¶

The Hermes container image is pulled from the registry. A progress bar shows per-layer download progress.

This step is idempotent — if the image is already up to date, the pull completes immediately without re-downloading.

If the pull fails:

Check your internet connection.
If you are behind a corporate proxy, configure Docker's proxy settings in Docker Desktop → Settings → Resources → Proxies.

Step 3 — Profile creation¶

Hermes keeps each agent's configuration, memory, and channels in a named profile. Enter a profile name here.

Name rules: lowercase letters, digits, hyphens, and underscores; 1 to 64 characters; must start with a letter or digit. Example: my-assistant.

The wizard creates the profile directory under <app data>/hermes/profiles/<name>/.

Step 4 — Channel selection¶

Choose which messaging platforms this profile will connect to (Slack, Telegram, etc.). You can leave all unchecked and add channels later from the Hermes dashboard.

Step 5 — LLM bridge¶

The LLM bridge tells Hermes which models to use for inference. The wizard automatically syncs the models currently loaded in Backend.AI GO to the Hermes daemon.

The wizard shows the router base URL Hermes will call and lists each model alongside a Synced / Pending badge. A successful sync turns all badges green.

If no models are listed, go to the Models page, load at least one model, and return to the wizard.

Step 6 — Claw migration (optional, may be skipped automatically)¶

If you have an existing Claw configuration at ~/.openclaw, this step offers to migrate memories, skills, and channel bindings to your new Hermes profile.

The wizard first runs a dry-run showing what would be migrated. Review the diff preview and click Apply to confirm.

This step is skipped automatically when:

The Claw gateway is not running, AND
No Claw configuration directory is detected, AND
The Claw provider has no managed channels.

Migration is non-destructive: the Claw configuration is mounted read-only and nothing is deleted from the Claw side.

Step 7 — Completion¶

The wizard summarizes what was set up and offers an Open dashboard button to navigate to the Hermes agent dashboard.

After setup¶

The Hermes gateway starts automatically when Backend.AI GO launches.
Open the Autonomous Agents page to see gateway status, channels, and connected models.
To change channel credentials or model assignments, use the Hermes dashboard or re-run the relevant wizard step.

Troubleshooting¶

The wizard gets stuck at "Runtime check"¶

The container runtime is not reachable. Common causes:

Docker Desktop is not running. Start it from the Applications folder (macOS/Windows) or run systemctl start docker (Linux).
On Linux, the socket at /var/run/docker.sock is not accessible. Run sudo chmod 666 /var/run/docker.sock as a temporary fix, or add yourself to the docker group permanently.

Image pull fails with "manifest unknown"¶

The pinned Hermes image tag may have been removed from the registry. Upgrade Backend.AI GO to the latest version, which will reference the correct tag.

Profile creation fails with "invalid name"¶

Profile names must match ^[a-z0-9][a-z0-9_-]{0,63}$. Avoid uppercase letters, spaces, and special characters other than - and _.

LLM bridge shows "No models loaded"¶

Load at least one model on the Models page before reaching Step 5. The bridge syncs whatever is loaded at the time the step is displayed.

Migration step shows an error about missing config¶

The wizard reported CLAW_CONFIG_NOT_FOUND. This means the path ~/.openclaw does not exist or is not a directory. If you have never used Claw, click Skip to proceed without migration.