Viewport Docs

vpd logs, vpd doctor, vpd status. The workflows for when something's off and you don't know what yet.

The "first look" sequence

If something feels off, run these in order:

vpd doctor
vpd status
vpd logs --tail 50

vpd doctor is the most-informative single command. It diagnoses identity, endpoints, relay state, config source.

vpd status shows the live state of the daemon process and its connections.

vpd logs --tail 50 shows recent activity. Most issues leave a recent trace.

Follow logs in real time

vpd logs --follow --level debug

--level debug enables verbose output. Default level is info.

Filter to a specific subsystem:

vpd logs --follow | grep -i relay        # relay bridge activity
vpd logs --follow | grep -i pairing      # pairing flow
vpd logs --follow | grep -i hook         # agent hook events
vpd logs --follow | grep -i workflow     # workflow runs

Get a portable diagnostic bundle

For sharing with support or filing a bug:

vpd diagnostic > /tmp/vpd-diagnostic.zip

Bundle includes:

vpd doctor --json output.
Last 1 hour of logs.
Sanitized config (secrets redacted).
Pairing state (without keys).
System info (OS, node version, CPU arch).

Send to hello@getviewport.com.

Check a specific session

vpd session list
vpd session show ses_01J7…
vpd session manifest --session ses_01J7…
vpd session logs --session ses_01J7… --follow

session show prints metadata. session manifest prints the resolved resource manifest (contexts, workflows, plan templates). session logs is the per-session stream from the daemon's local store.

Inspect resolved config

If you're unsure what config the daemon thinks applies in a directory:

cd ~/your-repo
vpd config resolve

Walks the directory tree, reads .viewport/config.yaml, merges parent configs, outputs the resolved manifest. Helpful when sessions seem to use the wrong workflow or context.

Verify the relay handshake

For self-hosters, replay the wire-protocol conformance vectors:

cd packages/daemon
npm run test:conformance

Tests the Noise handshake against packages/daemon/docs/relay-noise-v3-conformance-vectors.json. If your relay rejects daemons but conformance passes, the issue is environmental (JWT, JWKS, network). If conformance fails, the daemon's crypto is broken. File a bug.

When tests pass but production behaves wrong

vpd logs --follow --level debug

Watch logs while you reproduce the issue. Specifically:

Did the daemon receive the agent hook event?
Did the daemon send a frame to the relay?
Did the relay accept it (look for ACK)?
Did the platform process it (look for a follow-up notification)?

If any of those steps is missing, you've narrowed where to look.

Common one-liners

# Daemon process and its workers
ps -ef | grep vpd

# Current config file location
vpd doctor | grep "Config source"

# Last 100 lines of system journal (Linux)
journalctl -u viewport-daemon -n 100

# Reset everything (nuclear option. Re-pairs from scratch)
vpd stop
rm -rf ~/.viewport/runtime.json
vpd start
vpd unpair
vpd pair

When to escalate

Email us with:

vpd diagnostic bundle.
Specific URL or session id involved.
What you expected to happen vs. what did.
Whether it's reproducible.

We answer within one business day for hosted customers, faster for paid plans. Enterprise has named contacts and SLA.

Debug recipes