Operate vpd workers

The launch path uses a self-hosted vpd worker:

hosted Viewport authorizes
vpd executes on your machine
provider grants create receipts

This page is for the person responsible for keeping that worker online.

Recommended Launch Setup

Use one persistent polling worker for the first team:

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

Healthy defaults:

What Healthy Looks Like

Run:

vpd worker doctor --json

The output should show:

• expected server;
• workspace/runner identity;
• transport polling;
• writable workdir;
• detected agent/tool capabilities;
• no missing credentials for the first launch agent;
• no stale worker lock warning.

In the app, the runner should show online/idle when no work is queued.

Starting And Stopping

For an interactive proof:

vpd worker start --mode persistent --transport polling

For normal operation, run it under your process manager. The command should be the same; only the supervisor changes.

Stop the paired worker cleanly:

vpd worker stop

Then confirm no stale worker process or lock remains:

pgrep -fl "vpd worker" || true
find "$HOME/.viewport" -maxdepth 5 -type f \( -name "*lock*" -o -name "*.lock" \) -print

Stale locks should be removed automatically when the recorded process is gone. If vpd worker stop reports that it removed a stale lock, start the worker again and watch the next heartbeat.

Do Not Run Two Persistent Workers For The Same Target

One persistent worker should own a server/workspace/runner target. A second worker for the same target can create duplicate claim attempts and confusing operator state.

If you want a one-off proof run, use one-shot mode instead of starting a second persistent worker:

vpd worker run-once --lease LEASE_TOKEN --transport polling

Do not paste lease tokens into docs, screenshots, or support tickets. Use a redacted digest if you need to reference one.

Restart While A Run Is Blocked

It is safe to restart the worker while a run is waiting for a human gate:

1. Stop the worker.
2. Confirm no stale process or lock.
3. Start the same paired worker profile.
4. Approve/request changes/reject in Viewport.
5. Watch the worker resume or keep the run blocked based on the decision.

Request changes should not run implementation. The revision attempt should stay in plan mode with no write/shell tools. See Approval or plan revision is stuck if it does not.

Logs And Evidence

Collect these when debugging:

vpd worker doctor --json > /tmp/vpd-worker-doctor.json
vpd status --json > /tmp/vpd-status.json

Also capture from the app:

• run id;
• runner name/id;
• current node;
• denial code, if present;
• GitHub PR URL or Slack permalink, if present;
• screenshot of run detail with tokens redacted.

Do not share:

• worker private keys;
• pairing codes that have not expired;
• bootstrap, claim, or lease tokens;
• provider OAuth tokens;
• model API keys;
• private repo content unless approved by your team.

Upgrade Discipline

For early partners:

1. Stop the worker.
2. Upgrade vpd.
3. Run vpd --version.
4. Run vpd worker doctor --json.
5. Start the worker.
6. Trigger a small sandbox run before trusting a production-adjacent route.

Do not change the workdir during an upgrade. If you must move it, reset and pair again so the stored worker profile matches reality.

When To Escalate

Escalate to the platform owner or support if:

• the worker is online but claim is denied with no visible reason;
• a run remains leased after worker exit and cleanup does not appear;
• request changes continues into implementation;
• a provider side effect runs without the expected approval;
• raw tokens appear in run detail, logs, proof files, or support packet output.

Where To Go Next

• Runner won't claim work.
• Support packet.
• Launch checklist.
• Security.