Introducing the computer: a micro-VM for every agent session

Every Vetta session gets an isolated Linux micro-VM with a shell, a filesystem and an optional real browser. It pauses between turns, so an idle agent costs storage only. Here is how it works and what it costs.

Somewhere to run the code

Agents write code constantly, and the moment they do they need somewhere to run it. Not a deployment or a cluster. A shell, a disk, and a way to look at the result. Every Vetta session gets exactly that: a computer, a disposable Linux micro-VM that Vetta provisions and operates, wired into the same durable runtime that runs the harness.

This post is about that machine: what is inside it, how it maps onto the session's turn cycle, and what it costs. The Computer and Sandbox primitive pages summarize the surface; the computer reference has every field.

One computer per session, paused between turns

The runtime runs one bounded harness turn, commits the transcript, and sleeps. The computer's lifecycle is bound to that same cycle:

• While the agent takes a turn, the computer is running and metered per second on the vCPU and memory it was provisioned with.
• Between turns, waiting on a schedule, a human reply, or a long external job, the computer is sleeping. No vCPU and no memory are metered.
• The next shell command or file operation wakes it automatically, filesystem intact, in roughly 300 ms.

That is the first of the runtime's efficiency levers: most wall-clock time on a long task is spent waiting, and waiting is nearly free. An agent that works for twenty minutes across an eight-hour window pays for twenty minutes of compute.

A computer moves through four states. Only one of them costs compute.

You rarely park manually; the runtime sleeps and wakes the computer around each turn. Only cold boots pay the full provisioning cost, about two seconds from a clean image and about three from a snapshot.

A real Linux box, not a restricted runtime

Every computer is a full Linux userland with an explicit slice of resources set at create time. There are no fixed instance classes: raise vCPU, memory, and disk per workload up to the ceilings. A session's own computer is provisioned at 1 vCPU / 1 GiB; the defaults below apply when you create one yourself.

Inside a session the agent reaches the machine through built-in tools. Each one is a governed action, quoted against the agent's budget before it runs and subject to the agent's policy of allow, ask, or deny.

Shell

The bash tool runs a command as bash -c in a non-login shell and returns buffered stdout, stderr, and an exit_code once the process exits or timeout_ms elapses. You can set a cwd for the call, and env for the call only; nothing persists to the next command. Output is capped at 262,144 characters each for stdout and stderr. It is a single request and response, not a stream, so a long-running command should write progress to a file that the agent reads back. Details: Shell.

Filesystem

Five operations cover the disk: read, write, list, mkdir, and remove. They take absolute paths, move binary data with encoding: "base64", and are capped at 4 MiB per file per read or write. list returns immediate children including dotfiles; remove is recursive and refuses /. Scratch work lives here. Anything the agent should hand back is promoted with publish_file to Files, which is organization-scoped and outlives the sandbox. Details: Filesystem.

Browser

A computer can have an optional managed browser attached. It is a real browser, driven through goto, click, type, extract, and screenshot, and every action re-validates the current page URL against a required allowed_domains list, so a redirect off the allow-list is blocked. Private, loopback, and cloud metadata hosts are always blocked regardless of the list. A guard refuses credential-shaped input through type, write-looking actions are blocked unless allow_writes is set, and screenshots land in Files as a fil_ id rather than as bytes in the transcript. Sessions default to a 15-minute timeout and can run up to six hours. The browser carries no charge of its own; what a browsing agent pays for is the tokens it spends driving it. Details: Browser.

Networking: out, not in

A computer has general outbound access by default, so the agent can install packages, call APIs, and fetch data without configuration. The filter on the egress path is not a general private-address block, so here it is exactly: cloud metadata (169.254.0.0/16), 10.0.0.0/8, and 172.16.0.0/12 are unreachable from bash and tools; 192.168.0.0/16 is not reliably blocked; the sandbox's own loopback is reachable, because it is the agent's own machine. Do not treat "RFC1918 is blocked" as a security boundary for the shell.

The one control that is a boundary is allow_outbound: false at create time: a complete, verified kill-switch for all outbound traffic, immutable for the life of the computer. The browser is different. Its private, loopback, and metadata block is enforced by us on every action and does hold.

