Viewport Docs

vpd pair hangs. Browser doesn't return. Code expires. Daemon shows the wrong org after pairing.

Symptoms

`vpd pair` hangs at "Waiting for confirmation..."

The daemon mints the code and polls for approval. If you closed the browser tab or didn't approve, it'll poll for ~15 minutes before timing out.

Fix: re-open the URL vpd pair printed. Or Ctrl-C and run vpd pair again to mint a fresh code.

If you approved and the daemon still hangs, the daemon → platform poll may be stuck. Check logs:

vpd logs --since 2m | grep -i pair

If you see 404 on /api/pairing-codes/{code} polls, the code expired. Re-run vpd pair.

Browser approval succeeded but daemon didn't pick it up

The daemon polls on a fixed interval. After approval, it should pick up within 2-5 seconds. If 30+ seconds and nothing:

vpd restart
vpd status

The daemon re-checks pairing state on startup. If the pairing was approved, this should connect immediately.

Code expired before you could approve

Pairing codes have a 15-minute TTL. If you got distracted:

vpd pair

A fresh code is minted.

`vpd pair` says "already paired"

If the daemon is already paired to some org and you want to pair to a different one, you have two options.

Add a second binding (multi-org daemon):

vpd pair --add

This keeps the existing binding and adds a new one. Lets one daemon serve multiple orgs.

Replace the existing binding:

vpd pair --replace

This deletes the previous binding (the daemon stops streaming to the old org) and pairs to the new one. Any active sessions on the old org are unaffected (they continue, but new sessions go to the new org).

Without --add or --replace, vpd pair refuses to overwrite. By design, to prevent accidental switching.

Paired to the wrong org

Easy to fix:

vpd unpair --org 01J7…   # remove the wrong binding
vpd pair                  # pair fresh (you'll pick the right org in the browser)

Or replace in one step: vpd pair --replace and pick the right org in the browser.

`vpd pair` shows the wrong workspaces in the browser

If the browser drops you on the pair page but doesn't list a workspace you expect:

You're signed in to the wrong Viewport account. Sign out, sign in with the right account, retry.
You're not a member of that workspace. Ask an admin to invite you. See Invite teammates.

Self-hosted: pairing API unreachable

If your control plane is self-hosted and vpd pair can't reach it:

Check VIEWPORT_API_URL env var (or daemon.api.endpoint in config).
Try curl https://api.your-co.com/api/health. It should return 200.
See Reference: env vars.

Why pairing exists at all

The pairing handshake is the platform proving the daemon belongs to a workspace. It establishes:

A workspaceId for this binding.
A signed issueToken the daemon presents to the relay.
A per-org keypair so the daemon's machine identity is org-scoped.

Without pairing, the daemon has no way to identify itself to the relay. The relay rejects unsigned connections.

Pairing fails or loops