Machines and pairing

Pairing proves a local vpd install to a workspace. It does not grant broad authority by itself.

There are two different modes:

Use worker mode for the launch path.

Worker Pairing

The app issues a short-lived pairing code. Run:

vpd pair PAIRING_CODE --worker --transport=polling --workdir "$HOME/.viewport/worktrees"
vpd worker doctor --json
vpd worker start --mode persistent --transport polling

Hosted Viewport is the default server. Self-hosted control planes should be explicit:

vpd pair PAIRING_CODE --worker --server https://viewport.customer.internal --transport=polling --workdir "$HOME/.viewport/worktrees"

The worker profile records the paired server, workspace, runner identity, transport, workspace root, and detected local capabilities. Capability advertisement helps routing; it is not business authority.

What A Worker Can Do

A worker can:

• heartbeat to the paired server;
• advertise detected agents and tools;
• claim an authorized lease;
• execute the workflow snapshot locally;
• sync receipts, logs, artifacts, and usage metadata;
• send a cleanup receipt.

A worker cannot, by pairing alone:

• write to GitHub;
• post to Slack;
• receive repo credentials;
• change workflow policy;
• bypass approval gates;
• claim work for another workspace.

Those require server-side workflow authority, grants, and approval state.

Monitor Pairing

The monitor path is for local interactive agent sessions. Pairing alone is not streaming. A directory must be explicitly bound:

vpd pair
vpd bind ~/code/my-repo

Keep monitor and worker profiles conceptually separate. A machine can do both, but team workflow execution should be debugged through vpd worker doctor, not through monitor session status.

Revocation And Reset

If a worker is revoked, hosted Viewport should deny new heartbeats, claims, and sync writes except for allowed final cleanup receipts tied to an already-issued lease. Locally, remove or reset the worker profile, then pair again with a fresh code.

Support bundles should include sanitized vpd worker doctor --json output and the run id. Do not include private keys, pairing codes, bootstrap tokens, or lease tokens.