Claude Code

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

Cordon can inject an ANTHROPIC_API_KEY for Claude’s API access, but this requires adding a route for api.anthropic.com and setting a dummy ANTHROPIC_API_KEY env var — see API key setup. If you use Claude Code with a Claude Pro/Team/Enterprise subscription (OAuth login), Anthropic API credential injection won’t apply — Claude Code authenticates directly via OAuth, bypassing the proxy. This limitation applies only to Claude’s own authentication; cordon supports header and basic auth types for routes to other APIs. Support for OAuth-based subscriptions is coming soon.

Scope

Claude Code setup defaults to project scope: cordon.toml lives in $CWD, and settings are written to $CWD/.claude/settings.local.json. This keeps credentials and proxy configuration isolated per repository and per checkout — settings.local.json is Claude Code’s gitignored-by-convention override file, so git worktrees do not inherit stale proxy env vars from a tracked settings.json. To share a single cordon configuration across all projects, use user scope:

cordon setup claude-code --scope user

User scope writes settings to $HOME/.claude/settings.json and stores config at $XDG_CONFIG_HOME/cordon/cordon.toml. See Scopes for path details and trade-offs.

Automated setup

The fastest way to get started:

cordon setup claude-code

This:

Generates CA certificates (if not already present)
Creates a scaffold cordon.toml
Generates the standard proxy and CA env vars from cordon env
Configures Claude Code’s settings file (.claude/settings.local.json for project scope, ~/.claude/settings.json for user scope) and adds NODE_OPTIONS when the Node bootstrap loader is discoverable
Installs a health-check hook that blocks Claude Code when cordon is not running
Installs a cordon agent skill (.claude/skills/cordon/SKILL.md for project scope, ~/.claude/skills/cordon/SKILL.md for user scope)
Offers to add routes and store secrets interactively (post-setup wizard)

Any existing settings file is backed up to <name>.cordon.bak before any changes are made. If setup detects cordon env vars in a project’s tracked settings.json (from a pre-fix install), they are migrated into settings.local.json automatically during the next cordon setup claude-code run. To run cordon as a background service, run cordon service install after setup (add --scope user if you set up Claude Code with --scope user).

Remove the setup

cordon integration disable claude-code

Sandbox configuration (macOS)

Claude Code runs tools in a macOS sandbox that manages proxy env var propagation to subprocesses. The sandbox must be enabled for HTTP_PROXY/HTTPS_PROXY env vars (set in your settings file) to reach tools like curl, wget, and gh. When the sandbox is disabled, these env vars are not propagated — requests bypass cordon entirely and no credential injection occurs. cordon setup claude-code configures these settings automatically. The resulting sandbox configuration in your Claude Code settings file (.claude/settings.local.json for project scope, ~/.claude/settings.json for user scope) looks like:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowLocalBinding": true,
      "allowedDomains": ["127.0.0.1"]
    }
  }
}

enabled: true activates the sandbox and its proxy env var propagation pipeline. Without this, subprocesses will not receive proxy env vars and cordon credential injection will silently fail.
autoAllowBashIfSandboxed: true allows Bash commands to run without individual permission prompts when the sandbox is active.
allowLocalBinding: true and allowedDomains: ["127.0.0.1"] permit sandboxed processes to connect to Cordon’s loopback listener.

Go-based tools (`gh`, `terraform`, `kubectl`, `gcloud`)

If you use Go-based CLI tools through Claude Code’s sandbox, you also need enableWeakerNetworkIsolation. Go binaries use Apple’s Security.framework for TLS certificate verification, which delegates to the trustd daemon via Mach IPC. The sandbox blocks this by default, causing OSStatus -26276 errors. This must be added manually — cordon setup claude-code does not set it by default because it reduces sandbox isolation.

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "enableWeakerNetworkIsolation": true,
    "network": {
      "allowLocalBinding": true,
      "allowedDomains": ["127.0.0.1"]
    }
  }
}

enableWeakerNetworkIsolation allows sandboxed processes to communicate with com.apple.trustd.agent. It is strictly more secure than disabling the entire sandbox with dangerouslyDisableSandbox: true, but it does reduce isolation by opening access to the system TLS trust service. Only add it if you need Go-based tools to work through the proxy. Users who only use curl, npm, or Node.js tools through the sandbox do not need enableWeakerNetworkIsolation.

Sandbox settings are applied when Claude Code launches. After changing these settings, you must restart Claude Code for them to take effect.

Adding routes

