Claude Code

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.

​

Scope

cordon setup claude-code --scope user

​

Automated setup

cordon setup claude-code

1. Generates CA certificates (if not already present)
2. Creates a scaffold cordon.toml
3. Generates a combined CA bundle (system CAs + Cordon CA)
4. Configures Claude Code’s settings file (.claude/settings.local.json for project scope, ~/.claude/settings.json for user scope) with proxy env vars (HTTPS_PROXY, HTTP_PROXY, https_proxy, http_proxy, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE)
5. Installs a health-check hook that blocks Claude Code when cordon is not running
6. Installs a cordon agent skill (.claude/skills/cordon/SKILL.md for project scope, ~/.claude/skills/cordon/SKILL.md for user scope)
7. Offers to add routes and store secrets interactively (post-setup wizard)

​

Remove the setup

cordon integration disable claude-code

​

Sandbox configuration (macOS)

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowLocalBinding": true
    }
  }
}

• 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 permits sandboxed processes to connect to loopback addresses, where cordon listens.

​

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

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "enableWeakerNetworkIsolation": true,
    "network": {
      "allowLocalBinding": true
    }
  }
}

​

Adding routes

cordon route add

cordon route add --host api.github.com --auth-type bearer --source keyring --account github

cordon secret set <account>

​

API key setup

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

​

Manual setup

export HTTPS_PROXY=http://127.0.0.1:<PORT>
export HTTP_PROXY=http://127.0.0.1:<PORT>
export https_proxy=http://127.0.0.1:<PORT>
export http_proxy=http://127.0.0.1:<PORT>
export NODE_EXTRA_CA_CERTS=./ca-cert.pem
export SSL_CERT_FILE=/path/to/combined-ca.pem
export REQUESTS_CA_BUNDLE=/path/to/combined-ca.pem
export CURL_CA_BUNDLE=/path/to/combined-ca.pem

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

​

Combined CA bundle

1. Your system CA certificates (e.g., from /etc/ssl/cert.pem)
2. The Cordon proxy CA certificate

• SSL_CERT_FILE — used by Python’s ssl module and OpenSSL-based tools
• REQUESTS_CA_BUNDLE — used by Python’s requests library (does not read SSL_CERT_FILE)
• CURL_CA_BUNDLE — used by curl and libcurl-based tools
• NODE_EXTRA_CA_CERTS — used by Node.js (appends to built-in CAs, so it points to just the Cordon CA cert, not the combined bundle)

​

Trust the CA

tls: failed to verify certificate: x509: certificate signed by unknown authority

cordon trust

​

Workflow

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

​

Health-check hook

​

What you see when cordon is down

Cordon proxy is not running. Please start it, or remove the integration to continue without it.

​

Recovery options

​

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

tls: failed to verify certificate: x509: certificate signed by unknown authority

tls: failed to verify certificate: OSStatus -26276

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "enableWeakerNetworkIsolation": true,
    "network": {
      "allowLocalBinding": true
    }
  }
}

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

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

cordon status
# Replace <PORT> with the listen port from your cordon.toml
curl http://127.0.0.1:<PORT>/health

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "network": {
      "allowLocalBinding": true
    }
  }
}

{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "@some/mcp-server"],
      "env": {
        "NODE_OPTIONS": "--import @codezero-io/cordon/register"
      }
    }
  }
}

npm install @codezero-io/cordon

{
  "env": {
    "NODE_OPTIONS": "--import @codezero-io/cordon/register"
  }
}

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

# If running as a service
cordon service stop && cordon service start