Skip to main content

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.

Cordon integrates with Hermes Agent so your AI agent can make authenticated API calls without holding real credentials.

​
Scope

Hermes setup treats the default ~/.hermes/ profile as its own cordon project. It stores config at ~/.hermes/cordon.toml and writes proxy env vars to ~/.hermes/.env, so Hermes is isolated from unrelated repository configs while still working across projects. Hermes does not expose --scope, and setup rejects the generic user-scope config at ~/.config/cordon/cordon.toml. If you need follow-up commands such as cordon route, cordon start, cordon env, or cordon service, pass --config ~/.hermes/cordon.toml. Automated setup only supports the default profile in v1; HERMES_HOME must be unset or point at ~/.hermes. See Scopes for path details and trade-offs.

​
Automated setup

The fastest way to get started: 
cordon setup hermes
This:
  1. Generates CA certificates (if not already present)
  2. Creates a scaffold ~/.hermes/cordon.toml
  3. Writes the standard proxy and CA env vars from cordon env --config ~/.hermes/cordon.toml 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 --config ~/.hermes/cordon.toml after setup.

​
Remove the setup

cordon integration disable hermes

​
Adding routes

After setup, add a route for your LLM provider with cordon route add --config ~/.hermes/cordon.toml and, if using the keyring secret source, store the credential with cordon secret set. Pass --config ~/.hermes/cordon.toml to cordon route, cordon start, and cordon service commands so they target the Hermes config.
Anthropic uses type: header with header_name: x-api-key and no scheme. Using an Authorization header will result in 401 errors.

​
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: 
# 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 the default Hermes profile. 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 --config ~/.hermes/cordon.toml to the relevant Hermes .env file manually: 
HTTPS_PROXY="http://<audience>:<token>@127.0.0.1:<PORT>"
SSL_CERT_FILE="/path/to/combined-ca.pem"
Use the exact authenticated proxy URL from cordon env --config ~/.hermes/cordon.toml; do not hand-type or commit the tokenized URL. Automated setup does not write to custom HERMES_HOME locations in v1. See Any tool (generic) for the full env-var contract when configuring non-default profiles by hand.

​
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.

​
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 --config ~/.hermes/cordon.toml (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
Use cordon doctor to diagnose any setup issues. It checks config validity, cert paths, trust store status, and port availability.

​
Troubleshooting

  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
Verify ~/.hermes/.env includes the CA bundle values from cordon env --config ~/.hermes/cordon.toml, then follow TLS troubleshooting.
Verify the env vars are in ~/.hermes/.env:
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 with --config ~/.hermes/cordon.toml.
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:
ANTHROPIC_API_KEY=dummy-replaced-by-cordon    # for Anthropic
OPENAI_API_KEY=dummy-replaced-by-cordon       # for OpenAI
Restart Cordon after adding or editing route definitions. See Routes: route changes and secret rotation.