Code interpreter
Run model-authored Python in a zero-egress sandbox – Firecracker on KVM hosts, gVisor everywhere else.
The code interpreter lets an agent run Python to compute, transform data, and produce files (for example a chart), then hand the result back into the chat as a downloadable artefact. The code the model writes runs in an isolated, network-less sandbox – never on the host.
What the sandbox guarantees
- Zero egress. The sandbox has no network interface and no route out, so injected code cannot fetch or exfiltrate anything, even in principle. An outbound socket simply fails.
- Ephemeral. A fresh sandbox is built for each execution and destroyed afterwards. Nothing persists between runs, and no leftover sandboxes remain.
- Least privilege. Read-only root filesystem, a non-root user, dropped capabilities, no new privileges, and CPU / memory / wall-clock limits. A runaway loop is killed at the wall-clock cap.
The image ships with numpy, pandas, matplotlib, and openpyxl baked in. There is no network, so there
is no runtime pip; the analysis libraries are fixed in the image.
Two backends, one behaviour
The interpreter picks its sandbox backend from the host's capabilities. The behaviour and the security guarantees are identical; only the isolation mechanism differs.
| Host | Backend | Isolation |
|---|---|---|
Bare-metal, on-prem, or a VM with KVM (/dev/kvm) | Firecracker microVM | Strongest: a real hardware boundary |
| A VM guest without nested virt, or a normal Docker/VM host (no KVM) | gVisor (runsc) | An application kernel in userspace, no KVM needed |
| A fully locked, unprivileged container (some managed PaaS) | none | The interpreter reports it is unavailable with a clear message |
gVisor's systrap platform intercepts guest syscalls in userspace, so it needs no hardware virtualization
and runs on the shared GPU hosts where Firecracker cannot. This is why the code interpreter works on a
rented cloud GPU box that has no /dev/kvm, as well as on your own bare-metal server.
Enable it
Code interpreter is a boot feature. In the config (or .env):
[features]
code_interpreter = true
[code_interpreter]
backend = "auto" # auto | firecracker | gvisor | off
# gVisor (KVM-less hosts):
runsc_bin = "runsc"
gvisor_rootfs = "/opt/pai/firecracker/rootfs"
gvisor_state_dir = "/run/pai/gvisor"
# Firecracker (KVM hosts) keeps its own [code_interpreter_vm] block.auto selects Firecracker when /dev/kvm is present, otherwise gVisor when runsc is available,
otherwise it reports unavailable. Set backend explicitly to pin one. The sandbox image (rootfs, and the
Firecracker kernel) is built once from the script in deploy/ – see the deployment guide.
Then give an agent the code-interpreter tool and ask it to compute or plot something; the answer comes back with a downloadable file.
The code interpreter needs a KVM host (Firecracker) or a gVisor-capable host. It is not available inside a fully locked, unprivileged container, where the platform reports it clearly rather than failing silently.