# Run code

> Run Python, JavaScript, TypeScript or bash in a new sandbox and get its output and exit code.

`code_run` runs a Python, JavaScript, TypeScript or bash snippet in a new, isolated Linux sandbox and returns what it printed, its exit code and any files you ask for. Agents use it to calculate, test code, run shell commands, or parse and transform data.

Call it with `POST /v1/tools/code_run`, or as `code_run` over [MCP](https://clonvo.com/docs/mcp.md). It answers when the code finishes, within `timeout_seconds`.

> **Warning: Keep secrets out of the code**
> 
> Don’t put passwords, API keys or personal data in the code or files. The code can reach the network, so MCP clients that auto-approve read-only tools ask before they call `code_run`.

## Arguments

-   `code` string Required
    
    The code to run. Print what you want back.
    
-   `language` string
    
    The language of code (default "python"). "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). The sandbox is billed per second.
    
-   `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.
    

## Example

```bash
curl https://api.clonvo.com/v1/tools/code_run \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "code": "import statistics\nprices = [19.5, 22.0, 18.75, 25.1]\nprint(round(statistics.mean(prices), 2))",
      "timeout_seconds": 20
    }
  }'
```

```json
{
  "id": "gen-01M6B6S0T2V4X6Z8B0D2F4H6K8",
  "tool": "code_run",
  "provider": "clonvo",
  "result": {
    "language": "python",
    "exit_code": 0,
    "output": "21.34\n",
    "truncated": false,
    "timed_out": false
  },
  "usage": { "cost": 0.0000555, "charged": 0.00005661, "is_byok": false }
}
```

### Bash with files

`files` writes text files into the sandbox before the code runs, and `return_files` reads files back after it. Relative paths are under the working directory, `/home/daytona`, and folders are created.

```bash
curl https://api.clonvo.com/v1/tools/code_run \
  -H "Authorization: Bearer $CLONVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "arguments": {
      "language": "bash",
      "code": "sort -t, -k2 -n data/sales.csv | tail -1 | tee top.txt",
      "files": [{ "path": "data/sales.csv", "content": "north,120\nsouth,340\neast,95\n" }],
      "return_files": ["top.txt"]
    }
  }'
```

```json
{
  "id": "gen-01M6B6S0T2V4X6Z8B0D2F4H6K9",
  "tool": "code_run",
  "provider": "clonvo",
  "result": {
    "language": "bash",
    "exit_code": 0,
    "output": "south,340\n",
    "truncated": false,
    "timed_out": false,
    "files": [{ "path": "top.txt", "size": 10, "encoding": "utf-8", "content": "south,340\n" }]
  },
  "usage": { "cost": 0.000037, "charged": 0.00003774, "is_byok": false }
}
```

## Result

| Field | Description |
| --- | --- |
| `language` | The language the code ran as. |
| `exit_code` | The process’s exit code: `0` when the code finished without an error. `null` when it hit `timeout_seconds`. |
| `output` | What the code printed, stdout and stderr together. |
| `truncated` | `true` when the output was longer than 50,000 characters. Clonvo then keeps its first 10,000 and last 40,000 characters, where errors usually are. |
| `timed_out` | `true` when the code was stopped at `timeout_seconds`. Its output is lost then; the call still succeeds and is billed. |
| `files` | Present when you passed `return_files`: one entry per path, in the order you asked. See [Returned files](#returned-files). |
| `notes` | Present when something wasn’t returned, such as charts the code showed. |

### Returned files

| Field | Description |
| --- | --- |
| `path` | The path as you passed it. |
| `size` | The file’s size in bytes, or `null` when it doesn’t exist or is a folder. |
| `encoding` | `utf-8` when `content` is the file’s text, `base64` for anything else, such as images and archives. |
| `content` | The file’s contents. |
| `error` | Present instead of `content` when the file wasn’t returned: it doesn’t exist, it’s a folder, or it’s too large. |

Each file is returned up to 1 MB, and all of them up to 2 MB together; past that, `error` says so. Files are read back after a timeout too, so code that may run long can write its progress to a file.

## Notes

-   Each call gets a fresh sandbox (1 vCPU, 1 GiB of memory, 3 GiB of disk) that is deleted when the code finishes, so nothing carries over between calls. Install packages, run and print within one call.
-   Python includes common packages such as numpy and pandas. `bash` runs the code as a bash script, with the same tools the sandbox has (Python, Node.js, git, curl).
-   Charts aren’t returned on their own: save them with `savefig` and name the file in `return_files`.
-   Up to 10 `files` of up to 1,000,000 characters each, and up to 10 `return_files`. Moving files gets 30 seconds in all.
-   A failed program is still a result: an exception gives a non-zero `exit_code` and the traceback in `output`.
-   Sandboxes are billed per second, from when Clonvo asks for one until it’s deleted. Starting a sandbox adds a second or two.
-   On Clonvo credits, Clonvo holds the cost of `timeout_seconds` plus 30 seconds (60 with files) before the code runs; see [Code runs on credits](https://clonvo.com/docs/tool-billing.md#code-runs-on-credits).
-   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).