Skip to documentation
API + guides

01Documentation

Hosting Hermes

Run Hermes inside a Sandbox0 sandbox when you want sessions, memory, skills, and gateway state behind Sandbox0 lifecycle and network controls. A hermes template imports the upstream image; availability and image versions depend on your deployment. Check s0 template get hermes before claiming it.

Create The Sandbox#

Claim the template:

bash
SANDBOX_ID="$( s0 -o json sandbox create --template hermes \ | jq -r '.ID // .id' )" s0 sandbox get "$SANDBOX_ID"

Use the Sandbox Services API or an SDK claim configuration to expose the Hermes API as a cmd service. Enable auto_resume on the sandbox and resume: true on its route when incoming traffic should wake a paused runtime.

The commands above create a sandbox only. They do not configure or start a Hermes service. Sandbox0 starts procd rather than automatically running an imported image's Docker entrypoint. Configure the foreground gateway command, working directory, environment, and required initialization for the exact image you imported; do not assume its Docker supervisor is running.

For versions supporting Hermes' OpenAI-compatible API server, enable API_SERVER_ENABLED=true, select a service port with API_SERVER_PORT (normally 8642), and set API_SERVER_KEY in the service environment. The API binds to loopback by default; set API_SERVER_HOST=0.0.0.0 when needed for the service listener. Configure Hermes' model provider and tool backends before serving requests. Its gateway API and dashboard are distinct listeners.

Protect the Sandbox0 public route as well. If you use separate tokens, prefer Sandbox0 header auth with a dedicated header so the client's Authorization header can carry Hermes' own API key. Two different bearer tokens cannot both occupy the same Authorization header.

Persistence#

Keep Hermes workspace and configuration files on the writable RootFS, with HERMES_HOME explicitly set for the imported image (the upstream Docker image uses /opt/data). A completed pause checkpoints RootFS state to encrypted object storage and resume restores it before execution. Runtime-only mounts such as /tmp are excluded from filesystem-only checkpoints. Deleting the sandbox deletes that RootFS identity.

Create a named rootfs snapshot before deletion when you need to preserve or fan out an initialized Hermes workspace. A new sandbox can be claimed with the snapshot ID, or the current sandbox can be restored after it is paused. Snapshots remain subject to expiry and retention limits.

The default filesystem-only pause does not retain running Hermes processes or memory. Previously started cmd services can restart from their retained supervised session records. Matching public requests also create or restart the configured service when needed; a never-started service is not started merely because it appears in the service configuration. Explicit experimental memory pause/resume can retain supported process state. External clients must reconnect after either mode.

Next Steps#