Docs
Sign in

Pair a Linux machine.

Pair a Linux machine so crews can run agents on it.

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.

Step 1 of 5

Install koidog.

Run this in a terminal on the machine.

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

Or download

FileSizeSHA-256
koidog-linux-x64 Linux · x86_64 91 MB f78a156867b8…
koidog-linux-arm64 Linux · arm64 91 MB fae7d75be852…
koidog-darwin-arm64 macOS · Apple silicon 71 MB 00b5a5dd89cd…

Each release lists its files and checksums in 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.

Terminal
$ 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.

Terminal
$ 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 asAgents run asWorkspaces
root, with systemd-runkoidog-slot-<n>/srv/koidog/workspaces
OtherwiseThe 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.