> ## Documentation Index
> Fetch the complete documentation index at: https://vetta.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Computer

> Vetta's own managed sandbox — a disposable Linux micro-VM with a filesystem, a shell, and an optional browser, paused when the agent sleeps.

A **computer** is where an agent does work: a disposable Linux micro-VM with a real filesystem, a shell, and an optional managed browser. It is provisioned and operated entirely by Vetta's compute layer and wired into the [durable runtime](/docs/concepts/runtime), so it **pauses when the agent sleeps and resumes on the next turn** — idle wall-clock time costs storage, not compute.

<Info>
  A fully virtualized **V8-isolate** mode (`mode: "isolate"`) — near-instant boot, near-zero idle, for the lightweight majority of agent work — is **coming soon**. Everything on this page describes the micro-VM that ships today.
</Info>

<Info>
  The computer — sandbox, filesystem, shell, browser, snapshots, and volumes — is available today. The [vault](/docs/identity/vault)'s sandbox-egress secret substitution is **coming soon**; vault injection on the [MCP connector](/docs/capabilities/tools#mcp-connector) path is live. Those sections are marked inline.
</Info>

## How it maps to the turn cycle

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

* When the agent takes a turn, its computer is **running** and metered per second on the vCPU, memory, and disk it was provisioned with.
* Between turns — waiting on a schedule, a human reply, or a long external job — the computer **sleeps** or is **parked**, and you pay for stored disk only.
* The next exec or file operation **wakes it automatically**, filesystem intact.

This is the mechanism behind Vetta's low cost on hours-long tasks: most wall-clock time is spent waiting, and waiting is nearly free. See [Idle costs storage, not compute](/docs/concepts/runtime#idle-costs-storage-not-compute).

## The toolset the agent gets

Inside a session the agent reaches the computer through built-in tools. Each is a governed, individually [priced](/docs/computer/limits-and-billing) action, quoted against the [budget](/docs/concepts/budgets) before it runs.

<CardGroup cols={3}>
  <Card title="Shell" icon="terminal" href="/docs/computer/shell">
    The `bash` tool runs a command and returns buffered stdout, stderr, and an exit code.
  </Card>

  <Card title="Filesystem" icon="folder-tree" href="/docs/computer/filesystem">
    `read`, `write`, `list`, `mkdir`, and `remove` over the sandbox's disk — the [canonical file API](/docs/computer/filesystem).
  </Card>

  <Card title="Browser" icon="globe" href="/docs/computer/browser">
    An optional managed browser: `goto`, `click`, `type`, `extract`, `screenshot`.
  </Card>
</CardGroup>

## Create a computer

A computer is created with explicit **resources** (vCPU, memory, disk) — or an optional `small`/`medium`/`large` preset — and, optionally, a managed browser. There is **no creation fee**: you are metered per running-second while it runs, and storage-only while it sleeps. See [Sandbox & lifecycle](/docs/computer/sandbox) for resources and states.

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta computer create \
    --name box \
    --size medium \
    --browser \
    --allowed-domains "*.example.com"
  ```

  ```typescript TypeScript theme={"system"}
  const computer = await vetta.computers.create({
    name: "box",
    size: "medium",
    browser: { allowedDomains: ["*.example.com"] },
  });
  ```

  ```bash cURL theme={"system"}
  curl https://api.vetta.sh/v1/computers \
    -H "Authorization: Bearer $VETTA_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "box",
      "size": "medium",
      "browser": { "allowed_domains": ["*.example.com"] }
    }'
  ```
</CodeGroup>

## Explore the reference

| Page                                                   | What it covers                                                                                                        |
| ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| [Sandbox & lifecycle](/docs/computer/sandbox)               | Provisioned resources, presets, the running → sleeping → parked → destroyed lifecycle, auto-destroy, and concurrency. |
| [Filesystem](/docs/computer/filesystem)                     | `write`, `read`, `list`, `mkdir`, `remove`, size caps, and binary via base64.                                         |
| [Shell](/docs/computer/shell)                               | The `bash` tool: fields, buffering, output caps, and wake behavior.                                                   |
| [Browser](/docs/computer/browser)                           | The managed browser: session creation, `allowed_domains`, saved logins, actions, and safety guards.                   |
| [Snapshots & volumes](/docs/computer/snapshots-and-volumes) | Checkpoints, forks, persistent volumes, and pause/resume.                                                             |
| [Networking](/docs/computer/networking)                     | Outbound access, HTTP preview URLs, and the coming egress pinning.                                                    |
| [Limits & billing](/docs/computer/limits-and-billing)       | Concurrency caps, max runtime, output/file caps, and the full metering model.                                         |

## Configuration reference

Fields accepted by `create`:

<ParamField path="name" type="string" required>A human-readable name, unique within the organization.</ParamField>
<ParamField path="vcpu" type="integer" default="2">Provisioned vCPU (1–16). See [resources](/docs/computer/sandbox#resources).</ParamField>
<ParamField path="memory_mb" type="integer" default="4096">Provisioned memory in MiB (128–65536).</ParamField>
<ParamField path="disk_gb" type="integer">Root disk size in whole GiB (up to 100).</ParamField>
<ParamField path="size" type="string">Optional preset (`small`, `medium`, `large`) — shorthand for a vCPU/memory/disk combination.</ParamField>
<ParamField path="mode" type="string" default="vm"><span>**`isolate` coming soon (Phase 5).**</span> Execution mode. Today every computer is a micro-VM (`vm`); a fully virtualized `isolate` mode ships in Phase 5.</ParamField>
<ParamField path="browser" type="object | boolean" default="false">Attach a managed browser. When enabled, `allowed_domains` is required.</ParamField>
<ParamField path="volume" type="string">Attach a [persistent volume](/docs/computer/snapshots-and-volumes#persistent-volumes) that survives park and sleep.</ParamField>
<ParamField path="snapshot" type="string">Boot from a [checkpoint](/docs/computer/snapshots-and-volumes#checkpoints) instead of a clean image.</ParamField>

<Card title="Next: sandbox & lifecycle" icon="server" href="/docs/computer/sandbox">
  Provisioned resources, states, and how a computer is metered and torn down.
</Card>