Skip to main content
Interactive setup wizard that detects your project type, generates CA certificates, creates a cordon.toml config file, and provides language-specific trust guidance.

​
Usage

cordon setup [OPTIONS]
cordon setup INTEGRATION [OPTIONS]

​
Options

OptionDescription
--yesSkip confirmation prompts (useful for automation and non-interactive setup)
--regenerate-caRegenerate the CA certificate
--trustAdd CA to system trust store
--no-trustSkip trust store prompt

​
Examples

# Interactive setup
cordon setup

# Non-interactive setup with trust
cordon setup --yes --trust

​
Project setup and services

Cordon is project-based. Each project has its own cordon.toml with its own routes and secrets — there is no global config or shared route table. This means route policy travels with the project and can be reviewed, version-controlled, and shared with teammates like any other project file.
The config file references secrets by name (e.g., a 1Password vault/item or a keyring account), not by value. Sharing cordon.toml via version control only works if each teammate’s secret store uses the same names. For local development setups where each developer manages their own secrets, you may want to gitignore cordon.toml and let each developer run cordon setup independently.
cordon setup writes ./cordon.toml in the current directory and stores generated certificates under ~/.config/cordon/projects/<namespace>/certs/. This keeps route policy with the project while keeping certificate material out of the project tree so it is not accidentally committed or deleted during normal project cleanup. Setup does not install a background service. To run cordon as a launchd/systemd service for a project, install the service explicitly after setup: 
cordon service install --name my-project --config ./cordon.toml
See process management for more on running cordon as a service.

​
Integration subcommands

Integrations configure cordon for a specific tool — setting up the proxy env vars and CA trust settings that the tool needs. Each integration knows where its target stores configuration (e.g., settings.json for Claude Code, ~/.codex/.env for Codex, ~/.hermes/.env for Hermes) and handles setup and teardown automatically. Currently supported: claude-code, codex, cursor, hermes.
Cordon currently works with API key authentication only. If you use Claude Code or Codex with a subscription-based OAuth login (e.g., Claude Pro/Team or ChatGPT Plus), credential injection won’t apply — those tools authenticate directly with their provider’s OAuth flow, bypassing the proxy’s auth injection. API key support is coming soon for OAuth-based subscriptions.

​
cordon setup claude-code

Configure cordon for Claude Code. Runs the base setup automatically, then generates a combined CA bundle and writes proxy env vars to Claude Code’s settings.json. 
cordon setup claude-code

# Remove the setup
cordon setup claude-code --remove
OptionDescription
--removeRemove the cordon setup
--yesSkip confirmation prompts (useful for automation and non-interactive setup)
--trustAdd the CA cert to the OS trust store
--no-trustSkip trust store prompt
--regenerate-caRegenerate the CA certificate

​
cordon setup codex

Configure cordon for OpenAI Codex. Runs the base setup automatically, then writes proxy env vars to Codex’s ~/.codex/.env. 
cordon setup codex

# Remove the setup
cordon setup codex --remove
OptionDescription
--removeRemove the cordon setup
--yesSkip confirmation prompts (useful for automation and non-interactive setup)
--trustAdd the CA cert to the OS trust store
--no-trustSkip trust store prompt
--regenerate-caRegenerate the CA certificate
Codex uses reqwest with rustls for HTTP/TLS. Setup generates a combined CA bundle (system CAs + Cordon CA) and sets SSL_CERT_FILE, REQUESTS_CA_BUNDLE, and CURL_CA_BUNDLE to point at it.
Codex filters out CODEX_* prefixed variables from its .env file, so the setup uses SSL_CERT_FILE instead of CODEX_CA_CERTIFICATE. The CODEX_HOME env var can override the default ~/.codex/ path.

​
cordon setup cursor

Configure cordon for Cursor. Runs the base setup automatically, then writes proxy settings to Cursor’s settings.json. 
cordon setup cursor

# Remove the setup
cordon setup cursor --remove
OptionDescription
--removeRemove the cordon setup
--yesSkip confirmation prompts (useful for automation and non-interactive setup)
--trustAdd the CA cert to the OS trust store
--no-trustSkip trust store prompt
--regenerate-caRegenerate the CA certificate
Cursor is built on VS Code (Electron/Node.js). Setup configures http.proxy for VS Code’s built-in proxy agent, generates a combined CA bundle, and sets terminal env vars (HTTPS_PROXY, HTTP_PROXY, NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE) via the platform-specific terminal.integrated.env setting.
This integration proxies traffic from tools running inside Cursor (terminal, extensions, MCP servers, tasks) — not Cursor’s own AI calls, which use subscription auth via *.cursor.sh. For the main Cursor process to trust the CA, run cordon trust to add it to the system trust store.

​
cordon setup hermes

Configure cordon for Hermes Agent. Runs the base setup automatically, then builds a combined CA bundle and writes proxy env vars to Hermes’s ~/.hermes/.env. 
cordon setup hermes

