Skip to main content
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, the CLI and the MCP server. Everything done to a sandbox is in its 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. The others take commands only.
  • The location: the region the sandbox runs in.
GET /sandboxes/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

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. 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. 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:
  • 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 first:
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

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

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

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

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:
image is the picture in base64. width and height are its size in pixels, the same pixels that clicks use.

6. Destroy it

This prints deleting. Billing stops now.

Computer use

POST /sandboxes/{sandbox}/computer 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. 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.

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.
An answer on Linux looks like this (the fields can differ a little on Windows):

Logs

GET /sandboxes/{sandbox}/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:
When a field fails validation, the answer also has errors, with messages per field:
A missing or wrong API token answers 401 in the usual error format. A token without the permission a request needs answers 403 (INSUFFICIENT_SCOPE): reading needs read, destroying needs delete, and everything else needs write.

Limits

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