Mental model
Five concepts cover most of what you'll do day to day. Get these right and the rest of the docs read in a day.
The whole product reduces to five nouns. Learn them once.
The five
| Concept | What it is | Where it lives |
|---|---|---|
| Session | One agent run on one machine. Tool calls, prompts, transcript. All of it. | The daemon. Never the control plane. |
| Plan | A reviewable artifact the agent proposes before doing work. | Control plane, mirrored to your inbox. |
| Inbox item | Any decision the agent is waiting on. Plan review, approval gate, or new context to remember. | Control plane, routed to whoever has access. |
| Context Vault | Encrypted shared memory the agent can read from. Runbooks, conventions, project lore. | Control plane (ciphertext only). |
| Workflow | A repo-local YAML contract that wires sessions, plans, gates, and context together. | .viewport/workflows/ in your repo, mirrored to DB. |
Plus three pieces of plumbing in service of those five:
- Machine · a daemon paired to a workspace. The pairing is org-local; the daemon ships per-org identity.
- Member · a human's access to a workspace. Owners, admins, members, viewers.
- Team · an org-local group of members. Optional. Lets you address a group as a single ACL principal.
How they fit
- A workflow declares what the agent is allowed to do, what context it gets, and which steps need a human.
- When the workflow runs, it produces one or more sessions on a paired machine.
- Sessions emit plans. Gated steps pause and surface inbox items.
- Plans, gates, and context candidates draw from the context vault.
- Every decision writes to the audit log.
Three things people get wrong at first
1. Sessions are not events. There's no session.started event stream. The daemon owns the session. The browser subscribes over WebSocket to see live frames. Close every paired daemon and the session list goes empty. That's expected behavior, not a bug.
2. Inbox routing is not by project. It's by resource access. A plan or approval routes to whoever can see the underlying resource. Through a direct user share, team membership, or a share group. There's no project intermediary.
3. Everything is private by default. Org membership gives you no automatic access to other members' resources. A plan, vault, or workflow is visible only to its creator until that creator explicitly shares it with another user, a team, or a share group inside the org. The org is the tenant wall (nothing escapes it); within the wall, sharing is per-resource and explicit.
What to read next
- Sessions. The wire protocol, lifecycle, and what's not on the wire.
- Plans. The artifact shape and the review flow.
- Inbox. The three decision kinds and how routing chooses who decides.
- Context Vault. Encrypted memory the agent reads from.
- Workflows. The YAML contract that binds it all together.