What is workspaces.build
The product definition, the problem it solves, and the boundaries of what the platform does and does not do.
workspaces.build is an API that executes agent actions on isolated compute, and bills for the execution by the second.
A customer organization integrates once, then calls the API every time its agent needs to do something it cannot do inside the model context: call a tool, evaluate code, run a command, drive a browser, operate a desktop. The platform decides where that runs, starts the runtime, streams the result back, tears it down, and emits the usage events that become an invoice line.
The problem
Agent products need execution, and execution is where agent products get expensive, slow and unsafe all at once.
- Unsafe. An agent runs attacker-influenced instructions. Model output reaching a shell on a shared host is a breach waiting for a prompt injection. Containers alone are not a defensible boundary against untrusted code.
- Slow. A cold container is hundreds of milliseconds. A cold VM with a desktop is tens of seconds. Agent loops make many calls, so start latency multiplies through the loop and dominates perceived response time.
- Expensive and unattributable. Teams provision long-lived VMs because starting them is slow, then pay for idle. And when the buyer is a platform reselling to its own customers, there is usually no way to answer "which of my customers burned this".
The common response — one big container image with everything in it, kept warm, shared across tenants — is the worst answer to all three. It pays desktop-class cost for tool-call-class work, and it puts every capability behind one boundary so the weakest workload sets the blast radius.
The answer: tier the compute
Split execution into five tiers. Each tier is a fixed bundle of capability, isolation boundary, start-latency class and price.
A caller declares a tier when it creates a session. The tier is not a hint — it is the contract. A
tier 1 session's own running code cannot spawn a subprocess of its own — os.system,
subprocess.Popen and the like fail with a denied syscall at the sandbox boundary, not a silent
escalation. Reaching for genuinely more capability (a CLI toolchain, a real filesystem) is always an
explicit new session at a higher tier, which keeps both the security boundary and the bill
predictable.
Pick the lowest tier that can do the job. Every step up the ladder costs more per second, starts slower, and widens the blast radius of a compromised agent. Choosing a tier has the decision table.
What the platform is responsible for
| Area | What workspaces.build provides |
|---|---|
| Execution | Starting, running and tearing down the runtime for all five tiers |
| Isolation | Process, gVisor, microVM and full-VM boundaries, plus per-session policy enforcement |
| Latency | Warm pools and snapshot restore sized to hold each tier's start-latency SLO |
| State | Ephemeral scratch, persistent volumes, snapshot and restore |
| Network | Default-deny egress, per-session allowlists, a filtering proxy, metered bandwidth |
| Observability | Per-session logs, traces, metrics, browser and desktop recordings, OTel export |
| Metering | Usage events per meter, rated against the org's price list |
| Billing | Prepaid credits, postpaid invoices, spend caps, per-end-user attribution |
| Access | Organizations, projects, RBAC, API keys, scoped end-user tokens, audit log |
What the platform is not
- Not a model provider. workspaces.build runs the agent's actions. The agent loop and the model calls stay with the customer. The platform never needs the customer's model keys.
- Not a general VM host. There is no "give me a box forever" product. Sessions have idle timeouts and maximum lifetimes. Persistence is explicit, through volumes and snapshots.
- Not an agent framework. No orchestration, planner or memory layer. The API is deliberately below that line so any framework can sit on top.
- Not a CI system. Runs are interactive and latency-sensitive, not queued batch builds. There is no pipeline DSL.
Who buys it
| Buyer | Shape of usage | What they care about most |
|---|---|---|
| Agent product teams | Steady tier 1 and tier 2, bursty tier 3 | p95 start latency, egress control |
| AI platforms reselling to their own customers | All tiers, tagged per end user | Per-end-user metering, quotas, spend caps |
| Enterprises with internal agents | Tier 2 and tier 4, long sessions | Data residency, audit log, SSO, private networking |
| Evaluation and benchmark harnesses | Very high tier 1 concurrency, short runs | Concurrency ceiling, cold-start tail, price per run |
How the rest of these docs are organised
- Agent tiers — what each tier can do, what it runs on, what it costs.
- Architecture — how the platform is built, for the infra team.
- Data model — the objects, their identifiers and their state machines.
- API — conventions, then resource-by-resource design, then the generated reference.
- Billing — meters, rating, quotas, invoices.
- Dashboard — the two consoles and what each one owns.
- Security — the isolation argument and the policy engine.
- Operations — SLOs, capacity, runbooks, incident response.