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

# Installation

> Install the Cordon CLI and optional Cordon Monitor macOS app.

> [!NOTE]
>
> Install the Cordon CLI first. It runs the local proxy and provides the setup, configuration, and service commands.

## CLI

```bash theme={null}
npm install -g @codezero-io/cordon
```

This installs the `cordon` binary globally. Platform-specific binaries are bundled for:

* macOS ARM64 (Apple Silicon)
* macOS x64 (Intel)
* Linux x64 (glibc 2.17+ — RHEL 7+, Ubuntu 18.04+, Debian 9+)
* Linux ARM64 (glibc 2.17+ — RHEL 7+, Ubuntu 18.04+, Debian 9+)

> [!NOTE]
>
> Requires Node.js 22.23.4+ on 22.x, 24.22.1+ on 24.x, or 26.12.1+ on 26.x.

## Verify installation

```bash theme={null}
cordon --version
```

## Cordon Monitor macOS app

Cordon Monitor is an optional macOS menu bar app for observing local Cordon instances. It shows which project and user-scope instances are present, whether they are running, which ports they use, and the routes/listeners loaded from their configs.

It is observability-only: Cordon Monitor does not start, stop, or reconfigure Cordon, and it does not handle credentials. Use the `cordon` CLI for setup and control.

> [card] [Download Cordon Monitor macOS app](https://www.codezero.io/downloads/cordon-monitor/latest/dmg)
>
> Observability-only companion app for macOS 14+. Signed and notarized.

> [card] [SHA-256 checksum](https://www.codezero.io/downloads/cordon-monitor/latest/sha256)
>
> Verify the downloaded DMG before opening it.

Open the DMG and drag **Cordon Monitor** to **Applications**.

To verify the download, place the DMG and checksum file in the same directory and run:

```bash theme={null}
shasum -a 256 -c Cordon-Monitor-<VERSION>.dmg.sha256
```

Replace `<VERSION>` with the version you downloaded (e.g. `0.3.1`).

> [!NOTE]
>
> Cordon Monitor does not install the `cordon` CLI. Install the CLI above to run the proxy.

## Prerequisites

Cordon needs a secret source to fetch credentials from. You'll need at least one of:

> [accordion] 1Password CLI
>
> Install the [1Password CLI](https://1password.com/downloads/command-line/) (`op`) and sign in:
>
> ```bash theme={null}
> # Install (macOS)
> brew install --cask 1password-cli
>
> # Sign in
> op signin
> ```
>
> The `op` CLI must be authenticated before starting cordon.

> [accordion] OS Keyring
>
> Cordon uses the operating system's built-in credential store:
>
> * **macOS**: Keychain Access — no additional setup needed.
> * **Linux**: Secret Service API (via D-Bus), typically provided by GNOME Keyring or KDE Wallet. Requires a desktop session.
>
> On Linux, ensure a Secret Service provider is installed:
>
> ```bash theme={null}
> sudo apt install gnome-keyring   # Debian/Ubuntu
> ```
>
> After installing, **log out and log back in** so the keyring daemon starts and creates a default "login" collection.
>
> > [!WARNING]
> >
> > The OS keyring requires a desktop session with D-Bus. It does not work in containers, CI, or headless servers.
>
> Store credentials with the `cordon secret set` command (see [Secret Sources](https://docs.codezero.io/configuration/secret-sources.md)).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.