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

# vetta computer

> Provision and control sandboxes.

Manage [computers](https://vetta.sh/docs/capabilities/computer.md) — disposable Linux sandboxes with an optional browser.

## Commands

| Command | Description |
| - | - |
| `vetta computer create` | Create a computer. |
| `vetta computer list` | List computers. |
| `vetta computer show <id>` | Show a computer. |
| `vetta computer exec <id>` | Run a shell command. |
| `vetta computer pause <id>` | Park the sandbox (storage-only cost). |
| `vetta computer resume <id>` | Wake the sandbox. |
| `vetta computer snapshot <id>` | Capture state to boot from later. |
| `vetta computer build-3d <id> <script.py> --engine <cad\|blender>` | Build, check and render a 3D model from a script. |
| `vetta computer delete <id>` | Destroy the sandbox. |

## create

```bash theme={"system"}
vetta computer create --name box --vcpu 2 --memory-mb 4096 --browser --allowed-domains "*.example.com"
```

| Flag | Description |
| - | - |
| `--name` | Human-readable name (required). |
| `--vcpu` | Provisioned vCPU, 1–16 (default 2). |
| `--memory-mb` | Provisioned memory in MiB, 128–65536 (default 4096). |
| `--disk-gb` | Root disk size in GiB (up to 100). |
| `--mode` | **`isolate` coming soon (Phase 5).** Today every computer is a micro-VM (`vm`). |
| `--size` | Optional preset (`small` \| `medium` \| `large`). **Not available yet** — no preset is defined, so passing it is an error; set `--vcpu`, `--memory-mb` and `--disk-gb`. |
| `--browser` | Attach a managed browser. |
| `--allowed-domains` | Optional with `--browser`; comma-separated globs, or `*`. Absent, the open web. |
| `--volume <id>` | Attach a persistent volume. |
| `--snapshot <id>` | Boot from a snapshot. |

## exec, pause, resume, snapshot

```bash theme={"system"}
vetta computer exec box -- "ls -la /workspace"
vetta computer pause box
vetta computer resume box
vetta computer snapshot box
```

Snapshots take no `--name`: the call returns a `snapshot_id`, and that id is the handle you pass to
`vetta computer create --snapshot`. Passing `--name` is a hard error, not an ignored flag.

> [!TIP]
>
> Computers pause automatically when the agent sleeps between turns, so you rarely pause manually. See [Runtime & durability](https://vetta.sh/docs/concepts/runtime.md).

## build-3d

Runs a [build123d](https://github.com/gumyr/build123d) (`cad`, millimetres) or Blender (`blender`, metres) script in the computer, checks the result, renders previews and publishes the exports as files. Same body and answer as [`POST /v1/computers/{id}/build-3d`](https://vetta.sh/docs/api/computers#build-a-3d-model).

```bash theme={"system"}
vetta computer build-3d cmp_01J... bracket.py --engine cad --name bracket --export step,stl --views iso,top --out ./bracket
```

```json theme={"system"}
{
  "ok": true,
  "files": [
    { "file_id": "fil_01J...", "name": "bracket.step", "content_type": "model/step", "bytes": 48211 },
    { "file_id": "fil_01K...", "name": "bracket.stl", "content_type": "model/stl", "bytes": 120884 }
  ],
  "previews": ["fil_01L...", "fil_01M..."],
  "checks": { "valid_solid": true, "watertight": true, "bbox_mm": [60, 40, 12], "volume_cm3": 14.2, "triangles": 2416 },
  "error": null,
  "log_tail": "",
  "compute_seconds": 6.4
}
```

| Flag | Description |
| - | - |
| `--engine` | **Required.** `cad` (the script assigns `result`, a build123d shape) or `blender` (the script builds the scene). |
| `--name` | Base name of the outputs, `[a-z0-9_-]`, up to 64. Defaults to the script's file name. |
| `--export` | Comma-separated: `step`, `stl`, `3mf`, `glb`, `obj`, `blend`. Default `step,stl` for `cad`, `glb` for `blender`. |
| `--views` | Comma-separated preview angles, up to 4: `iso`, `front`, `top`, `side`. Default `iso`. |
| `--size` | Preview size in pixels, 256–1024. Default 768. |
| `--timeout` | Seconds the script may run, 10–300. Default 120. |
| `--out` | Download the exports and previews into this directory. |

A script that fails answers `ok: false` with `error: { message, line }` and exits `1`. For `cad`, STEP, STL and 3MF are published only when the solid is valid and watertight. There is no fee of its own: the build is billed as the computer's running seconds.

## fs

One command covers the whole filesystem surface. The **operation comes first**, then the computer:
`vetta computer fs <read|write|list|mkdir|remove> <computer-id> --path <path>`.

```bash theme={"system"}
vetta computer fs list cmp_01a02ad8ba0f7bd59115bfd513fc6ed7 --path /etc
```

```json theme={"system"}
{
  "entries": [
    { "name": ".pwd.lock", "type": "file" },
    { "name": "X11", "type": "dir" }
  ]
}
```

```bash theme={"system"}
vetta computer fs read cmp_01a02ad8ba0f7bd59115bfd513fc6ed7 --path /etc/hostname
```

```json theme={"system"}
{
  "path": "/etc/hostname",
  "encoding": "text",
  "content": "eager-falcon-96c0\n"
}
```

`write` takes `--content`, and `--encoding base64` carries bytes that are not text. `remove` and
`mkdir` take only `--path`. Passing the computer id where the operation belongs is a usage error, not
a request:

```
usage: fs op must be read|write|list|mkdir|remove, got "cmp_01a02ad8ba0f7bd59115bfd513fc6ed7"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.