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, both project-scoped:
  • 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. Starts on login, restarts on failure. Useful when you want the proxy always available for a specific project 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).

​
Startup sequence

The proxy starts in a strict order:
  1. Parse and validate cordon.toml. Exit on invalid config.
  2. Resolve all secrets from configured sources. Exit if any fail.
  3. If TLS enabled: generate or load CA keypair.
  4. Bind listener on configured address. The health endpoint serves 200 from this point.
  5. Begin accepting connections.