# Sandboxes
> Create a sandbox that lasts between calls, run code and servers in it, move files, and open its ports with preview links.
Sandboxes are isolated Linux machines that last between calls, for work that takes more than one step: install packages once and keep using them, build and test a project, keep files, or run a web server and open it in a browser. `sandbox_create` makes one and returns a `sandbox_id`; `sandbox_run`, `sandbox_files`, `sandbox_preview` and `sandbox_delete` act on it.
A sandbox lasts `ttl_minutes` (5–60, 15 by default) and is then deleted with everything in it, whatever it’s doing. For one snippet with nothing to keep, [`code_run`](https://clonvo.com/docs/code-run.md) is simpler.
Call them with `POST /v1/tools/<id>`, or over [MCP](https://clonvo.com/docs/mcp.md).
> **Warning: Keep secrets out of sandboxes**
>
> Don’t put passwords, API keys or personal data in a sandbox. Code in it can reach the network, and anyone with a preview link can open what it serves until the link expires.
## Example
Create a sandbox with a file in it:
```bash
curl https://api.clonvo.com/v1/tools/sandbox_create \
-H "Authorization: Bearer $CLONVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"arguments": {
"ttl_minutes": 30,
"files": [{ "path": "site/index.html", "content": "<h1>Hello</h1>" }]
}
}'
```
```json
{
"id": "gen-01M6B6S0T2V4X6Z8B0D2F4H6KA",
"tool": "sandbox_create",
"provider": "clonvo",
"result": {
"sandbox_id": "sbx_clonvo_c4f919a3-db35-417f-81d2-411f80ef423f",
"expires_at": "2026-11-15T02:32:36.796Z",
"working_directory": "/home/daytona",
"files_written": ["site/index.html"]
},
"usage": { "cost": 0.03441, "charged": 0.0350982, "is_byok": false }
}
```
Start a web server in the background:
```bash
curl https://api.clonvo.com/v1/tools/sandbox_run \
-H "Authorization: Bearer $CLONVO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"arguments": {
"sandbox_id": "sbx_clonvo_c4f919a3-db35-417f-81d2-411f80ef423f",
"code": "cd site && python3 -m http.server 3000",
"background": true
}
}'
```
```json
{
"id": "gen-01M6B6S0T2V4X6Z8B0D2F4H6KB",
"tool": "sandbox_run",
"provider": "clonvo",
"result": {
"sandbox_id": "sbx_clonvo_c4f919a3-db35-417f-81d2-411f80ef423f",
"language": "bash",
"exit_code": null,
"output": "",
"truncated": false,
"timed_out": false,
"background": { "pid": 180, "log_path": "/tmp/clonvo/bg-9e6d7cd3.log" },
"notes": ["Started in the background. Read its output from /tmp/clonvo/bg-9e6d7cd3.log with sandbox_files; stop it and what it started with sandbox_run: kill -- -180."]
},
"usage": { "cost": 0, "charged": 0, "is_byok": false }
}
```
Then get a link to it with `sandbox_preview`:
```json
{
"tool": "sandbox_preview",
"arguments": { "sandbox_id": "sbx_clonvo_c4f919a3-db35-417f-81d2-411f80ef423f", "port": 3000 }
}
```
The result’s `url` opens the server in any browser until `expires_at`.
## `sandbox_create`
Creates a sandbox (1 vCPU, 1 GiB of memory, 3 GiB of disk) and waits for it to start, which takes a second or two.
- `ttl_minutes` integer
How long the sandbox lasts, in minutes (5–60, default 15). It’s deleted with everything in it after that. The call is priced for this whole time.
- `files` object\[\]
Text files to write into the sandbox when it’s created (at most 10). Relative paths are under the working directory, /home/daytona; folders are created.
| Field | Description |
| --- | --- |
| `sandbox_id` | Pass it to the other sandbox tools. |
| `expires_at` | When the sandbox is deleted, with everything in it. |
| `working_directory` | Where commands run and relative paths point: `/home/daytona`. |
| `files_written` | The `files` written, in order. Present when you passed `files`. |
## `sandbox_run`
Runs Python, JavaScript, TypeScript or bash in the sandbox and returns what it printed and its exit code, like [`code_run`](https://clonvo.com/docs/code-run.md#result). Files, installed packages and running processes stay between calls. `language` is `bash` by default.
With `background: true` (bash only), the command starts in its own process group and the call returns at once with `background.pid` and `background.log_path`, where its output goes. Read the log with `sandbox_files`, and stop it with `kill -- -<pid>`. Servers should listen on `0.0.0.0`.
- `sandbox_id` string Required
The sandbox_id sandbox_create returned, like "sbx_clonvo\_…".
- `code` string Required
The code or commands to run. Print what you want back.
- `language` string
The language of code (default "bash"). "bash" runs code as a bash script.
One of `python` `javascript` `typescript` `bash`
- `timeout_seconds` integer
The longest the code may run, in seconds (1–120, default 30).
- `background` boolean
Start the code in the background and return at once, for servers and other long-running commands (bash only). Its output goes to the log_path returned.
- `files` object\[\]
Text files to write into the sandbox before the code runs (at most 10). Relative paths are under the working directory, /home/daytona; folders are created.
- `return_files` string\[\]
Paths of files to read back after the run (at most 10), relative to /home/daytona or absolute. Each is returned up to 1 MB, 2 MB in all.
## `sandbox_files`
Writes, reads and lists files without running code. `write` takes text files and creates folders; `read` returns each file like `code_run`’s [returned files](https://clonvo.com/docs/code-run.md#returned-files); `list` returns a folder’s entries, folders first, up to 500. They run in that order, so one call can write a file and read it back.
- `sandbox_id` string Required
The sandbox_id sandbox_create returned, like "sbx_clonvo\_…".
- `write` object\[\]
Text files to write into the sandbox first (at most 10). Relative paths are under the working directory, /home/daytona; folders are created.
- `read` string\[\]
Paths of files to read back after any write (at most 10), relative to /home/daytona or absolute. Each is returned up to 1 MB, 2 MB in all.
- `list` string
A folder to list, e.g. "." for /home/daytona. At most 500 entries.
## `sandbox_preview`
Returns an https link to a port in the sandbox. The link carries its own token: anyone who has it can open the port until `expires_at`, which is `expires_minutes` from now (60 by default) or when the sandbox is deleted, whichever is sooner. `listening` says whether anything answered on the port when the link was made.
- `sandbox_id` string Required
The sandbox_id sandbox_create returned, like "sbx_clonvo\_…".
- `port` integer Required
The port the server listens on, e.g. 3000.
- `expires_minutes` integer
How long the link works, in minutes (1–60, default 60); never past the sandbox’s own expiry.
## `sandbox_delete`
Deletes the sandbox and everything in it. Sandboxes are deleted on their own at `expires_at`, so this is only needed to finish sooner or to make room under the limit below.
- `sandbox_id` string Required
The sandbox_id sandbox_create returned, like "sbx_clonvo\_…".
## Notes
- A `sandbox_id` names the account the sandbox was made on: Clonvo credits (`sbx_clonvo_…`) or one of your Daytona keys (`sbx_pk_…`). Every call on the sandbox goes there, whatever `provider` the request sets. If that key is deleted, its sandboxes can’t be reached.
- On Clonvo credits, `sandbox_create` is charged for the whole `ttl_minutes` plus a minute, at Daytona’s rate for the sandbox’s size, plus the tool margin; the other sandbox tools are free, and nothing is refunded when you delete a sandbox early. See [Sandboxes on credits](https://clonvo.com/docs/tool-billing.md#sandboxes-on-credits).
- On Clonvo credits an organization can have 3 sandboxes at once and create 3 a minute. On your own Daytona key, your Daytona account’s limits apply.
- Each organization only reaches its own sandboxes: a `sandbox_id` from another organization answers `404` with `sandbox_not_found`, the same as a deleted one.
- Network access follows the Daytona account’s tier. Sandboxes on Clonvo credits reach package registries such as PyPI and npm, and GitHub.
- Code and files are free text, like a prompt, so they’re never stored as a [web tool query](https://clonvo.com/docs/privacy.md#web-tool-queries).