Any tool (generic)

Cordon ships dedicated integrations for Claude Code, Codex, Hermes, and OpenClaw. For anything else — a Next.js app, a Python service, a Go binary, a shell script — you route traffic through cordon by setting a handful of environment variables. This guide documents that contract.

The env-var contract

Cordon terminates TLS locally, which requires the calling process to:

Send HTTP(S) traffic through the Cordon proxy URL from cordon env, and
Trust the cordon CA so the terminated TLS handshakes validate.

The env vars below express both. They are the same vars every cordon integration sets under the hood — there is nothing special about “generic” mode.

Variable	Value	Why
`HTTPS_PROXY` / `HTTP_PROXY`	`http://<audience>:<token>@127.0.0.1:<port>` when token enforcement is active; `http://127.0.0.1:<port>` only when inactive	Most HTTP clients honor these. `<audience>` is the local Cordon scope namespace and `<port>` comes from `listen` in `cordon.toml`.
`https_proxy` / `http_proxy`	same	lowercase variants — required by a handful of tools (curl on some distros, wget, some Python libs).
`NODE_EXTRA_CA_CERTS`	absolute path to `ca-cert.pem`	Node.js-specific. Node expects a raw cert, not a bundle.
`SSL_CERT_FILE`	absolute path to `combined-ca.pem`	Used by OpenSSL, curl, Go. These vars replace the default trust store, so they need a bundle (system CAs + cordon CA) — a raw cert alone would lose every other trust anchor.
`REQUESTS_CA_BUNDLE`	same combined bundle	Python `requests` library.
`CURL_CA_BUNDLE`	same combined bundle	curl.

The combined bundle (combined-ca.pem) is generated at setup time by concatenating your system CA trust store with the cordon CA. Runtime-specific exceptions are covered in SDK Compatibility. Tokenized proxy URLs are sensitive local configuration; do not commit them or paste them into logs and shared chats. In tokenized proxy URLs, <audience> is Cordon’s local token audience: user for the user scope or a project namespace such as myapp-a1b2c3d4. This is not an OAuth/OIDC audience claim; it is a local guardrail that helps Cordon reject a token presented to the wrong Cordon daemon.

Getting the values

You don’t derive these by hand. cordon env prints them for the current scope’s cordon.toml:

cordon env

Output (shell format, default):

export HTTPS_PROXY='http://myapp-a1b2c3d4:<token>@127.0.0.1:6790'
export HTTP_PROXY='http://myapp-a1b2c3d4:<token>@127.0.0.1:6790'
export https_proxy='http://myapp-a1b2c3d4:<token>@127.0.0.1:6790'
export http_proxy='http://myapp-a1b2c3d4:<token>@127.0.0.1:6790'
export NODE_EXTRA_CA_CERTS='/Users/you/.config/cordon/projects/myapp-a1b2c3d4/certs/ca-cert.pem'
export SSL_CERT_FILE='/Users/you/.config/cordon/projects/myapp-a1b2c3d4/certs/combined-ca.pem'
export REQUESTS_CA_BUNDLE='/Users/you/.config/cordon/projects/myapp-a1b2c3d4/certs/combined-ca.pem'
export CURL_CA_BUNDLE='/Users/you/.config/cordon/projects/myapp-a1b2c3d4/certs/combined-ca.pem'

See cordon env for the full command reference (fish, dotenv, and json formats, and the --scope flag).

Applying them

Pick whichever fits your workflow.

Current shell (bash / zsh)

eval "$(cordon env)"

fish

cordon env --format fish | source

direnv (`.envrc`)

eval "$(cordon env)"

Reload with direnv allow after adding. Traffic from commands run in that directory flows through cordon.

mise (`.mise.toml`)

cordon env --format dotenv > .mise.cordon.env

Then reference _.file = ".mise.cordon.env" in your .mise.toml.

dotenv (`.env`)

cordon env --format dotenv >> .env

Programmatic / CI

cordon env --format json

Pipe into jq or parse with your language’s JSON library. The output is a flat object of environment variable names to string values, so scripts can safely export every top-level entry.

Verifying it works

With the env vars exported and cordon running (cordon start), make a request to a host you’ve configured a route for:

curl -v https://api.stripe.com/v1/charges

Expect a response from the real API with cordon injecting the Authorization header on its way out. If TLS verification fails, see TLS troubleshooting. Run cordon doctor if anything feels off.

When to use which scope

cordon env (default, --scope project) reads ./cordon.toml. Use this when you have a per-project setup.
cordon env --scope user reads ~/.config/cordon/cordon.toml. Use this for a user-wide cordon instance shared across projects.

Scopes map to separate daemons with separate ports — see Scopes for the reference.

Getting Started

Configuration

Guides

CLI Reference

Security

Any tool (generic)

The env-var contract

Getting the values

Applying them

Current shell (bash / zsh)

fish

direnv (`.envrc`)

mise (`.mise.toml`)

dotenv (`.env`)

Programmatic / CI

Verifying it works

When to use which scope

​The env-var contract

​Getting the values

​Applying them

​Current shell (bash / zsh)

​fish

​direnv (.envrc)

​mise (.mise.toml)

​dotenv (.env)

​Programmatic / CI

​Verifying it works

​When to use which scope

The env-var contract

Getting the values

Applying them

Current shell (bash / zsh)

fish

direnv (`.envrc`)

mise (`.mise.toml`)

dotenv (`.env`)

Programmatic / CI

Verifying it works

When to use which scope