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

​
Automated setup

The fastest way to get started: 
cordon setup hermes
This:
  1. Generates CA certificates (if not already present)
  2. Creates a scaffold cordon.yaml
  3. Generates a combined CA bundle (system CAs + Cordon CA)
  4. Writes proxy env vars to Hermes’s ~/.hermes/.env (HTTPS_PROXY, HTTP_PROXY, SSL_CERT_FILE, REQUESTS_CA_BUNDLE)
Your existing .env is backed up to .env.cordon.bak before any changes are made.

​
Global setup with background service

To install cordon as a background service that starts automatically: 
cordon setup hermes --global
This additionally installs a launchd (macOS) or systemd (Linux) service so cordon runs in the background without a terminal window.

​
Remove the setup

cordon setup hermes --remove           # project-scoped
cordon setup hermes --remove --global  # global (also removes background service)

​
Adding routes

After setup, edit cordon.yaml to add routes for your LLM provider. Example for Anthropic: 
routes:
  - name: anthropic
    match:
      host: api.anthropic.com
    auth:
      type: api_key
      header_name: x-api-key
      secret:
        source: keyring
        account: anthropic
Then store the secret: 
cordon secret set anthropic --config /path/to/cordon.yaml
Anthropic uses type: api_key with header_name: x-api-key, not type: bearer. Using the wrong auth type 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

If you prefer manual configuration, add these to ~/.hermes/.env: 
HTTPS_PROXY="http://127.0.0.1:6790"
HTTP_PROXY="http://127.0.0.1:6790"
SSL_CERT_FILE="/path/to/combined-ca.pem"
REQUESTS_CA_BUNDLE="/path/to/combined-ca.pem"
You must create a combined CA bundle manually if not using cordon setup hermes. Concatenate your system CA bundle with the Cordon CA cert — see Combined CA bundle below.
The HERMES_HOME env var can override the default ~/.hermes/ path if Hermes is installed in a non-standard location.

​
How it works

Hermes uses Python’s httpx library for HTTP, which honors HTTPS_PROXY by default (trust_env=True). The OpenAI SDK, Firecrawl, Tavily, and Exa SDKs all use httpx or requests internally, so all HTTP traffic routes through cordon automatically. No code changes or monkeypatching required. Cordon only MITMs connections to hosts with matching routes. All other traffic passes through as a transparent CONNECT tunnel — the upstream server’s real certificate is presented to the client, and no CA bundle configuration is needed for those connections.

​
Combined CA bundle

Python’s SSL_CERT_FILE replaces the default certificate store rather than appending to it. This means setting SSL_CERT_FILE to just the Cordon CA cert would break TLS for all non-proxied connections (the system CAs would be missing). To solve this, cordon setup hermes generates a combined CA bundle that concatenates:
  1. Your system CA certificates (e.g., from /etc/ssl/cert.pem)
  2. The Cordon proxy CA certificate
This combined bundle is written next to the Cordon CA cert (e.g., combined-ca.pem) and both SSL_CERT_FILE and REQUESTS_CA_BUNDLE point to it. REQUESTS_CA_BUNDLE is set separately because Python’s requests library does not read SSL_CERT_FILE — it has its own env var.
This is different from the Codex integration, where SSL_CERT_FILE points directly to the Cordon CA cert. Codex uses Rust’s rustls, which adds custom CAs on top of the system trust store rather than replacing it.

​
Sandboxed environments

Hermes supports Docker, Modal, and SSH sandboxed execution backends. These environments run in isolated network namespaces where 127.0.0.1 refers to the container’s loopback, not the host. The cordon proxy running on the host is not reachable from inside these sandboxes without network bridging. For local development (TERMINAL_ENV=local), cordon works out of the box. For sandboxed backends, a remote cordon proxy with network-accessible binding would be needed (not yet supported).

​
Workflow

Once configured, the workflow is:
  1. Start cordon: cordon start (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

​
401 Unauthorized errors

  1. Wrong auth type: Anthropic uses type: api_key with header_name: x-api-key, not type: bearer. Check your cordon.yaml 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. Stale secret: Secrets are resolved at cordon startup. If you changed the secret, restart cordon.
  4. Verify the secret is stored: cordon secret set anthropic --config /path/to/cordon.yaml

​
Certificate errors

If you see SSL/TLS errors:
  1. Verify the combined CA bundle exists and is readable: 
    cat ~/.hermes/.env | grep SSL_CERT_FILE
ls -la "$(cat ~/.hermes/.env | grep SSL_CERT_FILE | cut -d'"' -f2)"
  2. Verify the bundle contains both system CAs and the Cordon CA: 
    grep -c "BEGIN CERTIFICATE" /path/to/combined-ca.pem  # should be many
grep "Cordon proxy CA" /path/to/combined-ca.pem       # should match
  3. If the combined bundle is missing, re-run cordon setup hermes to regenerate it.

​
Proxy not being used

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, ensure cordon is running: 
cordon status
curl http://127.0.0.1:6790/health

​
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: 
ANTHROPIC_API_KEY=dummy-replaced-by-cordon    # for Anthropic
OPENAI_API_KEY=dummy-replaced-by-cordon       # for OpenAI

​
Service restart required after config changes

Cordon resolves secrets eagerly at startup. If you add or change routes, secrets, or the cordon.yaml config, restart the proxy: 
# If running as a service
cordon service stop hermes && cordon service start hermes

# If running manually
# Ctrl+C the running process, then:
cordon start