Images
You create a sandbox from an image. The image decides:- The OS:
linuxorwindows. - The size: vCPUs, memory and disk. Each image has a fixed size.
- Desktop or not: images with
desktop: truehave 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 thecurrency 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)
Environment variables
Give a sandbox environment variables when you create it, inenv:
- 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 (
envon 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 withcurl 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
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
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
failed, the sandbox’s error says why.
4. Run a command
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
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.
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.
typenarrows the list:commands,computer,screen, orlifecycle(create, start, stop, destroy, auto-stop and the like). The default isall.limitsets the page size, 1 to 100 (default 50).- When
meta.moreistrue, pass the last event’sidasbeforeto get the next page.
Errors
The sandbox endpoints answer errors with amessage, not an error code:
When a field fails validation, the answer also has
errors, with messages per field:
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.