> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Code interpreter

> Sandboxed code execution in ClickHouse Agents

[Beta feature](https://clickhouse.com/docs/reference/settings/beta-and-experimental-features.md#beta-features)

The code interpreter lets an agent execute code in a managed sandbox. Use it for computation, data transformation, format conversion, plotting, and anything else better done in code than in natural language.

## Enable the code interpreter

In the Agent Builder, enable **Run Code** in the **Capabilities** section, then save. The agent decides when to run code based on the user's request and the agent's instructions.

![Run Code section of the Capabilities panel with the Run Code checkbox enabled and an Upload to Code Environment button](https://mintcdn.com/private-7c7dfe99/i3Gw7HRb0YxPr7dq/images/cloud/agent-builder/run-code/run-code.webp?fit=max\&auto=format\&n=i3Gw7HRb0YxPr7dq\&q=85\&s=00125f4a580b82198fdd9dc20dc6d25f)

## Supported languages

The sandbox is a Unix environment with two general-purpose runtimes and a few shell utilities:

* **Python 3** - the default for data tasks.
* **Node.js (JavaScript)** - when an agent prefers JS for the job.
* **Bash** and **sh** - shell scripting for chaining commands and quick I/O.
* **AWK** and **sed** - line-oriented text processing.
* **bc** - arbitrary-precision math.

Agents reach for Python first for anything involving data parsing, transformation, or computation.

> [!TIP]
>
> Reserve the shell tools for tasks that genuinely benefit from a one-liner.

## Files

Users can upload files into a conversation; the code interpreter has access to them in the sandbox working directory. Code can also write output files (CSVs, plots, archives) which appear in the conversation as downloadable attachments.

## Sandbox isolation

Each execution runs in an ephemeral sandbox with no network access and no persistent storage. Sessions don't share state — variables and files from one run don't carry into the next unless the agent explicitly re-loads them.

Plan-specific resource limits (memory, files per run, monthly request quotas) apply. Errors and stderr are surfaced in the conversation alongside stdout.

## When to use it

Reach for the code interpreter when the answer requires deterministic computation that a language model can't produce reliably by reasoning alone.
Typical cases include:

* Parsing a CSV or JSON file the user uploaded.
* Computing summary statistics or running a quick simulation.
* Converting between formats (Parquet, JSON, CSV).
* Generating a plot from query results.

> [!TIP]
>
> Avoid it for tasks the model can already answer from context.
> Code execution adds latency and consumes quota.
