Skip to content
CommandChain CommandChain CommandChain Docs

Pairing a runner

Pairing is how a runner earns the right to take work from your workspace. It is a device-code flow: the machine asks for a short code, and you approve that code in a browser where you are already signed in.

You never paste a token into a terminal, and no secret is ever displayed on either side.

The terminal side

Section titled “The terminal side”

When the runner has no saved credential for an instance, it prints a code and waits:

Terminal window
────────────────────────────────────────────────────────────
  Pair this runner to approve it for a tenant:


     Code: 329X-4QKT
     URL:  https://your-commandchain/app/pair?code=329X-4QKT


  Waiting for approval (up to 10 min)...
────────────────────────────────────────────────────────────

It also tries to open that URL in your desktop browser. If it cannot, open the URL yourself, or go to Settings, then Runners, then Add runner and type the code in.

The code is valid for ten minutes. If it expires, run the installer again to get a fresh one.

The browser side

Section titled “The browser side”

The approval page shows only the runner’s identity: the name it asked for, the coding-agent adapters it found on that machine, and its status.

The pairing approval page, showing the runner name, its adapters, and the Approve and Deny buttons.

  1. Check the name. It must match the machine you just ran the installer on. This is the whole security decision, so make it deliberately: an unknown name means someone else’s code, and you should select Deny.

  2. Select Approve. The workspace mints a credential for that runner and sends it back over the wire.

  3. Wait for the first heartbeat. The page keeps watching. Approval alone does not mean the machine is working; the runner has to check in.

When the runner checks in, the page confirms it:

The pairing page after approval, confirming that maya-macbook is connected and ready to take work.

Meanwhile, the terminal on the runner machine says the same thing from its side:

Terminal window
✔ Paired with CommandChain.
    instance     https://your-commandchain
    tenant       alpenglow
    runnerId     32c152e4-3d5e-49a1-b3df-20b95c0a74b6
    displayName  maya-macbook
    credential   /home/maya/.commandchain/runner.json (0600, never printed)

Why there is no token to paste

Section titled “Why there is no token to paste”

A token you copy is a token that lives in your clipboard, your scrollback, and quite possibly your shell history. Pairing avoids all three:

  • The code is not a credential. It authorises nothing on its own. It only identifies a machine that is asking, and it expires.
  • The real credential travels over the wire, straight into a 0600 file in your home directory. It is never printed, never a command-line argument, and never written into the service definition.
  • You approve as yourself, in a browser session you already trust, so the decision is attributed to a person rather than to whoever holds a secret.

Re-pairing

Section titled “Re-pairing”

Re-running the installer does not re-pair. It finds the saved credential and keeps it, which is what makes an upgrade safe. A runner pairs again only when:

  • you removed its credential with --uninstall --purge, or
  • you are pointing it at a different instance.

Next steps

Section titled “Next steps”