# 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](../platform/authentication.md) and prepaid [balance](../platform/billing.md) as the inference API.
[Quickstart ↗](quickstart.md){ .md-button .md-button--primary }
[API reference ↗](../api/sandboxes.md){ .md-button }
## 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](network.md) to control which hosts the sandbox can access.
## What you can do
| Task | Guide |
|---|---|
| Run commands and stream output | [Commands and streaming](commands.md) |
| Read and write files | [Files](files.md) |
| Control internet access and allowed hosts | [Network policy](network.md) |
| Access servers running inside a sandbox | [Preview ports](ports.md) |
| Pause a sandbox and resume it later | [Pause and resume](pause-resume.md) |
| Save a sandbox as an image and start new ones from it | [Images](images.md) |
| Run interactive shells and programs | [Terminals](terminals.md) |
| Give an AI assistant sandboxes and web search as tools | [MCP server](mcp.md) |
## 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](images.md).
| | `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](pause-resume.md). | 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](../platform/authentication.md#per-key-budgets). |
| `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](images.md) | $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](../api/sandboxes.md#errors) lists
every error code.
## Where to go next
<div class="grid cards" markdown>
- [Quickstart ↗](quickstart.md)
Create your first sandbox, run commands, and work with files.
- [MCP server ↗](mcp.md)
Connect Claude Code, Cursor, Codex or VS Code to sandboxes and web search, with nothing to install.
- [Data handling ↗](data-handling.md)
See how Keln handles and retains sandbox data.
- [Acceptable use ↗](acceptable-use.md)
Rules for running code in Keln sandboxes.
</div>
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.
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}.
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.