Configuration Overview

Cordon is configured via cordon.toml. Prefer the CLI over hand-editing this file: cordon setup creates it, and cordon route / cordon listener commands validate changes and write the safer defaults for you. The file format is documented here for review, troubleshooting, and automation when a CLI command does not cover your use case. See setup for details.

Scopes

Cordon is project-first — most integrations default to project scope, giving each repository its own config, credentials, and proxy instance. A user scope is also available for tools that span projects. The two scopes are independent: each runs its own daemon with its own config file, TLS certificates, and optional OS service. They are not merged or layered.

Resource	Project scope	User scope
Config file	`$CWD/cordon.toml`	`$XDG_CONFIG_HOME/cordon/cordon.toml`
TLS certificates	`$XDG_CONFIG_HOME/cordon/projects/<dirname>-<hash8>/certs/`	`$XDG_CONFIG_HOME/cordon/user/certs/`
Service name	`<dirname>-<hash8>`	`user`

<dirname>-<hash8> is the project directory basename plus the first 8 hex characters of the SHA-256 of the absolute CWD path, so two projects with the same directory name never collide. On macOS (launchd) and Linux (systemd user units) these names are automatically namespaced. The launchd label becomes io.codezero.cordon.<name>.

Directory layout

Cordon follows the XDG Base Directory spec for its config location. $XDG_CONFIG_HOME defaults to ~/.config on both Linux and macOS — cordon intentionally uses ~/.config/cordon/ on macOS for consistency with cross-platform dev tools like git and VS Code. Set XDG_CONFIG_HOME=/custom/path to override; cordon will then use /custom/path/cordon/.

~/.config/cordon/                         # base directory
├── cordon.toml                           # user-scope config
├── user/
│   └── certs/                            # user-scope TLS material
│       ├── ca-cert.pem
│       └── ca-key.pem
└── projects/
    └── myapp-a1b2c3d4/                   # <dirname>-<hash8>
        └── certs/                        # project-scope TLS material
            ├── ca-cert.pem
            └── ca-key.pem

<project>/
└── cordon.toml                           # project-scope config (one per project)

Project-scope configs live beside your code. Everything else — user-scope config and all TLS certificates — lives under the user’s cordon config directory. The <dirname>-<hash8> naming uses SHA-256 of the absolute project path so two projects sharing the same directory name never collide.

Port allocation

Each cordon setup invocation — project or user scope — asks the OS for a free port and writes it into cordon.toml at setup time. In practice this avoids collisions between concurrent projects and rapid successive cordon setup invocations. There is no base port to configure. The allocated port is not reserved: cordon setup binds to port 0, reads the port the OS assigned, then releases the socket before writing the number into cordon.toml. Between setup and cordon start, another process could theoretically claim the port. If that happens, cordon start will fail to bind and you can rerun cordon setup to pick a new port. Persistent port reservation and re-allocation at start time is future work.

Per-integration defaults

Integration	Default config target	Rationale
`claude-code`	Project scope: `./cordon.toml`	Editor configs are typically per-repo
`codex`	Project scope: `./cordon.toml`	Project-specific Codex env isolates credentials
`hermes`	Project-style config: `~/.hermes/cordon.toml`	Isolates Hermes from unrelated repo configs while matching Hermes’s default profile
`openclaw`	Project-style config: `~/.openclaw/cordon.toml`	Isolates OpenClaw from unrelated repo configs while matching OpenClaw’s default profile

Overriding the scope

Pass --scope user or --scope project to override the default for claude-code or codex:

# Configure Claude Code globally (one config for all projects)
cordon setup claude-code --scope user

Hermes and OpenClaw do not expose --scope. Their default config paths are ~/.hermes/cordon.toml and ~/.openclaw/cordon.toml; pass --config to follow-up commands when you need to target those instances explicitly.

When to choose which scope

Project scope — the right default for most tools. Each repo gets its own credentials, port, and service. No cross-project interference.
User scope — best when you want a single cordon instance shared across repos. One cordon process handles all requests.

`cordon start` and scope

cordon start with no flags uses ./cordon.toml (project scope). To start the user-scope instance explicitly:

cordon start --scope user

For Hermes or OpenClaw, target the integration config directly:

cordon start --config ~/.hermes/cordon.toml
cordon start --config ~/.openclaw/cordon.toml

`cordon service` and scope

cordon service install/start/stop --scope <project|user> derives the service name and config path from the scope automatically:

cordon service install --scope project   # installs <dirname>-<hash8>
cordon service install --scope user      # installs user

For Hermes or OpenClaw, target the integration config directly:

cordon service install --config ~/.hermes/cordon.toml
cordon service install --config ~/.openclaw/cordon.toml

After setup, use commands like cordon route add, cordon route edit, cordon listener add, and cordon listener edit to modify credential rules. For automation, prefer non-interactive CLI flags (for example, cordon setup --yes or fully-flagged cordon route add) instead of maintaining a hand-written config. cordon service install does not write cordon.toml — it points an OS service at an existing file, typically the project-local file setup produced. Paths in cordon.toml are literal strings: Cordon does not expand $HOME, ~, or other environment variables. Use the absolute paths written by cordon setup, or substitute placeholders like elsewhere in these docs (/path/to/...). If ca_cert_path or ca_key_path are relative, they are resolved against the config file’s directory (not the working directory), so hand-edited configs work correctly under service managers where the working directory is /.

Minimal example

The listen port is assigned automatically by cordon setup — the 6790 shown in the example is illustrative; your actual port is OS-assigned and typically in the ephemeral range. Check the listen = ... line in your generated cordon.toml to find the port in use.

listen = 6790  # illustrative — your setup may allocate a different port

