Skip to content

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:

{
  "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.

OpenAI Responses

OpenAI's hosted tools work unchanged. code_interpreter lets the model run Python:

{
  "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.

{
  "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.

{
  "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.

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.