# Dock CLI (https://docs.capy.ai/dock)

> Run Capy headless with capy dock: pair a Linux or macOS machine, such as a server, and run threads on it without the desktop app.

The Dock CLI, `capy dock`, is Capy without the desktop app. It turns a Linux or macOS machine into a [device](/desktop) that threads run on, so a build server, a cloud VM, or a spare Mac can host your threads with the tools, credentials, and services already on it. You start and follow those threads from any browser, the same way as threads on the desktop app.

## Install [#install]

Run the installer in a terminal on the machine, as the user that should run threads:

```bash
curl -fsSL https://downloads.capy.ai/stable/dock/install.sh | sh
```

The installer picks the build for the machine, checks its checksum, and on macOS checks its signature. It installs into `~/.capy/dock-install` and puts the `capy` command in `~/.capy/bin`. If that folder isn't on your `PATH`, the installer prints the line to add. Run the installer again to update.

| System | Supported |
| --- | --- |
| macOS | Apple Silicon and Intel |
| Linux | x64 and arm64, with glibc. Alpine and other musl distributions aren't supported. |
| Windows | Not supported. Use the [desktop app](/desktop). |

The installer refuses to run as root. Install the Dock CLI as an ordinary user, because threads run commands with that user's permissions.

## Pair the machine [#pair-the-machine]

Run `capy dock` in a terminal. On the first run it shows a link, a QR code, and a pairing code:

1. Open the link or scan the QR code, or open **Pair a device** in [device settings](https://capy.ai/settings/devices) and type the code.
2. Check the hostname and system, pick the organization, and name the device.
3. Select **This code is on a machine I am setting up right now**, then select **Approve**.
4. Back in the terminal, confirm that the organization and device name are yours.

Never approve a code someone sent you. The first run needs an interactive terminal, so the pairing code never ends up in a log.

## Run threads [#run-threads]

While `capy dock` runs, the machine is online. Pick it in **Run on** when you start a thread or a Captain, like any other device. Threads on the machine work in git worktrees under `~/.capy/worktrees` and have no machine-time charge.

To link the folders where your repositories are cloned, pass `--dir` when you start the dock, or use `capy dock dirs` while it's stopped:

```bash
capy dock --dir ~/src/api --dir ~/src/web
capy dock dirs add ~/src/mobile
```

`capy dock` runs in the foreground. When it stops, the machine goes offline, and its threads wait until it runs again or move to the cloud, as described in [Sleep and offline](/desktop#sleep-and-offline). After the first run it needs no terminal, so you can keep it running under `tmux` or a service manager such as systemd or launchd.

## Commands [#commands]

| Command | What it does |
| --- | --- |
| `capy dock` | Runs the dock in the foreground, and pairs the machine on the first run. |
| `capy dock status` | Shows whether the dock is running and which organization the machine is paired with. |
| `capy dock doctor` | Checks the machine, the install, the pairing, `git` and `gh`, and whether Capy is reachable. |
| `capy dock dirs` | Lists linked folders. `add <path>` and `remove <path>` change them. |
| `capy dock verify` | Checks the installed files against the list signed into the binary. |
| `capy dock version` | Prints the version. |

Add `--verbose` to `capy dock` to print its logs.

## Good to know [#good-to-know]

- One user on a machine runs one Capy device. Quit the desktop app before you start `capy dock` as the same user.
- Threads can read and change anything that user can. On a shared server, create a dedicated account for the dock.
- To unpair a machine, open it in [device settings](https://capy.ai/settings/devices) and choose **Revoke device**. The next `capy dock` run asks to pair again.