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 needs to be running before your application starts making API calls. There are two approaches. Project scope is the default; use --scope user for user-wide setups such as Hermes.
  • Procfile (recommended for development) — start Cordon alongside your app in a process manager. Simple, no system-level installation, stops when you stop developing.
  • Background service (optional) — install Cordon as a launchd/systemd service for a project or user scope. Starts on login, restarts on failure. Useful when you want the proxy always available without manually starting it.

​
Procfile (foreman / overmind)

The simplest approach for development. Use cordon wait to block until the proxy is ready: 
proxy: cordon start --config cordon.toml
web: cordon wait && npm run dev
cordon wait polls the health endpoint until it returns 200, then exits. Your application starts only after credentials are loaded and the proxy is accepting connections.

​
Background service

Install cordon as an OS-managed service that starts automatically: 
cordon service install --config /path/to/cordon.toml
The service is installed as a launchd user agent. It starts on login and restarts on failure.
# Install
cordon service install --config /path/to/cordon.toml

# Check status
cordon status

# Uninstall
cordon service uninstall

​
Named instances

Run multiple cordon instances with different configs: 
cordon service install api-proxy --config ~/configs/api-cordon.toml
cordon service install db-proxy --config ~/configs/db-cordon.toml

​
Health endpoint

The health endpoint is available at GET /health once the proxy binds its listener:
StatusResponseMeaning
200{"status":"ok"}Proxy is ready — secrets loaded, accepting connections
(connection refused)(no response)Proxy has not finished starting
There is no 503 state. Before the listener binds, there is no open port (connection refused). Once TcpListener::bind() succeeds, /health immediately returns 200. Process supervisors can distinguish between “not started yet” (connection refused) and “ready” (200).

​
Proxy not running checks

Use these checks from any integration when requests fail with connection refused or the tool reports that Cordon is down: 
cordon status
cordon doctor
If you know the configured port, the health endpoint should return 200: 
curl http://127.0.0.1:<PORT>/health
If the proxy is stopped, start it manually or through the installed service: 
cordon start
cordon service start
For user-scope integrations such as Hermes, add --scope user to these commands.

​
Startup sequence

The proxy starts in a strict order:
  1. Parse and validate cordon.toml. Exit on invalid config.
  2. Validate HTTP route secrets from configured sources. Exit if any fail.
  3. Resolve PostgreSQL listener credentials at startup, if listeners are configured.
  4. If TLS enabled: generate or load CA keypair.
  5. Bind listener on 127.0.0.1:<listen>. The health endpoint serves 200 from this point.
  6. Begin accepting connections.