The cordon route, cordon start, and cordon service commands below default to project scope. If you set up Claude Code with --scope user, append --scope user to each of these commands so they target ~/.config/cordon/cordon.toml instead of ./cordon.toml.

After setup, add a route for your API provider. Claude Code’s own Anthropic API-key path uses x-api-key:

cordon route add --name anthropic --host api.anthropic.com \
  --auth-type header --header-name x-api-key \
  --source keyring --account anthropic-api-key

Anthropic uses a raw x-api-key header. For bearer-style APIs, set the Authorization header with a scheme. For example, to add a GitHub API route:

cordon route add --host api.github.com --auth-type header --header-name Authorization --scheme Bearer --source keyring --account github

If you chose keyring as the secret source, store the secret using the account name from the route:

cordon secret set <account>

See Routes for provider auth types, dummy-key behavior, and route change restart guidance.

API key setup

Claude Code needs an API key env var set so it selects the API key auth path. Add a placeholder to your settings file — .claude/settings.local.json for project scope or ~/.claude/settings.json for user scope:

{
  "env": {
    "ANTHROPIC_API_KEY": "dummy-replaced-by-cordon"
  }
}

Cordon strips this dummy key and injects the real one from your secret store at the network layer.

Manual setup

Prefer cordon setup claude-code for Claude Code configuration. It writes the proxy, CA, sandbox, and health-check settings consistently and backs up existing files before changing them. If setup cannot cover your environment, add the values from cordon env to Claude Code’s env settings. For project scope, write .claude/settings.local.json; for user scope, write ~/.claude/settings.json. The settings shape is:

{
  "env": {
    "HTTPS_PROXY": "http://127.0.0.1:<PORT>",
    "NODE_EXTRA_CA_CERTS": "/path/to/ca-cert.pem",
    "SSL_CERT_FILE": "/path/to/combined-ca.pem"
  }
}

Use Any tool (generic) for the full env-var contract, TLS for certificate errors, and SDK Compatibility for Node’s bootstrap loader.

Workflow

Once configured, the workflow is:

Start cordon: cordon start (or use the background service)
Start Claude Code as usual
When Claude Code makes API calls to configured hosts, cordon transparently injects credentials
Claude Code 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.

Health-check hook

When cordon setup claude-code runs, it installs a UserPromptSubmit hook that checks whether cordon is responding before every message you send. If cordon is configured but not running, the hook blocks the message and shows an error — preventing you from sitting through repeated ConnectionRefused retries with no explanation. The hook runs cordon status -q, a fast health check (50ms timeout with one retry) that exits 0 if cordon is healthy and 1 if not.

What you see when cordon is down

Cordon proxy is not running. Run `cordon start` or remove the hook.

The hook exits with code 2, which blocks the message. The ! prefix runs shell commands directly from Claude Code’s prompt without going through the AI — use it to start cordon or remove the integration even while the hook is blocking.

Recovery options

Option	Command	Notes
Start as service	`! cordon service start`	Requires prior `cordon service install`. Runs in background.
Start manually	`cordon start` (separate terminal)	Foreground process — keeps running until you Ctrl+C.
Remove integration	`! cordon integration disable claude-code --yes`	Removes proxy env vars, hook, and skill. Restart session with `claude --continue`.

Hooks are loaded when Claude Code starts. If you install or remove the hook mid-session, restart with claude --continue for the change to take effect.

Hook details

Project scope: script is installed at .claude/cordon-status-hook.sh in the project directory
User scope: script is installed at ~/.config/cordon/hooks/claude-code-status.sh
The hook entry is added to settings.local.json (project) or ~/.claude/settings.json (user) under hooks.UserPromptSubmit
The hook appends to existing hooks — it does not overwrite any UserPromptSubmit hooks you already have
Running setup again is idempotent — if the hook is already installed, it prints “Hook already installed” and moves on
cordon integration disable claude-code removes both the hook entry from settings and the script file
The hook script is scope-aware: if setup was given an explicit --config <path>, the hook passes --config <path> to cordon status -q. For user scope (without explicit config), it passes --scope user. This ensures the hook checks the correct cordon instance.

Troubleshooting

Cordon proxy is not running

This message comes from the health-check hook. It means cordon’s proxy env vars are set in your Claude Code settings, but cordon status -q could not reach the health endpoint.

Start cordon: type ! cordon service start in the Claude Code prompt, or run cordon start in another terminal
Check status: ! cordon status shows whether the proxy is running, stopped, or blocked by another process
Remove the integration: if you no longer want cordon for this project, type ! cordon integration disable claude-code --yes, then restart with claude --continue

