# Code execution
Let Keln models run Python and shell commands while generating a response. Keln creates an isolated Linux sandbox,
runs the model's code, and returns the results to the model before it answers.
Code execution works with all Keln chat models through the Chat Completions, Responses, and Anthropic-compatible APIs.
You can use your existing OpenAI or Anthropic SDK without additional setup.
**Code execution vs. Sandboxes**
Use code execution when you want a model to run code as part of a response. Each response gets a temporary sandbox
that is deleted when the response ends.
Use [Sandboxes](../sandboxes/quickstart.md) when your application or agent needs to control a machine directly, access
the network, or keep files between requests.
Code execution costs $0.0001 per second of sandbox time, with a 30-second minimum ($0.003), plus model tokens.
Responses that don't run code have no additional charge.
## Enable code execution
Code execution is disabled by default. Enable it by including a code execution tool in your request.
### OpenAI Chat Completions
Chat Completions has no standard code execution tool, so Keln accepts the Responses API tool format in `tools`:
```json
{
"model": "zai-org/glm-5.3",
"messages": [...],
"tools": [
{
"type": "code_interpreter",
"container": { "type": "auto" }
}
]
}
```
The Responses API's shell tool also works with Chat Completions.
You can configure optional limits using `code_execution`. See [Settings](#settings).
### OpenAI Responses
OpenAI's hosted tools work unchanged. `code_interpreter` lets the model run Python:
```json
{
"model": "zai-org/glm-5.3",
"input": "...",
"tools": [
{
"type": "code_interpreter",
"container": { "type": "auto" }
}
]
}
```
`shell` lets it run shell commands. Send both to offer both.
```json
{
"model": "zai-org/glm-5.3",
"input": "...",
"tools": [
{
"type": "shell",
"environment": { "type": "container_auto" }
}
]
}
```
### Anthropic Messages
Anthropic's server tool works unchanged. The model can run shell commands and Python.
```json
{
"model": "zai-org/glm-5.3",
"messages": [...],
"tools": [
{
"type": "code_execution_20250825",
"name": "code_execution"
}
]
}
```
## Execution environment
Keln creates a sandbox when the model first runs code. Each response gets its own sandbox with the following
environment:
| Resource | Specification |
|---|---|
| Operating system | Ubuntu 24.04 |
| CPU | 2 vCPUs |
| Memory | 2 GiB |
| Disk | 10 GiB |
| Python | 3.12 |
| Node.js | 24 |
| Network | Disabled |
**Preinstalled software**
Python packages: `numpy`, `pandas`, `scipy`, `scikit-learn`, `statsmodels`, `sympy`, `matplotlib`, `seaborn`,
`pyarrow`, `openpyxl`, `xlsxwriter`, `python-docx`, `python-pptx`, `pypdf`, `pdfplumber`, `reportlab`, and `pillow`.
Other tools: `gcc`, `git`, `curl`, `jq`, `ripgrep`, and `sqlite3`.
**Files and execution**
- Files persist between commands within the same response. Keln deletes the sandbox and its files when the response
ends.
- Each Python execution starts a new interpreter. Variables don't persist between runs, but files do.
- The sandbox has no network access. The model can't download data or install additional packages.
- The sandbox takes no files. Include the data in your prompt instead.
- Keln returns command output, not generated files. For example, a chart saved to disk isn't returned and is deleted
with the sandbox. The model must print the information you need.
## Responses and tool output
The model decides when to run code and can execute multiple commands before producing its final answer.
Each API returns execution details in its native format.
| API | Execution results |
|---|---|
| Chat Completions | Hidden by default. Enable with `code_execution.include_events: true`. |
| Responses | `code_interpreter_call` for Python, or `shell_call` and `shell_call_output` for shell commands. |
| Anthropic Messages | `server_tool_use` and `bash_code_execution_tool_result` blocks. |
### Chat Completions
With `code_execution.include_events: true`:
- **Streaming:** Begin and end events appear in `delta.provider_specific_fields.keln_code_execution`.
- **Non-streaming:** Execution history appears in `message.provider_specific_fields.keln_code_execution.calls`.
Each event includes `phase`, `id`, `tool` (`bash` or `python`), and `input`.
End events also include `status`, `stdout`, `stderr`, and `exit_code`, or `outcome: "timeout"`. If execution couldn't
start, the event contains `error`.
### Responses API
Python executions return a `code_interpreter_call` item containing the code and its output.
Shell executions return `shell_call` and `shell_call_output` items with stdout, stderr, and exit code. Both include
lifecycle events.
### Anthropic-compatible API
Execution returns a `server_tool_use` block with `bash_code_execution` and the command, followed by a
`bash_code_execution_tool_result` block containing stdout, stderr, and return code.
Python executions appear as the shell commands used to run them.
### Usage reporting
Sandbox time appears in:
| API | Usage field |
|---|---|
| Chat Completions | `usage.code_execution_seconds` |
| Responses | `usage.code_execution_seconds` |
| Anthropic Messages | `usage.server_tool_use.code_execution_seconds` |
On Chat Completions, `usage.cost` includes the code execution fee.
For streaming Chat Completions and Responses requests, Keln sends a keepalive comment every 5 seconds while a command
runs.
## Pricing
Code execution costs **$0.0001 per second**, plus model token usage.
Billing starts when the model first runs code and ends when the response finishes. This includes time spent generating
text between and after commands.
Sandbox time is rounded up to the nearest second, with a minimum charge of 30 seconds ($0.003) per response that runs
code.
| Execution time | Sandbox cost |
|---|---|
| 10 seconds | $0.003 |
| 30 seconds | $0.003 |
| 2 minutes | $0.012 |
Model tokens are billed separately at the model's published rates.
Each time the model processes command output, the conversation history counts as input again. Repeated context is
billed at the cached rate when served from cache.
Failed and timed-out commands are billed because the sandbox was running. If the model never executes code, there is no
sandbox charge.
## Settings
Chat Completions supports the following settings through `code_execution`:
| Setting | Default | Maximum |
|---|---|---|
| `max_tool_calls` | 20 | 30 |
| `timeout_ms` | 120,000 ms | 300,000 ms |
| `max_output_length` | 16,384 bytes | 65,536 bytes |
The Responses and Anthropic-compatible APIs use the default settings.
Values above the maximum are capped automatically and reported in the `x-keln-inert-params` header.
**Execution limits**
The model receives the configured limits. When it reaches the maximum number of code runs, Keln asks it to finish the
response using the results already available.
Commands that exceed the timeout are stopped. The model receives any output produced before the timeout.
Output exceeding the configured size is truncated, and the model is informed so it can produce a shorter result.
## Using other tools
Code execution works alongside your own function tools when `tool_choice` is `"auto"`.
With `tool_choice: "none"` or a forced tool choice, code execution is not offered to the model. Keln processes the
request normally and reports the ignored setting in `x-keln-inert-params`.
Function tools named `bash` or `python` cannot be used alongside code execution. Requests containing either return
`400 code_execution_name_reserved`.
**Code execution and web search cannot be enabled in the same request.** Such requests return
`server_tools_combined_unavailable`.
## Sandbox lifetime
Each response gets a new sandbox. You can't reuse a sandbox across responses.
Referencing an earlier sandbox with `container_reference` on a shell tool or a container ID on `code_interpreter`
returns `400 container_expired`.
You can, however, include previous execution results in the conversation history:
- **Responses API:** Pass previous `code_interpreter_call`, `shell_call`, and `shell_call_output` items.
- **Anthropic-compatible API:** Include the previous tool result blocks.
These records tell the model what previously ran and what it returned. They don't execute again or incur additional
sandbox charges.
## Compatibility
Some API parameters are accepted but not applied.
**Responses API**
- `skills` on the shell tool are ignored.
- `max_tool_calls` is ignored.
- `include: ["code_interpreter_call.outputs"]` is ignored because outputs are always returned.
Ignored parameters are reported in `x-keln-inert-params`.
**Anthropic-compatible API**
`code_execution_20260120` and `code_execution_20260521` are supported using `code_execution_20250825` behavior.
Files persist between code runs within a response, but Python variables do not.
## Privacy
Code execution runs in an isolated Linux virtual machine with no network access, provided by a third-party sandbox
provider.
The code, command output, and generated files exist only in the sandbox, which is deleted when the response ends.
Keln doesn't store code execution content or output. Debugging logs may contain a short excerpt of a command, but never
its output.
See [Privacy & zero data retention](privacy.md#code-execution).
## Errors
| Code | Meaning |
|---|---|
| `code_execution_name_reserved` | A function tool named `bash` or `python` conflicts with code execution. |
| `container_expired` | The request references a sandbox from an earlier response. |
| `memory_tier_unavailable` | `memory_limit` exceeds the available 2 GiB. |
| `network_unavailable` | `network_policy` allows hosts, and the sandbox has no network access. |
| `file_upload_unavailable` | `file_ids` asks to put files into the sandbox, and the sandbox takes no files. |
| `server_tools_combined_unavailable` | Web search and code execution are enabled in the same request. |
Code execution
Let Keln models run Python and shell commands while generating a response. Keln creates an isolated Linux sandbox,
runs the model's code, and returns the results to the model before it answers.
Code execution works with all Keln chat models through the Chat Completions, Responses, and Anthropic-compatible APIs.
You can use your existing OpenAI or Anthropic SDK without additional setup.
Code execution vs. Sandboxes
Use code execution when you want a model to run code as part of a response. Each response gets a temporary sandbox
that is deleted when the response ends.
Use Sandboxes when your application or agent needs to control a machine directly, access
the network, or keep files between requests.
Code execution costs $0.0001 per second of sandbox time, with a 30-second minimum ($0.003), plus model tokens.
Responses that don't run code have no additional charge.
Enable code execution
Code execution is disabled by default. Enable it by including a code execution tool in your request.
OpenAI Chat Completions
Chat Completions has no standard code execution tool, so Keln accepts the Responses API tool format in tools:
Other tools: gcc, git, curl, jq, ripgrep, and sqlite3.
Files and execution
Files persist between commands within the same response. Keln deletes the sandbox and its files when the response
ends.
Each Python execution starts a new interpreter. Variables don't persist between runs, but files do.
The sandbox has no network access. The model can't download data or install additional packages.
The sandbox takes no files. Include the data in your prompt instead.
Keln returns command output, not generated files. For example, a chart saved to disk isn't returned and is deleted
with the sandbox. The model must print the information you need.
Responses and tool output
The model decides when to run code and can execute multiple commands before producing its final answer.
Each API returns execution details in its native format.
API
Execution results
Chat Completions
Hidden by default. Enable with code_execution.include_events: true.
Responses
code_interpreter_call for Python, or shell_call and shell_call_output for shell commands.
Anthropic Messages
server_tool_use and bash_code_execution_tool_result blocks.
Chat Completions
With code_execution.include_events: true:
Streaming: Begin and end events appear in delta.provider_specific_fields.keln_code_execution.
Non-streaming: Execution history appears in message.provider_specific_fields.keln_code_execution.calls.
Each event includes phase, id, tool (bash or python), and input.
End events also include status, stdout, stderr, and exit_code, or outcome: "timeout". If execution couldn't
start, the event contains error.
Responses API
Python executions return a code_interpreter_call item containing the code and its output.
Shell executions return shell_call and shell_call_output items with stdout, stderr, and exit code. Both include
lifecycle events.
Anthropic-compatible API
Execution returns a server_tool_use block with bash_code_execution and the command, followed by a
bash_code_execution_tool_result block containing stdout, stderr, and return code.
Python executions appear as the shell commands used to run them.
Usage reporting
Sandbox time appears in:
API
Usage field
Chat Completions
usage.code_execution_seconds
Responses
usage.code_execution_seconds
Anthropic Messages
usage.server_tool_use.code_execution_seconds
On Chat Completions, usage.cost includes the code execution fee.
For streaming Chat Completions and Responses requests, Keln sends a keepalive comment every 5 seconds while a command
runs.
Pricing
Code execution costs $0.0001 per second, plus model token usage.
Billing starts when the model first runs code and ends when the response finishes. This includes time spent generating
text between and after commands.
Sandbox time is rounded up to the nearest second, with a minimum charge of 30 seconds ($0.003) per response that runs
code.
Execution time
Sandbox cost
10 seconds
$0.003
30 seconds
$0.003
2 minutes
$0.012
Model tokens are billed separately at the model's published rates.
Each time the model processes command output, the conversation history counts as input again. Repeated context is
billed at the cached rate when served from cache.
Failed and timed-out commands are billed because the sandbox was running. If the model never executes code, there is no
sandbox charge.
Settings
Chat Completions supports the following settings through code_execution:
Setting
Default
Maximum
max_tool_calls
20
30
timeout_ms
120,000 ms
300,000 ms
max_output_length
16,384 bytes
65,536 bytes
The Responses and Anthropic-compatible APIs use the default settings.
Values above the maximum are capped automatically and reported in the x-keln-inert-params header.
Execution limits
The model receives the configured limits. When it reaches the maximum number of code runs, Keln asks it to finish the
response using the results already available.
Commands that exceed the timeout are stopped. The model receives any output produced before the timeout.
Output exceeding the configured size is truncated, and the model is informed so it can produce a shorter result.
Using other tools
Code execution works alongside your own function tools when tool_choice is "auto".
With tool_choice: "none" or a forced tool choice, code execution is not offered to the model. Keln processes the
request normally and reports the ignored setting in x-keln-inert-params.
Function tools named bash or python cannot be used alongside code execution. Requests containing either return
400 code_execution_name_reserved.
Code execution and web search cannot be enabled in the same request. Such requests return
server_tools_combined_unavailable.
Sandbox lifetime
Each response gets a new sandbox. You can't reuse a sandbox across responses.
Referencing an earlier sandbox with container_reference on a shell tool or a container ID on code_interpreter
returns 400 container_expired.
You can, however, include previous execution results in the conversation history:
Responses API: Pass previous code_interpreter_call, shell_call, and shell_call_output items.
Anthropic-compatible API: Include the previous tool result blocks.
These records tell the model what previously ran and what it returned. They don't execute again or incur additional
sandbox charges.
Compatibility
Some API parameters are accepted but not applied.
Responses API
skills on the shell tool are ignored.
max_tool_calls is ignored.
include: ["code_interpreter_call.outputs"] is ignored because outputs are always returned.
Ignored parameters are reported in x-keln-inert-params.
Anthropic-compatible API
code_execution_20260120 and code_execution_20260521 are supported using code_execution_20250825 behavior.
Files persist between code runs within a response, but Python variables do not.
Privacy
Code execution runs in an isolated Linux virtual machine with no network access, provided by a third-party sandbox
provider.
The code, command output, and generated files exist only in the sandbox, which is deleted when the response ends.
Keln doesn't store code execution content or output. Debugging logs may contain a short excerpt of a command, but never
its output.