Quickstart — first governed run, first receipt

Every agent run through Viewport gets a receipt: a tamper-evident, exportable record of what ran, under which policy, what it spent, and who approved it. This page takes you from a new account to viewing the receipt of your own governed run.

The journey:

sign up -> create workspace -> get a runner -> add a model key
        -> launch the first governed run -> open the receipt

You do not need to commit any .viewport/ files, configure GitOps routes, or connect Slack for this first run. Those come later, when you wire Viewport into real team events — see Self-serve first run.

Before you start

• A browser, for https://app.getviewport.com.
• Only if you choose a self-hosted runner: Node.js 20+ and npm 10+ on the machine that will execute agent work. The managed-runner path needs nothing installed.

1. Sign up and create your workspace

Open https://app.getviewport.com and sign up. A workspace is your organization's container — runs, runners, keys, and receipts all live inside it.

The onboarding wizard starts automatically. When it asks what you want to do, pick "Run governed agent sessions" (or "Both — the full platform"). Both of these end the wizard on the same final step: launching your first governed run. Don't worry about getting every wizard choice right — every screen it covers is reachable later from the app sidebar.

The wizard's last step, "Launch your first governed run", shows a live checklist of exactly what is still missing before a run can start. The next two sections are how you turn its two most common blockers green.

2. Get a runner

A runner (executor) is where agent work actually executes. You need one online runner. Two paths:

Option A — managed runner (fastest, nothing to install)

1. In the app, go to Runners → New runner.
2. Choose Managed. Viewport provisions execution in an isolated, Viewport-hosted sandbox — each run gets a fresh ephemeral environment.
3. The runner appears in your runner list with its scope and pool as returned by the platform.

Option B — self-hosted (your machine, your boundary)

Code never has to leave your machine. Install the daemon:

npm install -g @viewportai/daemon
vpd --version

vpd is the Viewport daemon — the supervision layer that pairs your machine with the workspace and executes claimed work locally.

In the app, go to Runners → New runner → Self-hosted. The app mints a pairing code (valid for 10 minutes — re-mint if it lapses). Pair this machine as a worker with that code:

vpd pair <PAIRING_CODE> --worker --transport=polling --workdir "$HOME/.viewport/worktrees"

Approve the pairing in the browser when prompted, then verify and start the worker:

vpd worker doctor --json   # paired server, workspace id, transport, detected agents
vpd worker start --mode persistent --transport polling

vpd worker doctor --json should report the workspace you paired against and that the runner is claimable. If it doesn't, see Runner won't claim work.

3. Add a model key

Agent runs call a model provider through the Viewport gateway, which holds your real provider key and hands out capped, attributed, revocable virtual keys.

In the app, go to Keys and add a provider key (Anthropic, OpenAI, or Google), or use Viewport pass-through if it is enabled for your plan — either satisfies the launch checklist.

4. Clear the launch checklist

Back in the wizard's First run step (or via Workspace setup from the home screen), the checklist shows each gate with a link to fix it:

The list refreshes automatically when you come back to the tab. When every blocking gate is green, the Launch first run button activates.

5. Launch the governed run

Click Launch first run. Viewport starts your suggested workflow on the available runner and takes you straight to the run's detail page (/runs/<run-id>).

Watch the run execute: the timeline shows policy resolution, the agent working, every model call metered through the gateway, and — if your workflow has an approval gate — a pause waiting for a human decision.

From now on, the first screen of the app is the work queue: every run, approval, and review that needs you, ranked by urgency.

6. Open the receipt

On the run detail page, click Run receipt (also reachable any time at Receipts in the sidebar, or directly at /runs/<run-id>/receipt).

The receipt is the canonical viewport.run_receipt/v1 document. It shows:

• Legs — one entry per governed fact: the policy that was in force, each LLM call with its metered cost, MCP tool calls, runner lifecycle, and human approvals. Only legs that actually happened render; nothing is fabricated.
• Verification state — honest, in three levels: finalized · software-signed (Merkle root signed with Viewport's published key), finalized · unsigned (root sealed, signature pending), or chain-only.
• Spend — real metered cost. Unpriced spend renders as unknown, never as $0.

Click Export to download the receipt JSON. Signed receipts verify offline: the digests are recomputable from the document itself, and Viewport's signing keys are published at https://api.getviewport.com/.well-known/viewport-receipt-keys — no API access required to check that a receipt is genuine and untampered.

What you just proved

In one sitting you took an agent run from "trust me" to evidence:

• the run could only start because policy gates (billing, runner, key, workflow) were satisfied — and the checklist showed you exactly which ones;
• every model call was metered and attributed through the gateway;
• the whole run is sealed into one exportable receipt a third party can verify without trusting Viewport's API.

That is the wedge: every agent run gets a receipt.

Optional: watch your local agent sessions

If you also run agents interactively (Claude Code, Codex) on your own machine, the daemon can stream those sessions into the same workspace:

vpd pair            # personal monitor pairing (no --worker)
vpd bind ~/code/my-repo

Pairing proves the machine to the workspace; binding opts one directory into monitoring. Sessions then appear under Sessions in the app. See the CLI setup reference for the worker-vs-monitor distinction.

Troubleshooting

Local daemon state lives under ~/.viewport/. For a throwaway end-to-end test on a machine you already use, set VIEWPORT_HOME to an empty directory first.