Skip to content

Sandboxes

Keln sandboxes are isolated Linux machines where your code or AI agents can run programs, execute commands, and work with files.

Create a sandbox through the API, run commands with streamed output, read and write files, and stop it when you're done. You pay per second based on its vCPU and memory size while the sandbox is running.

The Sandbox API is available at https://sandbox.keln.ai. It uses the same API keys and prepaid balance as the inference API.

Quickstart ↗ API reference ↗

Isolation

Each sandbox runs in its own microVM, isolated from other sandboxes.

Commands run as the default user, or as root when specified. You can also configure a network policy to control which hosts the sandbox can access.

What you can do

Task Guide
Run commands and stream output Commands and streaming
Read and write files Files
Control internet access and allowed hosts Network policy
Access servers running inside a sandbox Preview ports
Pause a sandbox and resume it later Pause and resume
Save a sandbox as an image and start new ones from it Images
Run interactive shells and programs Terminals
Give an AI assistant sandboxes and web search as tools MCP server

Templates and sizes

Every sandbox starts from a template. Use GET /v1/sandbox-templates to list available templates and their default sizes.

The default template is base. To start from your own setup instead, save a sandbox as an image.

base template
Default size 2 vCPU, 2,048 MiB memory, 10,240 MiB disk
Software Python 3 with pip and venv, Node.js with npm, git, curl, and a C toolchain
User user, home directory /home/user, passwordless sudo

You can use pip install directly with the system Python without creating a virtual environment.

To change the size, set cpu and memory_mb when creating a sandbox.

  • cpu: 1 to 4 vCPUs.
  • memory_mb: 1,024 to 8,192 MiB per vCPU, and at most 16,384 MiB.

Both values must meet the allowed memory-to-CPU ratio. For example, setting only cpu: 4 keeps the template's default 2,048 MiB of memory, which is below the minimum for 4 vCPUs, so the API rejects the request. Set both fields when changing the size.

Lifecycle

State Description Billed
starting The sandbox is starting. Requests wait until it's ready. No
running The sandbox is running and accepts requests. Yes
paused Memory, processes, and files are preserved until the sandbox resumes. No
stopped The sandbox has stopped and its contents have been deleted. No

When creating a sandbox, timeout_s determines how long it runs before stopping. The default is 300 seconds (5 minutes).

For longer workloads, set a higher timeout. You can also change the expiry using POST /v1/sandboxes/{sandbox_id}/timeout.

A sandbox can run for a maximum of 24 hours from created_at or its most recent resume.

Stopped sandboxes remain accessible through GET /v1/sandboxes/{sandbox_id}, with ended_at and end_reason populated.

end_reason Description
deleted The sandbox was stopped using DELETE /v1/sandboxes/{sandbox_id}.
timeout The sandbox reached its expires_at time.
out_of_memory The sandbox ran out of memory.
insufficient_balance The workspace balance ran out.
budget_exhausted The API key reached its budget.
suspended The account or API key was suspended.
pause_expired The sandbox remained paused for 30 days.
failed The sandbox couldn't start or stopped for another reason.

Keln may introduce additional states and end reasons. Your integration should handle values it doesn't recognize.

Pricing

Resource Price
vCPU $0.0504 per vCPU-hour
Memory $0.0162 per GiB-hour
Stored images $0.08 per GB-month

There's no monthly fee. Billing is calculated per second while a sandbox is running, based on its configured vCPU and memory.

A sandbox that starts running is billed for at least 1 second.

Time spent starting or paused isn't billed. Paused sandbox snapshots are also free.

Size Price per hour
2 vCPU, 2 GiB (base default) $0.133
2 vCPU, 4 GiB $0.166

Your balance must cover the first 5 minutes of runtime when creating or resuming a sandbox. Otherwise, the API returns 402 insufficient_balance.

If your balance runs out while sandboxes are running, Keln stops them after 60 seconds. Paused sandboxes remain paused because they don't incur charges.

You can still read, list, pause, and stop sandboxes when an API key or account is blocked, so you can stop further charges.

Limits

Limit Default Scope Error
Running sandboxes 20, or 3 before your first paid top-up Per workspace 429 concurrency_limit
Paused sandboxes 100, each kept 30 days at most Per workspace 429 paused_limit
Images 20 creating or ready Per workspace 429 image_limit
Lifetime 24 hours from created_at or the last resume Per sandbox 400 invalid_parameter
Requests 100 per second, burst to 200 Per key 429 rate_limited
Open streams, terminal sockets included 256 Per workspace 429 too_many_streams
Request body 1 MB. File uploads stream and have no limit. Per request 413 body_too_large
env 64 KB, names and values together Per object 400 invalid_parameter
metadata 50 keys, keys up to 40 characters, values up to 500 Per sandbox 400 invalid_parameter
Preview connections 256 per sandbox, 64 per client address Open at once 429 too_many_connections

Background commands do not count as open streams. The API reference lists every error code.

Where to go next

  • Quickstart ↗ Create your first sandbox, run commands, and work with files.
  • MCP server ↗ Connect Claude Code, Cursor, Codex or VS Code to sandboxes and web search, with nothing to install.
  • Data handling ↗ See how Keln handles and retains sandbox data.
  • Acceptable use ↗ Rules for running code in Keln sandboxes.