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

> Install and manage cordon as a background service.

Install cordon as an OS-managed background service that starts automatically and restarts on failure.

## cordon service install

```bash theme={null}
cordon service install [NAME] [OPTIONS]
```

| Argument/Option  | Default                                          | Description                                                                                |
| ---------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `[NAME]`         | project scope service name (`<dirname>-<hash8>`) | Service instance name. Mutually exclusive with `--scope`; may be combined with `--config`. |
| `--config`, `-c` | scope-resolved config path                       | Path to an **existing** config file                                                        |
| `--scope`        | project                                          | Scope used to derive service name and config path                                          |
| `--dry-run`      | false                                            | Print the resolved install plan without writing service files                              |

This command **does not create or edit** `cordon.toml` — it only installs OS service metadata so the service runs `cordon start` with the config path you pass. The file must already exist, usually from [`cordon setup`](/cli/setup).

<Note>
  **Services are optional.** Most development workflows don't need a background service — just run `cordon start` alongside your app (e.g., in a Procfile). Use `cordon service install` when you want the proxy to start automatically on login and restart on failure for a specific project. Each service is tied to one project's `cordon.toml`.
</Note>

<Tabs>
  <Tab title="macOS">
    Installs a launchd user agent at `~/Library/LaunchAgents/`.

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

  <Tab title="Linux">
    Installs a systemd user service at `~/.config/systemd/user/`.

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

## cordon service uninstall

```bash theme={null}
cordon service uninstall [NAME] [--config PATH | --scope project|user]
```

| Argument / Option | Default                    | Description                                                              |
| ----------------- | -------------------------- | ------------------------------------------------------------------------ |
| `[NAME]`          | project scope service name | Service instance name (mutually exclusive with `--scope` and `--config`) |
| `--config`, `-c`  | —                          | Derive the service name from a config path                               |
| `--scope`         | project                    | Scope used to derive service name                                        |

## cordon service start

Start an installed cordon service.

```bash theme={null}
cordon service start [NAME] [--config PATH | --scope project|user]
```

| Argument / Option | Default                    | Description                                                              |
| ----------------- | -------------------------- | ------------------------------------------------------------------------ |
| `[NAME]`          | project scope service name | Service instance name (mutually exclusive with `--scope` and `--config`) |
| `--config`, `-c`  | —                          | Derive the service name from a config path                               |
| `--scope`         | project                    | Scope used to derive service name                                        |

The service must already be installed via `cordon service install`. If the service is already running, prints a warning and exits successfully.

## cordon service stop

Stop a running cordon service.

```bash theme={null}
cordon service stop [NAME] [--config PATH | --scope project|user]
```

| Argument / Option | Default                    | Description                                                              |
| ----------------- | -------------------------- | ------------------------------------------------------------------------ |
| `[NAME]`          | project scope service name | Service instance name (mutually exclusive with `--scope` and `--config`) |
| `--config`, `-c`  | —                          | Derive the service name from a config path                               |
| `--scope`         | project                    | Scope used to derive service name                                        |

## cordon service cleanup

List installed services whose embedded `--config` path no longer exists on disk (orphaned services) and remove them. Services accumulate when project directories are deleted or moved — cleanup prunes stale service definitions.

```bash theme={null}
cordon service cleanup [NAME] [--dry-run | --all]
```

| Argument / Option | Description                                                                |
| ----------------- | -------------------------------------------------------------------------- |
| `[NAME]`          | Target a single orphaned service by name. Mutually exclusive with `--all`. |
| `--dry-run`       | List orphaned services without prompting or removing anything              |
| `--all`           | Remove every orphaned service without prompting (skips running ones)       |

`--dry-run` and `--all` are mutually exclusive.

### Interactive mode

With no flags, each orphan is listed and you're prompted per service:

```
  Remove 'cordon-a1b2c3d4'? [y/N/a/q]
```

* **y** — remove this service
* **n** (or blank) — keep it
* **a** — remove this and all remaining orphans
* **q** — quit and leave remaining orphans untouched

### Running orphans

If an orphaned service is still running (it was started before its config was deleted), cleanup skips it and prints a hint:

```
⚠ Service 'cordon-deadbeef': running with missing config.
  Stop it first with: cordon service stop cordon-deadbeef
```

Stop the service manually, then re-run cleanup.

### Exit status

Cleanup exits non-zero if any removal failed.

## Multiple instances

Run separate cordon instances with different configurations:

```bash theme={null}
cordon service install api-proxy --config ~/configs/api-cordon.toml
cordon service install db-proxy --config ~/configs/db-cordon.toml
```

Each instance gets its own service with an independent lifecycle.