Certificate errors

Claude Code uses the same proxy and CA env vars documented in cordon env. Check TLS troubleshooting, then verify those values are present in .claude/settings.local.json or ~/.claude/settings.json.

OSStatus -26276 / TLS failures in Go tools (macOS sandbox)

If Go-based tools (gh, terraform, kubectl, gcloud) fail with:

tls: failed to verify certificate: OSStatus -26276

This means Claude Code’s macOS sandbox is blocking com.apple.trustd.agent Mach IPC. Go uses Apple’s Security.framework for TLS certificate verification, which communicates with the trustd daemon. The sandbox blocks this by default.Add enableWeakerNetworkIsolation to your sandbox settings:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "enableWeakerNetworkIsolation": true,
    "network": {
      "allowLocalBinding": true,
      "allowedDomains": ["127.0.0.1"]
    }
  }
}

See Sandbox configuration for details and trade-offs. Restart Claude Code after changing sandbox settings.Python tools may also encounter TLS errors in the sandbox, but these are more commonly resolved by ensuring SSL_CERT_FILE and REQUESTS_CA_BUNDLE point to the combined CA bundle — see the Certificate errors accordion above.

Proxy not being picked up

Verify the env vars are in Claude Code’s settings file. Project scope writes .claude/settings.local.json; user scope writes ~/.claude/settings.json.

# Project scope
cat .claude/settings.local.json

# User scope
cat ~/.claude/settings.json

If the vars are set but Claude Code isn’t routing through the proxy, use the shared proxy not running checks.

Proxy env vars not reaching subprocesses (sandbox disabled)

If HTTP_PROXY/HTTPS_PROXY are set in your settings file but subprocesses (curl, wget, gh) don’t see them — requests go directly to the internet and cordon credential injection silently fails.Cause: The sandbox is disabled ("enabled": false or absent). Claude Code’s sandbox manages proxy env var propagation to subprocesses. When the sandbox is off, the proxy env vars from your settings file are not passed through, even though other env vars (like CA cert paths) may be.Diagnosis: Run env | grep HTTP_PROXY in a Claude Code Bash tool call. If the proxy vars are missing but CA cert vars are present, the sandbox is likely disabled.Fix: Ensure sandbox.enabled is true in your settings file:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowLocalBinding": true,
      "allowedDomains": ["127.0.0.1"]
    }
  }
}

Restart Claude Code after changing sandbox settings.

MCP servers not using the proxy

MCP servers launched by Claude Code inherit the env vars written by cordon setup claude-code. If a server is launched outside Claude Code, or its config replaces rather than inherits the parent environment, follow the MCP server guide.

Routes not appearing in cordon logs (Node.js)

Node.js built-in fetch needs the Cordon bootstrap loader. cordon setup claude-code sets this automatically when register.mjs is discoverable; otherwise follow SDK Compatibility: Node register import.

New routes not taking effect

Restart Cordon after adding or editing route definitions. See Routes: route changes and secret rotation.

401 Unauthorized errors

Verify the secret is stored: cordon secret set <account> (find the account name with cordon route show <name>)
Check the header: Anthropic uses type: header with header_name: x-api-key and no scheme
Check the secret source: HTTP route secrets are fetched per-request — if you changed a secret, the next request picks it up automatically

Getting Started

Configuration

Guides

CLI Reference

Security

Scope

Automated setup

Remove the setup

Sandbox configuration (macOS)

Go-based tools (`gh`, `terraform`, `kubectl`, `gcloud`)

Adding routes

API key setup

Manual setup

Workflow

Health-check hook

What you see when cordon is down

Recovery options

Hook details

Troubleshooting

Getting Started

Configuration

Guides

CLI Reference

Security

Documentation Index

​Scope

​Automated setup

​Remove the setup

​Sandbox configuration (macOS)

​Go-based tools (gh, terraform, kubectl, gcloud)

​Adding routes

​API key setup

​Manual setup

​Workflow

​Health-check hook

​What you see when cordon is down

​Recovery options

​Hook details

​Troubleshooting

Scope

Automated setup

Remove the setup

Sandbox configuration (macOS)

Go-based tools (`gh`, `terraform`, `kubectl`, `gcloud`)

Adding routes

API key setup

Manual setup

Workflow

Health-check hook

What you see when cordon is down

Recovery options

Hook details

Troubleshooting