> ## 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.

# Computers

> Sandboxed compute environments with a browser and filesystem.

A **computer** is a durable, sandboxed environment an [agent](/docs/api/agents) can use: a shell, a filesystem, and an optional browser constrained to an allowlist of domains. Computers can be paused to stop compute charges and snapshotted for fast restore.

Every [session](/docs/api/sessions) whose toolset needs a filesystem provisions one of these for itself and reports it as `computer_id`. Those appear in this list named `session {id}`, so you can tell them from the ones you created; their lifecycle is the session's, not yours.

## The computer object

<ResponseField name="id" type="string">Unique id (e.g. `cmp_01H...`).</ResponseField>
<ResponseField name="object" type="string">Always `computer`.</ResponseField>
<ResponseField name="name" type="string">Human-readable name.</ResponseField>
<ResponseField name="vcpu" type="integer">Provisioned vCPU for a micro-VM (1–16).</ResponseField>
<ResponseField name="memory_mb" type="integer">Provisioned memory in MiB (128–65536).</ResponseField>
<ResponseField name="disk_gb" type="integer">Root disk size in GiB.</ResponseField>
<ResponseField name="status" type="string">Lifecycle state — see [below](#lifecycle).</ResponseField>

<ResponseField name="browser" type="object">
  Browser configuration, or `null` if disabled.

  <Expandable title="browser">
    <ResponseField name="allowed_domains" type="string[]">Domain allowlist (supports wildcards, e.g. `*.example.com`).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="volume" type="object | null">Attached persistent volume. Always `null` — a volume separate from the boot disk is not provisioned today; size the root disk with `disk_gb`.</ResponseField>
<ResponseField name="snapshot_id" type="string | null">Snapshot this computer was restored from, if any.</ResponseField>
<ResponseField name="created_at" type="string">Creation timestamp.</ResponseField>

## Lifecycle

| Status      | Meaning                                                          |
| ----------- | ---------------------------------------------------------------- |
| `creating`  | Provisioning; not yet usable.                                    |
| `running`   | Ready and billable for compute.                                  |
| `paused`    | Stopped; storage cost only. Resume to use again.                 |
| `failed`    | Provisioning failed; the computer never became usable. Terminal. |
| `destroyed` | Permanently deleted. Terminal.                                   |

## Create a computer

`POST /v1/computers` → `202 Accepted`. Provisioning is asynchronous: the response returns immediately with `status: "creating"`. **Wait for readiness before using the computer**: poll `GET /v1/computers/{id}` until `status` is `running`. There is no computer lifecycle [event](/docs/api/events) to subscribe to — the event stream is session-scoped. If provisioning fails the computer moves to `failed`, and calls that need a live machine return `409` with code `computer_unavailable`.

<ParamField body="name" type="string">Human-readable name. Defaults to `computer`.</ParamField>
<ParamField body="vcpu" type="integer">Provisioned vCPU. Defaults to `2`.</ParamField>
<ParamField body="memory_mb" type="integer">Provisioned memory in MiB. Defaults to `4096`.</ParamField>
<ParamField body="disk_gb" type="integer">Root disk size in GiB. Defaults to `5`.</ParamField>
<ParamField body="browser" type="object | null">Browser config — `{ "allowed_domains": ["*.example.com"] }`. Defaults to `null`, which disables the browser.</ParamField>
<ParamField body="snapshot_id" type="string">Snapshot (`snp_…`) to restore this computer from.</ParamField>

<CodeGroup>
  ```bash cURL theme={"system"}
  curl -fsSL https://api.vetta.sh/v1/computers \
    -H "authorization: Bearer sk_live_..." \
    -H "content-type: application/json" \
    -H "idempotency-key: $(uuidgen)" \
    -d '{ "name": "box", "vcpu": 4, "memory_mb": 8192, "disk_gb": 40, "browser": { "allowed_domains": ["*.example.com"] } }'
  ```
</CodeGroup>

<ResponseExample>
  ```json Response theme={"system"}
  {
    "id": "cmp_01H8YZ...",
    "object": "computer",
    "name": "box",
    "vcpu": 4,
    "memory_mb": 8192,
    "disk_gb": 40,
    "status": "creating",
    "browser": { "allowed_domains": ["*.example.com"] },
    "volume": null,
    "snapshot_id": null,
    "created_at": "2026-08-20T17:00:00Z"
  }
  ```
</ResponseExample>

## Retrieve & list

```bash theme={"system"}
GET /v1/computers/{id}     # retrieve one -> 200 (poll status here)
GET /v1/computers          # list (cursor-paginated) -> 200
```

See [Pagination](/docs/api/pagination) for list parameters.

## Execute a command

`POST /v1/computers/{id}/exec` → `200 OK`. Runs a shell command and returns its output. The computer must be `running`; a `creating`, `paused`, or `failed` computer returns `409` with code `computer_unavailable`.

<ParamField body="command" type="string" required>The command to run.</ParamField>
<ParamField body="timeout_ms" type="integer">Max runtime before the command is killed. Defaults to `30000`.</ParamField>

```bash theme={"system"}
curl -fsSL https://api.vetta.sh/v1/computers/cmp_01H8YZ.../exec \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "command": "ls -la /workspace" }'
```

```json Response theme={"system"}
{ "exit_code": 0, "stdout": "total 8\n...", "stderr": "", "duration_ms": 42 }
```

## Pause & resume

Pausing stops compute charges while retaining state. Resuming makes it usable again.

```bash theme={"system"}
POST /v1/computers/{id}/pause    # -> 200, status: paused
POST /v1/computers/{id}/resume   # -> 200, status: running
```

```json Response theme={"system"}
{ "id": "cmp_01H8YZ...", "status": "paused" }
```

## Snapshot

`POST /v1/computers/{id}/snapshot` → `201 Created`. Captures the current filesystem state for fast restore. Pass the returned `snapshot_id` when creating a new computer.

```bash theme={"system"}
curl -fsSL https://api.vetta.sh/v1/computers/cmp_01H8YZ.../snapshot \
  -H "authorization: Bearer sk_live_..."
```

```json Response theme={"system"}
{ "snapshot_id": "snp_0368aa449de84e308959ca72744a3bd5", "computer_id": "cmp_01H8YZ...", "created_at": "2026-08-20T18:00:00Z" }
```

## Filesystem

The disk is reached through the governed `fs/*` operations — there is no separate upload/download channel. Each takes an absolute path. See [Filesystem](/docs/computer/filesystem) for limits and encoding details.

### Read a file

`POST /v1/computers/{id}/fs/read` → `200`

<ParamField body="path" type="string" required>Absolute path of the file to read.</ParamField>
<ParamField body="encoding" type="string">`text` (default) or `base64`. Ask for `base64` when the file is not valid UTF-8 — decoding binary as text substitutes U+FFFD and loses bytes silently.</ParamField>

```json Response theme={"system"}
{ "path": "/workspace/notes.txt", "encoding": "text", "content": "hello\n" }
```

### Write a file

`POST /v1/computers/{id}/fs/write` → `200`

<ParamField body="path" type="string" required>Absolute path to write or overwrite.</ParamField>
<ParamField body="content" type="string" required>The file contents, in the named encoding.</ParamField>
<ParamField body="encoding" type="string">`text` (default) or `base64` for binary payloads.</ParamField>

### List a directory

`POST /v1/computers/{id}/fs/list` → `200`

<ParamField body="path" type="string" required>Absolute path of the directory; lists its immediate children.</ParamField>

### Create a directory

`POST /v1/computers/{id}/fs/mkdir` → `200`

<ParamField body="path" type="string" required>Absolute path to create; parents are created too (`mkdir -p`).</ParamField>

### Remove a path

`POST /v1/computers/{id}/fs/remove` → `200`

<ParamField body="path" type="string" required>Absolute path to remove; directories are removed recursively (`rm -rf`).</ParamField>

```bash theme={"system"}
curl -fsSL https://api.vetta.sh/v1/computers/cmp_01H8YZ.../fs/list \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "path": "/workspace" }'
```

```json Response theme={"system"}
{ "entries": [ { "name": "report.md", "type": "file" } ] }
```

<Note>
  To persist an artifact beyond the computer's lifetime, publish it to [Files](/docs/api/files) (Vetta object storage) rather than leaving it on the computer's disk.
</Note>

## Destroy

`DELETE /v1/computers/{id}` → `200 OK`. Permanently destroys the computer and its non-snapshotted disk.

```json Response theme={"system"}
{ "id": "cmp_01H8YZ...", "object": "computer", "deleted": true }
```

A computer a [session](/docs/api/sessions) provisioned for itself — listed as `session {id}` — cannot be
destroyed while that session can still run a turn: the call is `computer_unavailable` (409) naming
the session. Cancel the session to release the box, or let it finish; a session's computer is
destroyed with it, and one left resting at `idle` is reclaimed after an hour of silence.