[tls]
enabled = true
# Substitute paths from your real `cordon.toml` (typically under ~/.config/cordon/projects/<namespace>/certs/).
ca_cert_path = "/path/to/ca-cert.pem"
ca_key_path = "/path/to/ca-key.pem"

[[routes]]
name = "stripe"

[routes.match]
host = "api.stripe.com"

[routes.auth]
type = "header"
header_name = "Authorization"
scheme = "Bearer"

[routes.auth.secret]
source = "1password"
account = "my-team"
vault = "Engineering"
item = "Stripe API Key"
field = "secret_key"

Top-level fields

Field	Type	Required	Description
`listen`	integer	Yes	Port number to listen on. The proxy always binds to `127.0.0.1` (loopback) — this is not configurable because binding to a non-loopback address would expose injected credentials to the network.
`tls`	object	No	TLS interception settings. Required only when you enable HTTPS MITM or require PostgreSQL client TLS.
`secrets`	object	No	Secret provider configuration. Use to specify an explicit path to the `op` binary when it’s not on `PATH` (common for background services). See Secret Sources — Provider configuration.
`routes`	array	No	List of HTTP credential route definitions. Matched routes are explicit trust decisions; see Routes.
`listeners`	array	No	List of PostgreSQL listener definitions. See Listeners.
`denylist_exceptions`	array of strings	No	`host:port` destinations carved out of the always-on SSRF denylist, without credential injection. See Denylist exceptions.

TLS settings

Field	Type	Required	Description
`tls.enabled`	boolean	No	Enable HTTPS interception via TLS MITM. Defaults to `false` if omitted.
`tls.ca_cert_path`	string	Conditional	Path to the CA certificate file. Required when HTTPS MITM is enabled or PostgreSQL `client_tls = "require"` is used.
`tls.ca_key_path`	string	Conditional	Path to the CA private key file. Required when HTTPS MITM is enabled or PostgreSQL `client_tls = "require"` is used.

When TLS is enabled, cordon performs MITM on HTTPS connections to configured route hosts. Inner request path and method filters decide whether credentials are stripped and injected after the tunnel is decrypted. It generates per-host certificates signed by the local CA. See TLS for details. Route and listener names share one namespace and must be unique. Listener ports must also be unique and cannot equal the HTTP proxy listen port.

Denylist exceptions

Cordon permits outbound requests to any public destination by default — it does not maintain an egress allowlist. What it always enforces is an SSRF denylist that blocks private, loopback, link-local, and cloud metadata addresses, plus CGNAT, 0.0.0.0/8, documentation and benchmarking ranges, multicast, IETF-reserved space, and the IPv6 equivalents of these. The denylist_exceptions list carves specific host:port destinations out of that denylist, without credential injection. This is useful for local development services (databases, mock APIs, local Supabase instances) that the proxy needs to forward traffic to but that do not require credential injection.

# top-level in cordon.toml, alongside `listen`
denylist_exceptions = ["localhost:54321", "localhost:4201"]

denylist_exceptions is a top-level key. In TOML, bare keys belong to whatever table precedes them, so it must appear before any [table] header (such as [tls] or [[routes]]). Placed after a table, TOML parses it as a field of that table and cordon rejects the config with an unknown field error.

Field	Type	Required	Description
`denylist_exceptions`	array of strings	No	List of `host:port` pairs carved out of the SSRF denylist. Each entry must include a port — host-only entries are not supported.

Loopback expansion: Loopback entries auto-expand across localhost, 127.0.0.1, and [::1]. Configuring localhost:54321 also allows 127.0.0.1:54321 and [::1]:54321. Denylist bypass scope: Entries bypass the entire SSRF denylist, not just loopback blocking. An exception for a private-network address (e.g., 192.168.1.50:8080) will be allowed through. Trust model: Denylist exceptions follow the same operator opt-in trust model as configured routes. Each entry is an explicit decision by the developer to permit a denylisted destination. Unlike routes, exceptions do not inject credentials — requests are forwarded unmodified.

Extended examples

Keep this page as the map of cordon.toml. Use the focused references for complete examples:

Routes for HTTP credential injection, auth types, provider examples, and route matching.
Listeners for PostgreSQL listener configuration.
Secret Sources for 1Password, keyring, rotation, and platform behavior.

Config file location

cordon start resolves the config file based on scope:

Project scope (default) — ./cordon.toml
User scope (--scope user) — $XDG_CONFIG_HOME/cordon/cordon.toml (or ~/.config/cordon/cordon.toml if XDG_CONFIG_HOME is not set)

cordon setup writes the config to the scope-appropriate path automatically. See Scopes above for the full scope path table. You can bypass scope resolution entirely with the --config flag:

cordon start --config /path/to/cordon.toml

cordon.toml typically contains project-specific secret references and should be gitignored.

Getting Started

Configuration

Guides

CLI Reference

Security

Configuration Overview

Scopes

Directory layout

Port allocation

Per-integration defaults

Overriding the scope

When to choose which scope

`cordon start` and scope

`cordon service` and scope

Minimal example

Top-level fields

TLS settings

Denylist exceptions

Extended examples

Config file location

​Scopes

​Directory layout

​Port allocation

​Per-integration defaults

​Overriding the scope

​When to choose which scope

​cordon start and scope

​cordon service and scope

​Minimal example

​Top-level fields

​TLS settings

​Denylist exceptions

​Extended examples

​Config file location

Scopes

Directory layout

Port allocation

Per-integration defaults

Overriding the scope

When to choose which scope

`cordon start` and scope

`cordon service` and scope

Minimal example

Top-level fields

TLS settings

Denylist exceptions

Extended examples

Config file location