Skip to main content
Cordon is configured via cordon.toml. cordon setup creates this file for you — you do not need to write it by hand.
FilePath
Config./cordon.toml
Certificates~/.config/cordon/projects/<namespace>/certs/
See setup for details. After setup, edit the generated file (or use commands like cordon route add) to add routes and secret references. For automation, run cordon setup non-interactively (e.g. --yes) 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

listen = 6790

[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 = "bearer"

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

​
Top-level fields

FieldTypeRequiredDescription
listenintegerYesPort 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.
tlsobjectNoTLS interception settings. Required for HTTPS routes.
routesarrayYesList of route definitions. At least one route is required.
servicesarrayNoTCP service definitions (e.g., PostgreSQL credential injection).

​
TLS settings

FieldTypeRequiredDescription
tls.enabledbooleanYesEnable HTTPS interception via TLS MITM.
tls.ca_cert_pathstringYesPath to the CA certificate file. Created by cordon setup.
tls.ca_key_pathstringYesPath to the CA private key file. Created by cordon setup.
When TLS is enabled, cordon performs MITM on HTTPS connections for matched routes. It generates per-host certificates signed by the local CA. See TLS for details.

​
Full example

listen = 6790

[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 = "bearer"

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

[[routes]]
name = "openai"

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

[routes.auth]
type = "bearer"

[routes.auth.secret]
source = "1password"
vault = "Engineering"
item = "OpenAI API Key"
field = "credential"

[[routes]]
name = "custom-service"

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

[routes.auth]
type = "api_key"
header_name = "X-Api-Key"

[routes.auth.secret]
source = "keyring"
account = "example-api-key"

​
Config file location

Cordon searches for the config file in this order:
  1. Current directory — ./cordon.toml
  2. User config directory — ~/.config/cordon/cordon.toml (or $XDG_CONFIG_HOME/cordon/cordon.toml if XDG_CONFIG_HOME is set)
If neither is found, cordon exits with an error showing both paths it checked. You can skip this lookup entirely with the --config flag: 
cordon start --config /path/to/cordon.toml
cordon.toml typically contains project-specific secret references and should be gitignored.