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

# Sandbox & lifecycle

> Execution modes, provisioned resources, and the running → sleeping → parked → destroyed lifecycle of a computer.

Every [computer](/docs/computer/index) is a real Linux micro-VM provisioned by Vetta's compute layer with a fixed slice of vCPU, memory, and disk. This page covers how much you get, how to override it, and the states a computer moves through over its life.

<Info>
  A fully virtualized **V8-isolate** mode (`mode: "isolate"`) is **coming soon**. Today every computer is a micro-VM; everything below describes it.
</Info>

## Resources

A computer is provisioned with an explicit slice of **vCPU, memory, and disk** — there are no fixed instance classes. Defaults match the platform default (**2 vCPU / 4 GiB**); raise them per workload up to the ceilings below. Resources are set at create time and priced per running-second on what you provisioned.

| Resource | Default            | Range                  |
| -------- | ------------------ | ---------------------- |
| vCPU     | `2`                | `1`–`16`               |
| Memory   | `4096` MiB (4 GiB) | `128`–`65536` MiB      |
| Disk     | service default    | whole GiB, up to `100` |

<CodeGroup>
  ```bash CLI theme={"system"}
  vetta computer create --name box --vcpu 4 --memory-mb 8192 --disk-gb 40
  ```

  ```typescript TypeScript theme={"system"}
  const computer = await vetta.computers.create({
    name: "box",
    vcpu: 4,
    memoryMb: 8192,
    diskGb: 40,
  });
  ```

  ```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", "vcpu": 4, "memory_mb": 8192, "disk_gb": 40 }'
  ```
</CodeGroup>

## What it costs

There is **no creation fee**. A computer is **metered per running-second** on its provisioned vCPU and memory, plus per-second **storage** on its disk (the first **5 GiB are free**). A computer that is paused incurs **no compute cost — only storage**. Exact per-second rates are on [Limits & billing](/docs/computer/limits-and-billing#the-compute-meter).

## Lifecycle

A computer moves through a small set of states. Only **running** costs compute.

<Steps>
  <Step title="running">
    The VM is live and metered per second on its provisioned resources. This is the state during an agent's turn and whenever you exec directly.
  </Step>

  <Step title="sleeping">
    Free. The VM is idle with its disk (and memory) preserved. It **wakes automatically** on the next exec or file operation, or on an explicit `resume`. This is the state the runtime uses between turns.
  </Step>

  <Step title="parked">
    Free, but explicit. A parked computer must be resumed before it will accept work — exec and file operations are **rejected while parked**. Use it to hold a computer indefinitely without paying for compute.
  </Step>

  <Step title="destroyed">
    Terminal. Disk, memory, and any attached ephemeral state are torn down. See [Snapshots & volumes](/docs/computer/snapshots-and-volumes) to persist state across a destroy.
  </Step>
</Steps>

### Sleeping vs. parked

Both are free, but they differ in how the next operation is handled:

|              | Wakes on next op?  | Explicit resume required? | Ops while in state     |
| ------------ | ------------------ | ------------------------- | ---------------------- |
| **sleeping** | Yes, automatically | No                        | Auto-woken, then run   |
| **parked**   | No                 | Yes                       | Rejected until resumed |

<Tip>
  You rarely park manually. The runtime sleeps and wakes a computer automatically around each turn — parking is for deliberately holding a computer out of rotation. See [Runtime & durability](/docs/concepts/runtime).
</Tip>

```bash CLI theme={"system"}
vetta computer pause box     # park: storage-only, explicit resume required
vetta computer resume box    # wake a sleeping or parked computer
```

## Auto-destroy

A computer is **automatically destroyed** when either of these happens:

* The organization's real-USD balance is **exhausted** (credit exhaustion). See [Budgets](/docs/concepts/budgets) and [Limits & billing](/docs/computer/limits-and-billing).
* It exceeds its **max runtime** — **12 hours** by default.

<Warning>
  Auto-destroy is irreversible and tears down sandbox disk. Anything the agent should keep must be promoted with `publish_file` to [Files](/docs/capabilities/files) or captured as a [checkpoint / volume](/docs/computer/snapshots-and-volumes) beforehand.
</Warning>

## Concurrency

A computer counts toward your organization's **concurrency cap** the entire time it is `running`, `sleeping`, or `parked` — i.e. any time it is not destroyed. Only a destroy frees the slot. The cap is a configurable per-organization limit; see [Limits & billing](/docs/computer/limits-and-billing#concurrency).

## Configuration reference

Fields accepted by `create`:

<ParamField path="vcpu" type="integer" default="2">
  Provisioned vCPU. Range **1–16**.
</ParamField>

<ParamField path="memory_mb" type="integer" default="4096">
  Provisioned memory in **MiB**. Range **128–65536** (0.125–64 GiB).
</ParamField>

<ParamField path="disk_gb" type="integer">
  Root disk size in whole **GiB**, up to **100**.
</ParamField>

<ParamField path="size" type="string">
  Optional convenience preset (`small`, `medium`, `large`) that expands to a common `vcpu`/`memory_mb`/`disk_gb` combination. Explicit resource fields override the preset. Presets are Vetta shorthand — the underlying provisioning is always the explicit vCPU/memory/disk above.
</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="allow_inbound" type="boolean" default="true">
  Allow inbound network to the sandbox. **Set at create time only** — immutable afterward.
</ParamField>

<ParamField path="allow_outbound" type="boolean" default="true">
  Allow outbound network from the sandbox. **Set at create time only** — immutable afterward. `false` is a complete kill-switch; see [what is and is not blocked](/docs/computer/networking#what-is-blocked-precisely).
</ParamField>

<ParamField path="idle_timeout_minutes" type="integer">
  Auto-pause the computer after this many minutes idle. See [lifecycle](#lifecycle).
</ParamField>

<ParamField path="max_duration_hours" type="number">
  Hard ceiling on total runtime before auto-destroy. See [Limits & billing](/docs/computer/limits-and-billing).
</ParamField>

<ParamField path="env" type="object">
  Environment variables injected into the sandbox.
</ParamField>

<ParamField path="metadata" type="object">
  Arbitrary key-value tags.
</ParamField>

<Card title="Next: filesystem" icon="folder-tree" href="/docs/computer/filesystem">
  Read, write, list, and manage files on the sandbox disk.
</Card>