Inbound is the other direction, and today there is none: no port-preview surface, so a sandbox reaches out and nothing reaches in. Coming soon, all sandbox HTTPS egress will be pinned through Vetta's egress proxy so the vault can substitute secrets at the network boundary; the sandbox, the model, and your logs only ever see opaque placeholders. Details: Networking.

Snapshots, forks and volumes

State on a computer is ephemeral by default: a destroy tears it down. Three mechanisms make it outlive a single machine.

A snapshot is a durable checkpoint taken without stopping the VM. The computer keeps running while its disk is captured, so the agent can mark a known-good baseline mid-task. A fork creates a new computer from a snapshot, with its own lifecycle and billed like any fresh create. Prepare one baseline, then fork several computers to try different approaches in parallel. A persistent volume, attached at create time, keeps the computer's disk and its paused memory alive across park and sleep. Volumes protect state across the idle cycle, not across a destroy; anything you must keep permanently belongs in Files.

Details: Snapshots and volumes.

Driving a computer directly

Sessions provision their computer for you. You can also drive one from the CLI or the TypeScript SDK.

# Create with explicit resources and a browser (--browser requires --allowed-domains)
vetta computer create --name box --vcpu 2 --memory-mb 4096 --browser --allowed-domains "*.example.com"
 
# Run commands, read back the buffered result
vetta computer exec box -- "ls -la /workspace"
 
# Files: operation first, then the computer
vetta computer fs write box --path /workspace/notes.txt --content "hello"
vetta computer fs read box --path /workspace/notes.txt
 
# Checkpoint without stopping, then boot a fork from the returned snapshot_id
vetta computer snapshot box
vetta computer create --name box-2 --snapshot <snapshot_id>
 
# Hold it for free, wake it later, or tear it down
vetta computer pause box
vetta computer resume box
vetta computer delete box

The SDK is one method per route.

import { randomUUID } from "node:crypto";
import { createClient } from "@usenaive-sdk/vetta";
 
const client = createClient({
  baseUrl: "https://api.vetta.sh",
  apiKey: process.env.VETTA_API_KEY!,
  fetch: globalThis.fetch,
  idempotencyKey: () => randomUUID(),
});
 
const box = await client.computers.create({ name: "scratch", vcpu: 2, memory_mb: 4096 });
 
await client.computers.fs(box.id, "write", { path: "/workspace/main.py", content: "print(40 + 2)\n" });
const result = await client.computers.exec(box.id, "python3 /workspace/main.py", 30_000);
// { stdout: "42\n", stderr: "", exit_code: 0, duration_ms: 412 }
 
const snapshot = await client.computers.snapshot(box.id);
const fork = await client.computers.create({ name: "variant-b", snapshot_id: snapshot.snapshot_id });
 
await client.computers.pause(box.id); // no vCPU or memory metered until resume
await client.computers.delete(fork.id);

What it costs, exactly

There is no creation fee. A running computer is metered per second on its provisioned vCPU and memory, booked against the agent's budget at the end of each turn and drawn from the organization's prepaid USD balance.

A session's computer is 1 vCPU / 1 GiB, so a full hour of running time is $0.0504 + $0.0162 = $0.0666; a computer you create at the 2 vCPU / 4 GiB default is $0.1656. A sleeping or parked computer meters no vCPU and no memory. Compute spend appears as the computer component of the agent's spend breakdown and as a line item on the organization ledger, reported on the wire in integer micro-USD.

Two failsafes bound the downside. A computer is auto-destroyed when the organization's balance is exhausted, or when it exceeds its max runtime, max_duration_hours, 12 hours by default. That ceiling is wall-clock from create to destroy, not billed seconds, so a computer that sleeps most of the window still hits it on schedule. An optional idle_timeout_minutes pauses a computer to storage-only after it sits idle. Every non-destroyed computer counts toward the organization's concurrency cap, 25 computers and 10 browser sessions by default, raised on request. Details: Limits and billing.

What is next

Everything above describes the micro-VM that ships today. A fully virtualized V8 isolate mode (mode: "isolate") is coming soon for the lightweight majority of agent work, with near-instant boot and near-zero idle. Vault secret substitution on sandbox egress is also coming; today vault injection is live only on the MCP connector path, where credentials never enter the sandbox.

Get started

Create an agent with a budget and give it work; its session provisions the computer. Or provision one yourself with vetta computer create. The full surface is in the computer reference, and the Vetta launch post covers how the computer fits alongside completion windows and budgets.