--- title: How to Run a Hermes Agent on DigitalOcean Harness Runtime (public) description: Run the Hermes gateway as a long-lived agent inside a Harness Runtime sandbox and reach its admin dashboard from your machine. product: Managed Agents url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/run-hermes-agent/ last_updated: "2026-10-06" --- > **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document). # How to Run a Hermes Agent on DigitalOcean Harness Runtime (public) DigitalOcean Harness Runtime provides managed, hardware-isolated microVM sandboxes with built-in tools such as Chromium to run harnesses and execute arbitrary code. Rich lifecycle APIs preserve conversational history and working state across sessions, letting you pause, resume, and fork work to control costs and adapt to the nonlinear nature of agentic workflows. Scale complete agents such as Claude Code or use sandboxes independently for code execution, all through the same service. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases. Managed Agents supports Hermes as an agent kind. Unlike the coding adapters, the Hermes gateway is a long-lived process that the sandbox template starts once and supervises there. The harness connects to that process rather than spawning an agent per turn. You use Hermes when you want the gateway experience (long-lived, dashboard, session-per-attach) rather than a coding-agent adapter. Hermes ships a web admin UI that starts by default, bound to loopback inside the sandbox on port `9119`. `doctl harness-runtime port-forward` is the access path to the dashboard. ## Write the Environment Spec Create `hermes-agent.yaml`: ```yaml name: my-hermes-agent agent: hermes size: mars-2vcpu-4gb env: HARNESS_INFERENCE_MODEL: "" secrets: HARNESS_INFERENCE_API_KEY: ${HARNESS_INFERENCE_API_KEY} permissions: default: ask ``` Export the inference API key so `doctl` can use it in `${HARNESS_INFERENCE_API_KEY}` before upload: ```shell export HARNESS_INFERENCE_API_KEY= ``` The spec has the following fields and environment variables: - `agent` (required): Must be `hermes`. - `HARNESS_INFERENCE_API_KEY` (required): API key for the inference endpoint. Declare it under `secrets`, never under `env`. Without it, the gateway logs a warning at boot and the first turn fails. - `HARNESS_INFERENCE_MODEL` (required): Model name to request from that endpoint. Non-secret. - `template` (optional): Leave unset. The platform derives `coding-hermes` automatically. - `size`, `name`, `permissions`, `repos`, `tools`, `egress` (optional): Same as the other coding adapters. At boot, Harness Runtime renders the resolved model, base URL, and API key into the gateway configuration file before the gateway starts. **Note**: If you set `OPENAI_API_KEY`, it takes precedence over `HARNESS_INFERENCE_API_KEY`, and `OPENAI_BASE_URL` and `OPENAI_MODEL` are read alongside it. Both paths work, but use `HARNESS_INFERENCE_*` so your Hermes spec stays consistent with LangGraph. ## Validate and Start the Session Validate the spec before you run it: ```shell doctl harness-runtime validate --spec ./hermes-agent.yaml ``` The command warns when no model is configured. Start the session: ```shell doctl harness-runtime launch ./hermes-agent.yaml ``` When the session is ready, `launch` attaches it to your terminal. Similar to the other adapters, tool calls, reasoning output, streamed replies, human-in-the-loop approvals, and cancellation all surface through attach. Answer approval prompts in the terminal with `Enter` or `y`, or reject with `n`. To resolve a pending approval without attaching, run: ```shell doctl harness-runtime approve approve ``` Replace `approve` with `reject` or `defer` as needed. Detach the session with `Ctrl+D`. The session stays alive until you pause or remove it. To attach again after you detach, run: ```shell doctl harness-runtime launch ``` ## Reach the Hermes Dashboard The Hermes dashboard is bound to `127.0.0.1:9119` inside the sandbox and is not published to the public internet. Open it with a `doctl` port forward in a second terminal: ```shell doctl harness-runtime port-forward 9119 ``` The output looks like this: ```text Forwarding 127.0.0.1:9119 -> port 9119 in session Ready. Press Ctrl-C to stop. ``` Then, open `http://127.0.0.1:9119` in a browser. The dashboard is bound to loopback inside the sandbox, so the tunnel is the only way in and nothing is published to the internet. Keep the `port-forward` command running while you use the dashboard. Stop it with `Ctrl+C`. For remap options, bind address, and commands, see [Forward Sandbox Ports](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/forward-ports/index.html.md). ## Troubleshoot Hermes Sessions Use this table to diagnose common Hermes errors: | Symptom | Likely cause | What to do | |---|---|---| | `validate` warns “no model configured” | `HARNESS_INFERENCE_*` variables missing | Set `HARNESS_INFERENCE_API_KEY` and `HARNESS_INFERENCE_MODEL` in the spec. | | First turn fails with auth error | API key not resolved into the guest | Confirm the key is declared under `secrets` (not `env`) and that `${HARNESS_INFERENCE_API_KEY}` is exported in your shell before create. | | Dashboard does not load at `127.0.0.1:9119` | `port-forward` not running, or wrong session | Start `doctl harness-runtime port-forward 9119` in a separate terminal and keep it running. | | Model responds from the wrong endpoint | `OPENAI_*` variables set unintentionally | Remove `OPENAI_API_KEY`, `OPENAI_BASE_URL`, and `OPENAI_MODEL` from the spec so the `HARNESS_INFERENCE_*` values apply. | | Session create fails on name | Session name already in use | Remove the old session or change `name`. |