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

# AI Sandboxes

> Linux and Windows VMs for AI agents, ready in seconds and billed per minute

A sandbox is a full Linux or Windows virtual machine for an AI agent to work in. Your agent runs shell commands in it. On a desktop image, it can also see and drive the screen (computer use).

A sandbox is ready in seconds: it is handed over already running from a warm pool, or woken from a saved memory image. You pay per minute from your account credit, and much less while it is stopped.

You can use sandboxes from the panel, the [API](https://docs.cloudblast.io/api-reference/sandboxes/list-images.md), the [CLI](https://docs.cloudblast.io/cli/overview.md#sandboxes) and the [MCP server](https://docs.cloudblast.io/mcp/overview.md#sandboxes). Everything done to a sandbox is in its [logs](#logs).

## Images

You create a sandbox from an image. The image decides:

* **The OS**: `linux` or `windows`.
* **The size**: vCPUs, memory and disk. Each image has a fixed size.
* **Desktop or not**: images with `desktop: true` have a desktop you can drive with [computer use](#computer-use). The others take commands only.
* **The location**: the region the sandbox runs in.

[`GET /sandboxes/images`](https://docs.cloudblast.io/api-reference/sandboxes/list-images) lists the images with their prices. `allowed` is `false` for an image that is larger than your account level allows. `in_stock` is `false` for an image that is out of stock right now: try again later, or pick an image in another location.

## Lifecycle

| Status | What it means |
| - | - |
| `creating` | Being created. Usually a few seconds. |
| `running` | Ready. You can run commands and use the desktop. |
| `stopping` | Shutting down. |
| `stopped` | Shut down. Its disk is kept, and you can start it again. |
| `starting` | Booting again from its disk. |
| `deleting` | Being destroyed. Then it is gone from the list. |
| `failed` | It could not be created. `error` says why. Destroy it to clear it. |

**Auto-stop.** A running sandbox stops by itself after `auto_stop_minutes` without activity. The default is 15 minutes. Set 0 to never stop it, or any value from 5 to 43200 minutes (30 days). Activity is starting it, running a command, a computer use action, or using its screen in the panel. Reading the sandbox or its logs does not count. `stops_at` says when it will stop if nothing happens.

**Stopped costs disk only.** A stopped sandbox keeps its disk and costs only its `stopped_hourly_price`. Start it again with [`POST /sandboxes/{sandbox}/start`](https://docs.cloudblast.io/api-reference/sandboxes/start-sandbox).

**Auto-destroy.** A stopped sandbox is destroyed after `auto_destroy_minutes`. The default is never (`-1`). You can set up to 43200 minutes. `destroys_at` says when.

**Ephemeral.** An ephemeral sandbox is destroyed as soon as it stops, whether you stop it or it stops by itself. Create it with `"ephemeral": true` (the same as `"auto_destroy_minutes": 0`). Use it for one-off jobs.

The `lifecycle` object of `GET /sandboxes/images` gives the platform's defaults and the allowed range.

## Billing

Sandboxes are billed per minute from your account credit. Prices are per hour, in the `currency` that `GET /sandboxes/images` returns.

| State | Price |
| - | - |
| Starting, running, stopping | `hourly_price`: CPU, memory and disk |
| Stopped | `stopped_hourly_price`: disk only |
| Failed or destroyed | Nothing |

When you destroy a sandbox, billing stops and the last part-minute is charged. Each sandbox shows its `current_hourly_price`, its `billed_total` and its `billed_until`.

To create a sandbox you need:

* credit for at least an hour of the sandbox (at least 0.10 EUR)
* your first top-up of 10 EUR done
* no overdue invoice
* a free slot: your account level sets how many sandboxes you may have at once (`limits.max`)
* an image within your account level's size (`allowed: true`)
* an image in stock (`in_stock: true`)

Starting a stopped sandbox also needs credit for an hour of it. If your credit runs out, your running sandboxes are stopped, and stopped ones are destroyed after 72 hours without credit.

## Environment variables

Give a sandbox environment variables when you create it, in `env`:

```json theme={null}
{
  "image_id": 3,
  "env": { "API_TOKEN": "abc123", "MODE": "test" }
}
```

* Names use letters, digits and `_`, and do not start with a digit. Up to 128 characters.
* Up to 50 variables, 32 KB in all. Values are text.
* They are in place before the sandbox shows as `running`.
* Commands you run get them, and so do the apps computer use opens. On Linux they are also in `/etc/cloudblast/sandbox.env`, which your own shells can source. On Windows they are also set as machine variables for new terminals.
* They are stored encrypted. Only the names are shown again (`env` on the sandbox), and values are never logged.
* They cannot be changed after the sandbox is created.

## Quickstart

This walks through a sandbox's whole life with `curl` and `jq`. Set your [API token](https://docs.cloudblast.io/authentication.md) first:

```bash theme={null}
export CLOUDBLAST_API_TOKEN=your-api-token
```

> [!NOTE]
>
> Send `Accept: application/json` with every sandbox request. Without it, a request that fails validation gets a redirect instead of a JSON error.

### 1. Pick an image

```bash theme={null}
curl -s https://console.cloudblast.io/api/v2/sandboxes/images \
  -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
  -H "Accept: application/json" \
  | jq '.data[] | {id, name, os, desktop, hourly_price, allowed, in_stock}'
```

Note the `id` of an image with `allowed: true` and `in_stock: true`. Pick a desktop image (`desktop: true`) to try the screenshot in step 5.

### 2. Create a sandbox

```bash theme={null}
SANDBOX=$(curl -s -X POST https://console.cloudblast.io/api/v2/sandboxes \
  -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"image_id": 3, "name": "quickstart", "env": {"GREETING": "hello"}}' \
  | jq -r '.data.uuid')
echo "$SANDBOX"
```

If the image has a warm pool, the sandbox is already `running`. Otherwise it starts as `creating`. If this prints `null`, run the request without `jq` and read the `message`: you may be out of credit or slots.

### 3. Wait until it is running

```bash theme={null}
while true; do
  STATUS=$(curl -s https://console.cloudblast.io/api/v2/sandboxes/$SANDBOX \
    -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
    -H "Accept: application/json" | jq -r '.data.status')
  echo "$STATUS"
  case "$STATUS" in running|failed) break ;; esac
  sleep 2
done
```

This usually takes a few seconds. A Windows sandbox woken cold can take longer. If it ends as `failed`, the sandbox's `error` says why.

### 4. Run a command

```bash theme={null}
curl -s -X POST https://console.cloudblast.io/api/v2/sandboxes/$SANDBOX/exec \
  -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"command": "echo $GREETING && uname -sr"}' \
  | jq .data
```

```json theme={null}
{
  "finished": true,
  "exit_code": 0,
  "stdout": "hello\nLinux 6.8.0-49-generic\n",
  "stderr": "",
  "truncated": false,
  "seconds": 0.38
}
```

Linux runs the command with `sh -c`. Windows runs it in PowerShell, so there you would write `Write-Output $env:GREETING`.

A call waits up to 60 seconds. A command still running then goes on inside the sandbox, and the answer has `finished: false`. Start long jobs in the background (for example with `nohup ... &`) and check on them with later commands.

### 5. Take a screenshot

On a desktop sandbox:

```bash theme={null}
curl -s -X POST https://console.cloudblast.io/api/v2/sandboxes/$SANDBOX/computer \
  -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"action": "screenshot", "format": "png"}' \
  | jq -r '.data.image' | base64 --decode > screen.png
```

`image` is the picture in base64. `width` and `height` are its size in pixels, the same pixels that clicks use.

### 6. Destroy it

```bash theme={null}
curl -s -X DELETE https://console.cloudblast.io/api/v2/sandboxes/$SANDBOX \
  -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
  -H "Accept: application/json" | jq -r '.data.status'
```

This prints `deleting`. Billing stops now.

## Computer use

[`POST /sandboxes/{sandbox}/computer`](https://docs.cloudblast.io/api-reference/sandboxes/computer-use) sees and drives the desktop of a running desktop sandbox. Each call does one action. It works the same on Linux and Windows.

Coordinates are screen pixels from the top left, 0 to 16384. Take a screenshot (or call `size`) first to know the screen size.

| Action | Fields | Answer |
| - | - | - |
| `screenshot` | `format`: `jpeg` (default) or `png`. `quality`: 10 to 100, for jpeg | `width`, `height`, `format`, `image` (base64) |
| `size` | | `width`, `height` |
| `cursor` | | `x`, `y` |
| `move` | `x`, `y` (required) | |
| `click` | `x`, `y` (both or neither, default: where the cursor is). `button`: `left`, `middle` or `right`. `count`: 1 to 3 | |
| `mouse_down`, `mouse_up` | `x`, `y`, `button` | |
| `drag` | `from` and `to`, each `{"x": ..., "y": ...}` (required) | |
| `scroll` | `x`, `y`. `direction`: `up`, `down` (default), `left` or `right`. `amount`: 1 to 30 (default 3) | |
| `type` | `text` (required): up to 20,000 characters, any language | |
| `key` | `keys` (required): one combination like `"ctrl+l"`, or a list like `["ctrl+a", "delete"]` (up to 20). `repeat`: 1 to 50 | |
| `open` | `target` (required): a URL, a file or an app. `args`: its arguments. `wait`: 0 to 30 seconds | |
| `windows` | | `windows`: the open windows, each with an `id` and a `title` |
| `focus` | `window` (required): an `id` from `windows`, or part of a title | |
| `read_screen` | `window` (optional). `max_nodes`: 20 to 1500 | the window's controls, as a numbered list |
| `wait` | `seconds`: 0 to 30 | |

Every answer has `ok: true`. An action that fails answers 422, with `data.ok: false` and the reason in `data.error`. Computer use counts as activity, and every action is in the sandbox's logs (without the pictures).

### See the result in the same call

The actions that change the screen (`move`, `click`, `mouse_down`, `mouse_up`, `drag`, `scroll`, `type`, `key`, `open`, `focus` and `wait`) take `"screenshot": true`. The answer then also has a `screenshot` object (`width`, `height`, `format`, `image`), taken just after the action. You can add `format` too, but `quality` only works on the `screenshot` action itself. This saves a call per step.

```bash theme={null}
curl -s -X POST https://console.cloudblast.io/api/v2/sandboxes/$SANDBOX/computer \
  -H "Authorization: Bearer $CLOUDBLAST_API_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"action": "click", "x": 640, "y": 360, "screenshot": true}' \
  | jq -r '.data.screenshot.image' | base64 --decode > after-click.jpg
```

### Read the screen as text

`read_screen` lists the controls of the window in front (or of the one you name in `window`) as a numbered list, read from the accessibility tree. Each control has its role, its name and the point to click (`x`, `y`). It is often faster and more exact than finding a button in a screenshot.

```json theme={null}
{ "action": "read_screen", "max_nodes": 200 }
```

An answer on Linux looks like this (the fields can differ a little on Windows):

```json theme={null}
{
  "data": {
    "ok": true,
    "window": { "title": "Example Domain", "app": "Firefox", "box": [0, 0, 1280, 800] },
    "nodes": [
      { "n": 1, "role": "entry", "name": "Search or enter address", "x": 640, "y": 52, "box": [200, 38, 880, 28], "value": "https://example.com/" },
      { "n": 2, "role": "link", "name": "More information...", "x": 512, "y": 418, "box": [430, 409, 164, 18] }
    ],
    "truncated": false
  }
}
```

## Logs

[`GET /sandboxes/{sandbox}/logs`](https://docs.cloudblast.io/api-reference/sandboxes/get-logs) lists what happened to the sandbox, newest first. Each event has a `source` (`panel`, `api` or `system`), an `action`, a `status` (`ok` or `failed`), a `message` and a `detail`. Calls from the CLI and the MCP server show as `api`.

* `type` narrows the list: `commands`, `computer`, `screen`, or `lifecycle` (create, start, stop, destroy, auto-stop and the like). The default is `all`.
* `limit` sets the page size, 1 to 100 (default 50).
* When `meta.more` is `true`, pass the last event's `id` as `before` to get the next page.

Commands are logged with their exit code and the first 2000 characters of their output. The values of environment variables are never logged.

## Errors

The sandbox endpoints answer errors with a `message`, not an error code:

```json theme={null}
{ "message": "Start the sandbox first." }
```

| Status | When |
| - | - |
| `404` | No sandbox with that UUID on your account. |
| `409` | The sandbox is not running. Start it first. |
| `422` | A rule was broken (no credit, no free slot, image not available, no desktop for computer use), a computer use action failed, or a field failed validation. |
| `503` | The sandbox did not answer. If it was just started, try again in a few seconds. |

When a field fails validation, the answer also has `errors`, with messages per field:

```json theme={null}
{
  "message": "The command field is required.",
  "errors": { "command": ["The command field is required."] }
}
```

A missing or wrong API token answers `401` in the usual [error format](https://docs.cloudblast.io/errors.md). A token without the permission a request needs answers `403` (`INSUFFICIENT_SCOPE`): reading needs `read`, destroying needs `delete`, and everything else needs `write`.

## Limits

| Limit | Value |
| - | - |
| Sandboxes at once | Set by your account level (`limits.max`) |
| Largest sandbox | Set by your account level (`limits.cpu`, `limits.memory_mb`) |
| Command | 8000 characters, 60 seconds per call |
| Command output | 64 KB per stream, per call |
| Typed text | 20,000 characters per `type` action |
| Environment variables | 50 variables, 32 KB in all |
| Auto-stop, auto-destroy | Up to 43200 minutes (30 days) |

Rate limits:

Each kind of call has its own count, per account, so a busy agent never runs out of room to create or stop a sandbox:

| Calls | Per minute |
| - | - |
| Computer use | 600 |
| Run command | 120 |
| Create, start and stop, together | 30 |
| Everything else (list, get, destroy, logs) | 60, shared with the rest of the API |

Computer use and run command do not count toward the 60 of the rest of the API. Over a limit, the answer is `429`: wait the number of seconds in the `Retry-After` header, then try again.


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