> ## 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 (`-`) | 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). **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`. Installs a launchd user agent at `~/Library/LaunchAgents/`. ```bash theme={null} cordon service install --config /path/to/cordon.toml ``` Installs a systemd user service at `~/.config/systemd/user/`. ```bash theme={null} cordon service install --config /path/to/cordon.toml ``` ## 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` | — | Find the installed service whose embedded config path matches; falls back to the config-derived service name if no installed service matches | | `--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]` | auto-detected | Service instance name (mutually exclusive with `--scope` and `--config`) | | `--config`, `-c` | — | Find the installed service whose embedded config path matches; falls back to the config-derived service name if no installed service matches | | `--scope` | project | Scope used to derive service name | With no arguments, the target is auto-detected: the current directory's project service if installed, otherwise the sole installed service. If multiple services are installed and none matches the current directory, the command errors and lists them. 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]` | auto-detected | Service instance name (mutually exclusive with `--scope` and `--config`) | | `--config`, `-c` | — | Find the installed service whose embedded config path matches; falls back to the config-derived service name if no installed service matches | | `--scope` | project | Scope used to derive service name | With no arguments, the target is auto-detected: the current directory's project service if installed, otherwise the sole installed service. If multiple services are installed and none matches the current directory, the command errors and lists them. ## cordon service log View logs for a cordon service. ```bash theme={null} cordon service log [NAME] [OPTIONS] ``` | Argument / Option | Default | Description | | ----------------- | ------------- | --------------------------------------------------------- | | `[NAME]` | auto-detected | Service instance name (mutually exclusive with `--scope`) | | `--follow`, `-f` | false | Stream logs continuously (Ctrl+C to stop) | | `--tail`, `-n` | 100 | Number of recent log lines to show | | `--scope` | project | Scope used to derive service name | With no arguments, the target is auto-detected: the current directory's project service if installed, otherwise the sole installed service. If multiple services are installed and none matches the current directory, the command errors and lists them. Tails `cordon.stderr.log` under `~/Library/Logs/cordon-/` — `cordon--` for project scope, `cordon-user` for user scope. Cordon writes startup errors and diagnostics to stderr. The launchd service may also create a sibling `cordon.stdout.log`, but `cordon service log` does not read it. ```bash theme={null} cordon service log --follow ``` Reads from `journalctl --user` for the systemd service unit. ```bash theme={null} cordon service log --follow ``` ## 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.