Skip to main content
Cordon needs to be running before your application starts making API calls. There are two approaches. Project scope is the default; use --config when you need to target an integration-specific config path such as ~/.hermes/cordon.toml or ~/.openclaw/cordon.toml.
  • 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:
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:
The service is installed as a launchd user agent. It starts on login and restarts on failure.

​
Named instances

Run multiple cordon instances with different configs:

​
Health endpoint

The health endpoint is available at GET /health once the proxy binds its listener: Before the listener binds, there is no open port (connection refused). Readiness is set synchronously immediately after TcpListener::bind() succeeds and before the proxy begins accepting connections, so callers normally see /health go straight from connection refused to 200. Process supervisors can still 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:
If you know the configured port, the health endpoint should return 200:
If the proxy is stopped, start it manually or through the installed service:
For integration-specific configs such as Hermes or OpenClaw, add --config ~/.hermes/cordon.toml or --config ~/.openclaw/cordon.toml 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. Load TLS certificates when needed for HTTP MITM or PostgreSQL client TLS.
  4. Resolve PostgreSQL listener credentials at startup, if listeners are configured.
  5. Bind listener on 127.0.0.1:<listen>. Readiness is set immediately afterward, so /health starts returning 200 from this point.
  6. Begin accepting connections.