Viewport Docs

vpd status shows disconnected. Relay state errored. The web app shows your machine as offline.

Quick checks

vpd doctor
vpd status

Read the output. If Relay state is anything other than connected, this page is for you.

Most common cause: the daemon process is up, but its WebSocket to the relay closed and reconnect is failing.

Check internet reachability first. Many false alarms turn out to be VPN or firewall changes.

curl -I https://relay.getviewport.com/health
# expect: HTTP/2 200

If that fails, your network can't reach the relay. Check VPN, firewall, captive portal.

If that succeeds:

vpd logs --follow --since 5m | grep -i relay

Look for the last connection attempt and the error code. Common ones:

4401: invalid_token. The relay credential has expired or been revoked. Re-pair.
4403: workspace_not_found. Your workspace was archived or your pairing was revoked from the web. Re-pair.
ECONNREFUSED. The relay URL is wrong. Check daemon.relay.endpoint in ~/.viewport/config.json.
Noise handshake: invalid psk. Workspace requires crypto_pairing mode. See Relay handshake errors.

Daemon is in exponential backoff. It'll try 5 times before giving up. If it gives up:

vpd restart

This re-reads the config, regenerates any session keys, and tries again from scratch.

The daemon process exited. Check:

vpd logs --since 1h | tail -50

Look for a panic or shutdown signal. Restart:

vpd start

If it crashes again, capture and send us:

vpd doctor --json > /tmp/vpd-doctor.json
vpd logs --since 1h > /tmp/vpd-logs.txt

The daemon process is alive but the local API is not answering. This usually means the worker process is hung but the supervisor is up.

vpd restart --force

--force sends SIGKILL to the process group. Use it when graceful shutdown isn't completing.

If you self-host the relay and daemons can't connect to it:

Check the relay's /health endpoint from a machine that can reach it: curl https://relay.your-co.com/health.
Check the relay's logs for handshake failures. If you see JWKS_URL unreachable, the relay can't reach the platform JWKS endpoint.
See Self-host: Monitor and operate.

Sometimes the daemon is fine and the platform side is the problem:

This is a state-sync gap. Force a re-sync:

vpd sync

If it persists, restart the daemon: vpd restart.

If you've tried the above and nothing sticks:

vpd unpair
vpd pair

This deletes the local pairing state and re-runs the browser flow. Your data on the platform side is unaffected.