Skip to content

Pairing the runner

Connect a local runner to your Pipemason account.

Pairing binds the CLI on a specific machine to your Pipemason account. Once paired, the runner can register runs, stream live events to your dashboard, and receive control messages (pause, resume, abort) from the cloud. Pairing is a one-time step per machine.

Pair with pipemason login

From any terminal where the CLI is installed, run:

pipemason login

This kicks off a device-code flow:

  1. The CLI opens pipemason.com/pair in your browser with a 9-character code pre-filled.
  2. Sign in to your account if you are not already signed in.
  3. Click Pair to confirm the code and bind this machine to your account.
  4. The CLI detects the confirmation and completes the pairing automatically.

If your browser does not open on its own, the CLI prints the URL and code so you can open pipemason.com/pair manually and enter the code yourself.

Where the token lives

On a successful pair, the runner saves the resulting token to:

~/.pipemason/credentials.json

That file stays on your machine. The cloud never stores the token itself — it keeps only a sha256 hash of it, which is enough to authenticate your runner but cannot be reversed back into the token.

Privacy model

Pairing carries the same source-stays-local guarantee as the rest of Pipemason:

  • Your source code never leaves your machine. The runner reads and writes your working directory locally.
  • Only run metadata, logs, and any artifacts you opt into (such as screenshots and diffs) are streamed to the cloud for live monitoring.
  • The pairing token authenticates the runner to stream events for runs that belong to your account only.

Confirm pairing

When you start a run, the runner logs cloud: registered run <id> on startup. Seeing that line confirms the pairing is valid and the run is connected to your dashboard.

Note

If you see connecting to cloud control plane with no registration line that follows, the token may be invalid or revoked. Re-run pipemason login to pair again.

Re-pairing a machine

Running pipemason login again re-pairs the same machine and overwrites the stored credentials. Do this after revoking a runner from the dashboard, moving to a new account, or any time the runner reports an authentication problem.

Next step

With a paired runner, you are ready to start your first run. Read the Concepts overview to understand runs, programs, stories, and the phase machine before you go further.