> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codezero.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agent

> Set up cordon to give Hermes Agent secure API access without exposing secrets.

Cordon integrates with [Hermes Agent](https://hermes-agent.nousresearch.com/) so your AI agent can make authenticated API calls without holding real credentials.

## Scope

Hermes setup only supports **user scope** — Hermes operates across projects, so `cordon setup hermes --scope project` is rejected by the CLI. User scope stores config at `$XDG_CONFIG_HOME/cordon/cordon.toml` and writes proxy env vars to `$HERMES_HOME/.env` (or `~/.hermes/.env`). A single cordon instance handles credential injection regardless of which project Hermes is working in.

See [Scopes](/configuration/overview#scopes) for path details and trade-offs.

## Automated setup

The fastest way to get started:

```bash theme={null}
cordon setup hermes
```

This:

1. Generates CA certificates (if not already present)
2. Creates a scaffold `cordon.toml`
3. Writes the standard proxy and CA env vars from `cordon env --scope user` to Hermes's `~/.hermes/.env`
4. Installs a cordon agent skill to `~/.hermes/skills/devops/cordon/SKILL.md`

Your existing `.env` is backed up to `.env.cordon.bak` before any changes are made.

To run cordon as a background service, run `cordon service install --scope user` after setup.

### Remove the setup

```bash theme={null}
cordon integration disable hermes
```

## Adding routes

After setup, add a route for your LLM provider with [`cordon route add --scope user`](/cli/route) and, if using the keyring secret source, store the credential with [`cordon secret set`](/cli/secret). Hermes is user-scope only, so pass `--scope user` to `cordon route`, `cordon start`, and `cordon service` commands.

<Warning>
  Anthropic uses `type: header` with `header_name: x-api-key` and no `scheme`. Using an `Authorization` header will result in 401 errors.
</Warning>

## Provider auto-detection

Hermes uses env vars to auto-detect which LLM provider to use. Since cordon injects the real API key at the network layer, Hermes still needs a dummy key to select the right provider. Add a placeholder to `~/.hermes/.env`:

```bash theme={null}
# Hermes sees this and selects the Anthropic provider.
# Cordon strips it and injects the real key from the keychain.
ANTHROPIC_API_KEY=dummy-replaced-by-cordon
```

Without this, Hermes won't know which provider to use and will fail to make API calls even though cordon has the real credentials ready to inject.

## Manual setup

Prefer `cordon setup hermes` for Hermes configuration. It writes the proxy and CA settings, generates the combined CA bundle, and backs up the existing `.env` before changing it. If setup cannot cover your environment, copy the values from [`cordon env --scope user`](/cli/env) to `~/.hermes/.env`:

```bash theme={null}
HTTPS_PROXY="http://127.0.0.1:<PORT>"
SSL_CERT_FILE="/path/to/combined-ca.pem"
```

The `HERMES_HOME` env var can override the default `~/.hermes/` path if Hermes is installed in a non-standard location. See [Any tool (generic)](/guides/generic) for the full env-var contract.

## How it works

Hermes uses Python's `httpx` library for HTTP, which honors `HTTPS_PROXY` by default (`trust_env=True`). The OpenAI, Firecrawl, and Exa SDKs all use `httpx` or `requests` internally, and Hermes's own Tavily client uses `httpx` directly, so all HTTP traffic routes through cordon automatically. No code changes or monkeypatching required.

For Cordon's matched-route TLS behavior and certificate troubleshooting, see [TLS](/configuration/tls).

### Sandboxed environments

Hermes supports several sandboxed execution backends (`TERMINAL_ENV`): `docker`, `singularity`, `modal`, `daytona`, and `ssh`. These environments run in isolated network namespaces where `127.0.0.1` refers to the container's or remote host's loopback, not the developer's machine. The cordon proxy running on the host is not reachable from inside these sandboxes without network bridging.

For local execution (`TERMINAL_ENV=local`), cordon works out of the box. For sandboxed backends, network reachability varies by backend and has not been fully tested. Docker may reach the host via `host.docker.internal` on macOS/Windows, but other backends (Modal, Daytona, SSH) have their own networking models. A remote cordon proxy with network-accessible binding would be needed for full support (not yet available).

## Workflow

Once configured, the workflow is:

1. Start cordon: `cordon start --scope user` (or use the background service)
2. Start Hermes as usual
3. When Hermes makes API calls to configured hosts, cordon transparently injects credentials
4. Hermes never sees or logs real API keys

<Tip>
  Use `cordon doctor` to diagnose any setup issues. It checks config validity, cert paths, trust store status, and port availability.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="401 Unauthorized errors">
    1. **Wrong header config**: Anthropic uses `type: header` with `header_name: x-api-key` and no `scheme`. Check your `cordon.toml` route configuration.
    2. **Missing dummy key**: Hermes won't select a provider without its API key env var set. Add `ANTHROPIC_API_KEY=dummy-replaced-by-cordon` to `~/.hermes/.env`.
    3. **Check the secret source**: HTTP route secrets are fetched per-request — if you changed a secret, the next request picks it up automatically.
    4. **Verify the secret is stored**: `cordon secret set anthropic`
  </Accordion>

  <Accordion title="Certificate errors">
    Verify `~/.hermes/.env` includes the CA bundle values from [`cordon env --scope user`](/cli/env), then follow [TLS troubleshooting](/configuration/tls#troubleshooting-certificate-errors).
  </Accordion>

  <Accordion title="Proxy not being used">
    Verify the env vars are in `~/.hermes/.env`:

    ```bash theme={null}
    cat ~/.hermes/.env
    ```

    Hermes loads this file at startup via `load_hermes_dotenv()`. If the file exists but Hermes isn't routing through the proxy, use the shared [proxy not running checks](/guides/process-management#proxy-not-running-checks) with `--scope user`.
  </Accordion>

  <Accordion title="Provider not detected">
    If Hermes can't determine which LLM provider to use, it's likely missing the dummy API key env var. Add the appropriate key to `~/.hermes/.env`:

    ```bash theme={null}
    ANTHROPIC_API_KEY=dummy-replaced-by-cordon    # for Anthropic
    OPENAI_API_KEY=dummy-replaced-by-cordon       # for OpenAI
    ```
  </Accordion>

  <Accordion title="Service restart required after config changes">
    Restart Cordon after adding or editing route definitions. See [Routes: route changes and secret rotation](/configuration/routes#route-changes-and-secret-rotation).
  </Accordion>
</AccordionGroup>