> ## 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.

# Process Management

> Run cordon alongside your application using Procfiles, launchd, or systemd.

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:

```bash theme={null}
cordon service install --config /path/to/cordon.toml
```

<Tabs>
  <Tab title="macOS (launchd)">
    The service is installed as a launchd user agent. It starts on login and restarts on failure.

    ```bash theme={null}
    # Install
    cordon service install --config /path/to/cordon.toml

    # Check status
    cordon status

    # Uninstall
    cordon service uninstall
    ```
  </Tab>

  <Tab title="Linux (systemd)">
    The service is installed as a systemd user service.

    ```bash theme={null}
    # Install
    cordon service install --config /path/to/cordon.toml

    # Check status
    cordon status

    # Uninstall
    cordon service uninstall
    ```
  </Tab>
</Tabs>

### Named instances

Run multiple cordon instances with different configs:

```bash theme={null}
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:

| Status                 | Response          | Meaning                                                |
| ---------------------- | ----------------- | ------------------------------------------------------ |
| `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:

```bash theme={null}
cordon status
cordon doctor
```

If you know the configured port, the health endpoint should return `200`:

```bash theme={null}
curl http://127.0.0.1:<PORT>/health
```

If the proxy is stopped, start it manually or through the installed service:

```bash theme={null}
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.