# Pair a Linux machine.

> Pair a Linux machine so crews can run agents on it.
> https://koi.dog/docs/pair-a-linux-machine/

## Before you start.

- A Linux machine with systemd and a shell.
- An account on app.koi.dog. Koidog is invite-only; request an invite at [koi.dog/invite](https://koi.dog/invite/).

*Step 1 of 5*

## Install koidog.

Run this in a terminal on the machine.

```sh
curl -fsSL https://koi.dog/install.sh | sh
# installs koidog in ~/.local/bin
koidog version
```

### Or download

| File | Size | SHA-256 |
| --- | --- | --- |
| [koidog-linux-x64](https://koi.dog/download/0.1.0/koidog-linux-x64) Linux · x86\_64 | 91 MB | `f78a156867b858b9ce700e86689d73758760b8dc1dddd227053d530cae5b8d39` |
| [koidog-linux-arm64](https://koi.dog/download/0.1.0/koidog-linux-arm64) Linux · arm64 | 91 MB | `fae7d75be852b1c44bca3c93303cf55dff2086a2f3303917499e384e73d3b6bc` |
| [koidog-darwin-arm64](https://koi.dog/download/0.1.0/koidog-darwin-arm64) macOS · Apple silicon | 71 MB | `00b5a5dd89cd82b22c5ddb795f9637a92e0e89c19f3829f924592d2786bb6db6` |

Each release lists its files and checksums in [manifest.json](https://koi.dog/download/latest/manifest.json).

*Step 2 of 5*

## Get a pairing code.

Copy an 8-character code from app.koi.dog; it lasts 10 minutes.

*Step 3 of 5*

## Run the pairing command.

Paste the dashboard's command into a shell on the machine.

```sh
koidog pair <code> --server https://app.koi.dog
# or choose the node's name
koidog pair <code> --server https://app.koi.dog --name <name>
```

*Step 4 of 5*

## Install the service.

This writes the systemd unit koidog-node.service, enables it and starts the node. Without root, Koidog turns on lingering (`loginctl enable-linger`) so the service keeps running after you log out. If it can’t, it says so and gives you the `sudo loginctl enable-linger` command to run.

Logs: `journalctl -u koidog-node` as root, `journalctl --user-unit koidog-node` otherwise, or `koidog node logs -f` either way.

```sh
koidog node install-service
# as root: /etc/systemd/system/koidog-node.service
# otherwise: ~/.config/systemd/user/koidog-node.service
```

*Step 5 of 5*

## Check that it works.

Run these on the machine.

- `koidog node doctor`: Health check of node and setup.
- `koidog node status`: Whether the node is running.
- `koidog node logs -f`: Node logs; -f follows them.

## How agents run on Linux.

On Linux as root with systemd-run, each agent slot runs as its own user in its own systemd scope. Otherwise agents run as the node's user.

| Node runs as | Agents run as | Workspaces |
| --- | --- | --- |
| root, with systemd-run | `koidog-slot-<n>` | `/srv/koidog/workspaces` |
| Otherwise | The node's user | `~/.koidog/workspaces` |

`KOIDOG_WORKSPACE_ROOT` moves the workspaces somewhere else.

## Unpair.

Run `koidog unpair` on the machine. It stops the node and removes its service and this machine's identity. The server still lists the machine until you revoke it on the Machines page.

> **Note**
>
> Revoke the pairing if you lose the machine.
