Quickstart

End state: you start an agent on your laptop, walk to a different room, get a prompt on your phone, tap "Keep going," and the agent continues.

What you need

• Node 20+ on PATH.
• A Mac or Linux machine where your agent runs. Claude Code, Codex, Aider, and Gemini are supported.
• An account at getviewport.com.
• A phone (optional, but where this gets fun).

1. Install the daemon

npm i -g @viewportai/daemon
vpd doctor

vpd doctor is read-only. It prints daemon identity, control-plane endpoints, relay state, and the config source path. If something's wrong, it tells you where to look. It does not repair.

Daemon config lives at ~/.viewport/config.json, mode 0o600. Override with VIEWPORT_HOME or VPD_HOME if you need sandboxing or per-CI installs.

2. Pair this machine

vpd pair

With no arguments, vpd pair mints an 8-character pairing code, opens your browser at app.getviewport.com/pair?code=…, and polls for approval. From the browser you pick which workspace to pair into and click Approve.

What's happening:

• The daemon calls POST /api/pairing-codes to mint the code.
• The web /pair route reads the code and offers a workspace picker.
• On approve, the platform binds your machine to the workspace and issues a relay credential for this install.
• The daemon writes credentials to ~/.viewport/config.json and auto-restarts to connect.

Confirm:

vpd status

You should see running, your machine name, daemon version, and Relay state: connected.

3. Add a repo

Tell the daemon which directories to watch:

vpd add ~/code/api
vpd list

vpd add persists the directory into ~/.viewport/config.json and POSTs to the daemon's local API so the running daemon picks it up immediately. Repeat for each repo you want covered.

4. Run an agent

Two ways. Both produce the same result.

Programmatic:

vpd run ~/code/api --prompt "fix the failing auth tests"

This opens a WebSocket to your daemon, sends a launch request, and streams session-update frames back. --wait blocks until the session ends; --attach follows it like vpd logs --follow.

Out of band, exactly how you already work:

cd ~/code/api
claude       # or: codex, aider, gemini

The daemon picks up the session the moment it starts and announces it to the platform.

Either way, app.getviewport.com/sessions shows the row with status active, the working directory, the agent name, and the resolved context manifest. The daemon sends metadata. Never the prompt or transcript.

5. Decide from anywhere

When the agent generates a plan to review, or hits an approval gate (e.g. risky path edit), or proposes new context to remember, it pauses and the decision lands in your inbox:

• Open app.getviewport.com/inbox on web (or your phone. It's mobile-responsive).
• Tap Approve plan / Allow once / Approve candidate as appropriate.

The daemon receives the decision over its WebSocket and continues, or stops, without you having to open the laptop the agent is running on.

What just happened

Every decision you make writes an immutable row to the audit log (90-day default retention).

Where to go next

• Add a repo. Directory model and resolution.
• Mobile experience. The iPhone push flow.
• Daily driver loop. What an average week looks like.
• Concepts: Sessions. What's on the wire.
• CLI reference. Every vpd verb with real flags.
• Self-host the relay. Keep traffic inside your network.