Skip to main content

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.

Cordon can require a token before matched routes inject upstream credentials. This prevents an unrelated same-user process from connecting to the loopback proxy and receiving injected API credentials.

​
How it works

  • tokens.toml enables token enforcement for a scope.
  • Authenticated proxy URLs use HTTP Basic proxy auth: http://<audience>:<token>@127.0.0.1:<port>.
  • The Basic username 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 aud claim and does not provide third-party token attestation.
  • Matched HTTP and CONNECT routes require a valid Proxy-Authorization token when enforcement is active.
  • Unmatched forwarding does not require a token, but malformed, duplicate, or invalid Proxy-Authorization is still rejected while enforcement is active.
  • Missing tokens.toml preserves legacy behavior: matched routes remain unauthenticated and cordon start logs a warning.
  • If a running daemon has already observed tokens.toml, deleting the file does not silently reopen matched routes. Restart Cordon without tokens.toml if you intentionally want legacy unauthenticated mode.

​
Enable tokens

cordon setup creates tokens automatically — both base setup and integration setup (cordon setup claude-code, cordon setup codex, etc.) generate a tokens.toml with a default token. Integration setup additionally creates a client token and wires it into the tool’s proxy URL. The default token is the general-purpose proxy credential for a Cordon instance. Client tokens are named proxy credentials managed for configured clients such as Claude Code, Codex, Hermes, and OpenClaw. In the current token model, all valid tokens grant the same proxy access inside their local token audience; client tokens exist for independent rotation, revocation, setup/remove cleanup, and logging. Workload identity is verified separately. For existing setups created before token enforcement, re-run setup: 
# Re-run for a specific integration
cordon setup claude-code --yes
cordon setup codex --yes
cordon setup hermes --yes

# Or base setup for standalone usage
cordon setup --yes
eval "$(cordon env --config ./cordon.toml)"
Setup output redacts tokenized URLs. cordon env is the command intended to print full authenticated values for shells, dotenv files, direnv, or mise. Running daemons watch tokens.toml and pick up new, rotated, or revoked tokens on the next matched-route request. Restarting the daemon is still safe, but is not required for token-only changes.

​
Rotate tokens

cordon token rotate
cordon token rotate default
cordon token rotate claude-code
cordon token rotate --all
Omitting the token name rotates the default token. For supported clients (claude-code, codex, hermes, and openclaw), rotation updates the tool’s tokenized proxy URL before writing the new token file. Restart any already-running tool process that inherited the old URL. The daemon picks up the new token file automatically.

​
Revoke client tokens

cordon token revoke codex
For supported clients, revoke removes matching tokenized proxy settings after removing the token from tokens.toml. The daemon picks up the revocation automatically.

​
JSON output

cordon env --format json remains a flat object of environment variable names to string values. Existing scripts that read .HTTPS_PROXY or export every top-level entry continue to work; when token enforcement is active, proxy values include <audience>:<token>@.

​
Handling tokenized URLs

Proxy tokens are not upstream API credentials, but they grant access to Cordon’s matched-route credential injection for that scope while the daemon is running. Treat tokenized proxy URLs as sensitive local configuration:
  • Do not commit token-bearing integration files.
  • Do not paste tokenized URLs into issues, logs, or shared chat.
  • Use cordon token rotate <name> if a tokenized URL is exposed.
  • Use cordon doctor to verify token enforcement status.
Cordon setup refuses to write token-bearing files inside a Git repository unless both the final target and its atomic temp-file pattern are untracked and covered by .gitignore; merely untracked is not enough. For example, project Claude Code setup needs both .claude/settings.local.json and .claude/.settings.json.tmp.* ignored. Audience binding prevents accidental cross-scope proxy mixups, such as a project token being presented to a user-scope daemon or another project’s daemon. It does not bind the token to a process, working directory, binary, user session, OAuth/OIDC issuer, or remote verifier. A complete proxy URL remains a bearer credential for the matching local daemon until the token is rotated or revoked.