Skip to main content
Interactive setup wizard that detects your project type, generates CA certificates, creates a cordon.toml config file, and configures supported integrations. Prefer cordon setup over creating cordon.toml by hand; setup allocates ports, writes absolute TLS paths, and applies safer defaults consistently.

​
Usage

​
Options

Bare cordon setup is project-scope only. Claude Code and Codex add their own --scope option; Hermes and OpenClaw use integration-specific config paths by default.

​
Examples

​
Project setup and services

Cordon is project-first. By default, each project has its own cordon.toml with its own routes and credentials. A user scope is also available for tools that operate across projects. cordon setup writes ./cordon.toml in the current directory by default, or to the path specified by --config. Certificates are stored outside the project tree; see Scopes for exact paths. Setup does not install a background service automatically. In interactive mode it may offer to install one; --yes suppresses the prompt and skips service install. To run cordon as a launchd/systemd service for a project, install the service explicitly after setup:
See process management for more on running cordon as a service.

​
Integration subcommands

Integrations configure cordon for Claude Code, Codex, Hermes, or OpenClaw — setting up the proxy env vars and CA trust settings each integration needs. Each integration knows where that application stores configuration (for example, Claude Code settings, project-local or user Codex config, Hermes .env, or OpenClaw’s openclaw config + daemon service env) and handles setup and teardown automatically. Currently supported: claude-code, codex, hermes, openclaw.
For Codex, Cordon supports API-key authentication only. ChatGPT/OAuth-based Codex sessions may still route through the proxy transport, but Cordon does not replace or manage Codex’s ChatGPT auth state.

​
cordon setup claude-code

Configure cordon for Claude Code. Runs the base setup automatically, then writes the standard proxy and CA env vars to Claude Code settings.
To manage the integration later, see cordon integration. --service and --no-service are mutually exclusive.

​
cordon setup codex

Configure cordon for OpenAI Codex. Runs the base setup automatically, then writes the standard proxy and CA env vars to Codex’s .env and shell_environment_policy.set entries in Codex’s config.toml.
To manage the integration later, see cordon integration. --service and --no-service are mutually exclusive.
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. For project scope, set CODEX_HOME="$PWD/.codex" if you want Codex to load the project-local .env for its own startup-time network traffic.
When you want Codex to run outside its command sandbox, launch it with:
Running Codex with --dangerously-bypass-approvals-and-sandbox is inherently riskier because model-generated commands run without Codex’s normal sandbox boundary.We are working on a path that preserves credential protection while supporting fully sandboxed Codex sessions.

​
cordon setup hermes

Configure cordon for Hermes Agent. Runs the base setup automatically with ~/.hermes/cordon.toml by default, then writes the standard proxy and CA env vars to Hermes’s default ~/.hermes/.env.
To manage the integration later, see cordon integration. --service and --no-service are mutually exclusive.
Hermes setup only supports the default ~/.hermes/ profile in v1. If HERMES_HOME points elsewhere, setup exits and asks you to unset it or configure Hermes manually.

​
cordon setup openclaw

Configure cordon for OpenClaw. Runs the base setup automatically with ~/.openclaw/cordon.toml by default, then updates the default ~/.openclaw/openclaw.json proxy settings directly and reinstalls the OpenClaw daemon (openclaw daemon uninstall && openclaw daemon install) with NODE_EXTRA_CA_CERTS exported so the gateway trusts cordon’s CA.
To manage the integration later, see cordon integration. --service and --no-service are mutually exclusive.
OpenClaw setup only supports the default ~/.openclaw/ profile in v1. If OPENCLAW_CONFIG_PATH or OPENCLAW_STATE_DIR points elsewhere, setup exits and asks you to unset it or configure OpenClaw manually.
Older OpenClaw versions failed with a CDP 502 when using openclaw browser start with proxy.enabled=true. This was fixed upstream — run openclaw upgrade to get the fix. See Browser tool for details.

​
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. Allocates a free listen port and writes it to cordon.toml
  4. Generates CA certificates at ~/.config/cordon/projects/<namespace>/certs/
  5. Detects available secret providers and adds them to the config (OS Keyring, 1Password CLI)
  6. Creates cordon.toml with absolute cert paths
  7. Generates a default proxy token and creates tokens.toml for the scope
  8. Prints follow-up guidance for proxy env vars and CA trust
If you’re using Claude Code, Codex, Hermes, or OpenClaw, use the integration subcommands instead — they run the base setup automatically and then configure the tool’s proxy settings in one step.
Use cordon env for the generated proxy and CA variables, TLS for trust behavior, and SDK Compatibility for language-specific runtime notes.

​
Certificate storage

Certificates are stored outside your project directory, so they are not at risk of being committed to git with your app code. See Scopes for the canonical path table and TLS for CA private-key handling.

​
Multiple projects

Each project gets its own cordon.toml with its own listen port, routes, and certificate namespace. Setup allocates a free port automatically; inspect the generated listen = ... line in each cordon.toml if you need the exact port. 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 names:

​
Removal recipes

To disable an integration, see cordon integration disable. To remove cordon itself from a machine after all integrations are disabled:
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.