> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ctrlnode.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Install the Bridge

> Install ctrlnode (Windows, Linux, macOS), BASE_PATH workspace, pairing token, verify connection

Install the open-source **Bridge** binary (`ctrlnode`) from [github.com/ctrlnode-ai/ctrlnode](https://github.com/ctrlnode-ai/ctrlnode), pair it with CtrlNode, and confirm the app shows **connected**.

## Before you start

* A CtrlNode account at [app.ctrlnode.ai](https://app.ctrlnode.ai)
* A **pairing token** from **System → Bridge Setup** or the setup wizard **Token** step
* Network egress to `wss://api.ctrlnode.ai` (default control plane)

## One-line installers

<Tabs>
  <Tab title="Windows (PowerShell)">
    ```powershell theme={null}
    irm https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.ps1 | iex
    ```

    The script:

    * Downloads the latest **`ctrlnode.exe`** from GitHub Releases
    * Installs to `%LOCALAPPDATA%\Programs\ctrlnode` (or a path you choose)
    * Adds that folder to your user **PATH** (command name: `ctrlnode`)
    * Sets **`BASE_PATH`** to your chosen workspace parent (where `{BASE_PATH}/.ctrlnode` lives)
    * Optionally starts the Bridge when you answer **y** at the end
  </Tab>

  <Tab title="Linux / macOS">
    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.sh | sh
    ```

    Custom install directory:

    ```bash theme={null}
    curl -fsSL https://raw.githubusercontent.com/ctrlnode-ai/ctrlnode/main/install.sh | sh -s -- --dir ~/.local/bin
    ```

    The script installs **`ctrlnode`** (Linux x64 or x64-baseline by CPU features, or `ctrlnode-darwin-arm64` on Apple Silicon) and sets **`BASE_PATH`** in your shell profile.
  </Tab>
</Tabs>

## Manual download

| Platform                          | Release asset                 | Command on PATH |
| --------------------------------- | ----------------------------- | --------------- |
| Windows x64                       | `ctrlnode.exe`                | `ctrlnode`      |
| Linux x64 (AVX2)                  | `ctrlnode-linux-x64`          | `ctrlnode`      |
| Linux x64 (older CPUs / many VMs) | `ctrlnode-linux-x64-baseline` | `ctrlnode`      |
| macOS Apple Silicon               | `ctrlnode-darwin-arm64`       | `ctrlnode`      |

Download from [GitHub Releases](https://github.com/ctrlnode-ai/ctrlnode/releases). On Linux:

```bash theme={null}
grep -o "avx[^ ]*" /proc/cpuinfo | head -1
```

`avx2` → standard binary; otherwise use `-baseline`.

## Start the Bridge

<Warning>
  Copy the pairing token when generated — you cannot view it again. Regenerate from **Bridge Setup** if you lose it.
</Warning>

<Tabs>
  <Tab title="Windows">
    ```powershell theme={null}
    $env:PAIRING_TOKEN="<paste-token>"
    ctrlnode
    ```
  </Tab>

  <Tab title="Linux / macOS">
    ```bash theme={null}
    PAIRING_TOKEN=<paste-token> ctrlnode
    ```
  </Tab>
</Tabs>

Installers also write `~/.ctrlnode/.env` with `PAIRING_TOKEN`, `SAAS_URL`, and `BASE_PATH` when you use the interactive flow.

### Token and `BASE_PATH` precedence

| Source                                               | Wins?                                                                   |
| ---------------------------------------------------- | ----------------------------------------------------------------------- |
| Shell (`$env:PAIRING_TOKEN`, `$env:BASE_PATH`, etc.) | **Yes** — overrides `.env` for most keys                                |
| `~/.ctrlnode/.env` from installer                    | Authoritative for `PAIRING_TOKEN`, `SAAS_URL`, `BASE_PATH` when present |
| First-run prompts                                    | Used when keys are missing                                              |

If pairing fails after a new token, unset stale shell variables:

```powershell theme={null}
Remove-Item Env:PAIRING_TOKEN -ErrorAction SilentlyContinue
```

```bash theme={null}
unset PAIRING_TOKEN
```

## Verify in CtrlNode

1. Open **System → Bridge Setup** — status **Connected** (green).
2. Open **Team** — agents appear after `sync_*_agents` on connect.
3. Dispatch a test task — moves to **In progress** with live activity.

## Run as a service (optional)

Run **`ctrlnode`** as a long-lived process under the same user that owns `BASE_PATH` and `~/.ctrlnode/.env` (`systemd`, Windows Task Scheduler, or a supervisor).

## Next steps

* [Bridge configuration](/bridge/configuration) — `BASE_PATH`, API keys, timeouts
* [Providers](/bridge/providers) — CLIs including **Hermes**
* [Bridge overview](/bridge/overview) — routing (no `PROVIDERS` env needed)