# Remove the setup
cordon setup hermes --remove
OptionDescription
--removeRemove the cordon setup
--yesSkip confirmation prompts (useful for automation and non-interactive setup)
--trustAdd the CA cert to the OS trust store
--no-trustSkip trust store prompt
--regenerate-caRegenerate the CA certificate
Hermes uses Python’s httpx library, which honors HTTPS_PROXY by default. Setup generates a combined CA bundle (system CAs + Cordon CA) because Python’s SSL_CERT_FILE replaces the default cert store rather than appending to it. REQUESTS_CA_BUNDLE is also set for the requests library.
The HERMES_HOME env var can override the default ~/.hermes/ path. If the directory doesn’t exist, setup will warn but still write the .env file.

​
What setup does

Running cordon setup without an integration performs the base setup only:
  1. Checks platform dependencies — verifies that secret providers can function at runtime (e.g., D-Bus session on Linux for keyring, 1Password CLI sign-in status). Issues are reported as [!] warnings but do not block setup.
  2. Detects the project type and language ecosystem
  3. Generates CA certificates at ~/.config/cordon/projects/<namespace>/certs/
  4. Detects available secret providers and adds them to the config (OS Keyring, 1Password CLI)
  5. Creates cordon.toml with absolute cert paths
  6. Provides language-specific trust guidance (e.g., NODE_EXTRA_CA_CERTS for Node.js)
If you’re using Claude Code, Codex, or Hermes, use the integration subcommands instead — they run the base setup automatically and then configure the tool’s proxy settings in one step.
Node.js does not use the system trust store. You must also set NODE_EXTRA_CA_CERTS to the absolute path of your CA certificate (found in cordon.toml under tls.ca_cert_path).

​
What --remove does

The --remove flag reverses an integration setup, not cordon itself. It removes the settings that the integration wrote, but intentionally keeps the generated CA files and cordon.toml so you can re-enable the integration without rotating certificates.
CommandCreates / modifiesRemoves
cordon setupCA cert + key, cordon.toml—
cordon setup claude-codeCA cert + key, cordon.toml, Claude Code settings.json env vars—
cordon setup claude-code --remove—Claude Code settings.json env vars
cordon setup claude-code --remove --trust—Claude Code settings.json env vars + CA from system trust store
cordon setup codexCA cert + key, cordon.toml, Codex ~/.codex/.env env vars—
cordon setup codex --remove—Codex .env env vars
cordon setup cursorCA cert + key, cordon.toml, Cursor settings.json proxy + terminal env vars—
cordon setup cursor --remove—Cursor settings.json proxy + terminal env vars
cordon setup hermesCA cert + key, cordon.toml, combined CA bundle, Hermes ~/.hermes/.env env vars—
cordon setup hermes --remove—Hermes .env env vars + combined CA bundle
cordon trustAdds CA to system trust store—
cordon untrust—CA from system trust store
cordon service uninstall --name <name>—launchd plist / systemd unit
cordon setup --regenerate-caReplaces existing CA cert + keyOld cert + key
This retention is intentional and matches tools like mkcert and Caddy: uninstalling an integration should not silently delete reusable certificate material.
If you run --regenerate-ca and the old CA was already trusted, rerun cordon trust after setup. Regeneration replaces the certificate files, but it does not automatically update the system trust store to trust the new CA.

​
Certificate storage

Certificates are stored outside your project directory, so they are not at risk of being committed to git with your app code.
ScopePath
Project setup~/.config/cordon/projects/<namespace>/certs/
The <namespace> is derived from your project directory: <dirname>-<short hash> (e.g., my-app-a1b2c3d4). The hash is the first 8 hex characters of the SHA-256 of the absolute path, so two projects named my-app in different locations get separate cert stores. The CA private key is written with 0600 permissions (owner-only read/write).
The CA private key is only useful for interception where the CA is still trusted, whether through the system trust store or an app-specific trust configuration such as NODE_EXTRA_CA_CERTS or a custom Java trust store.

​
Multiple projects

Each project gets its own cordon.toml with its own listen port, routes, and certificate namespace. If you run Cordon in multiple projects simultaneously, each instance must listen on a different port: 
# ~/project-a/cordon.toml
listen = 6790

# ~/project-b/cordon.toml
listen = 6791
Certificate namespaces are derived from the project directory path, so two projects with the same directory name in different locations get separate cert stores automatically. If you install background services for multiple projects, use distinct --name values: 
cd ~/project-a && cordon service install --name project-a --config ./cordon.toml
cd ~/project-b && cordon service install --name project-b --config ./cordon.toml

​
Removal recipes

To remove an integration for the current project: 
cordon setup claude-code --remove
cordon setup codex --remove
cordon setup cursor --remove
cordon setup hermes --remove
To remove cordon itself from a machine after any integrations are gone: 
# Remove CA from the system trust store, if present
cordon untrust --config /path/to/cordon.toml

# Remove any installed services
cordon service uninstall --name my-project
cordon service uninstall                      # if installed with the default service name

# Delete cordon-managed data
rm -rf ~/.config/cordon/
If you’ve already deleted cordon.toml and the cert files, cordon untrust won’t be able to locate the CA to remove. In that case, remove it manually — on macOS, open Keychain Access and search for “cordon”; on Linux, remove the cert from /usr/local/share/ca-certificates/ and run update-ca-certificates.