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

<Info>
  Install the Cordon CLI first. It runs the local proxy and provides the setup, configuration, and service commands.
</Info>

## 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
* Linux ARM64

<Note>Requires Node.js 20.18.1 or later.</Note>

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

<Columns cols={2}>
  <Card title="Download Cordon Monitor macOS app" icon="download" href="https://www.codezero.io/downloads/cordon-monitor/latest/dmg" cta="Download .dmg">
    Observability-only companion app for macOS 14+. Signed and notarized.
  </Card>

  <Card title="SHA-256 checksum" icon="shield-check" href="https://www.codezero.io/downloads/cordon-monitor/latest/sha256" cta="Download checksum">
    Verify the downloaded DMG before opening it.
  </Card>
</Columns>

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-0.2.0.dmg.sha256
```

<Note>
  Cordon Monitor does not install the `cordon` CLI. Install the CLI above to run the proxy.
</Note>

## Prerequisites

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

<AccordionGroup>
  <Accordion title="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>

  <Accordion title="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.
    </Warning>

    Store credentials with the `cordon secret set` command (see [Secret Sources](/configuration/secret-sources)).
  </Accordion>
</AccordionGroup>