What Is a Code Interpreter Sandbox API (2026 Guide)

The revenue question came back with a confident table and a small footnote: the model had added up the quarters in its head, since nothing was there to run the sum. The totals looked plausible, which made them harder to trust, because nobody could tell which cell had drifted.

A code interpreter sandbox API closes that gap. It lets an agent send a snippet of code to an isolated machine, run it, keep the variables for the next snippet, and get back text, errors and images as structured results instead of guesses. It is the narrowest form of an agent sandbox, and on Solari it is the runCode call on an AI Sandbox, from the same account as its cloud browsers and desktops. This guide covers how the interpreter keeps state, what a run returns, which isolation tier fits, what it costs and how to set one up.

How the Interpreter Keeps State Between Calls

The interpreter is what separates this API from a plain command runner, so it comes first. A command runs, exits and forgets; an interpreter behaves like a read–eval–print loop, running each snippet against the same live session. On Solari, runCode on an AI Sandbox remembers variables and imports between calls, so an agent can load a dataset in a step and query it in the next.

The sketch below loads a file in a call and sums it in the next, on a sandbox where pandas is already installed (the setup section shows how).

await sbx.runCode("import pandas as pd; df = pd.read_csv('/work/sales.csv')", { language: "python" })
const out = await sbx.runCode("print(df.groupby('quarter')['revenue'].sum())", { language: "python" })
console.log(out.results, out.error ?? "none")

await sbx.runCode("import pandas as pd; df = pd.read_csv('/work/sales.csv')", { language: "python" })
const out = await sbx.runCode("print(df.groupby('quarter')['revenue'].sum())", { language: "python" })
console.log(out.results, out.error ?? "none")

await sbx.runCode("import pandas as pd; df = pd.read_csv('/work/sales.csv')", { language: "python" })
const out = await sbx.runCode("print(df.groupby('quarter')['revenue'].sum())", { language: "python" })
console.log(out.results, out.error ?? "none")

The interpreter runs Python only. JavaScript, TypeScript, bash or R are refused with an unsupported-language error and run through commands.run instead, which returns the exit code with stdout and stderr.

State is half of the API; the other half is what comes back from each call.

What Comes Back From a Run

Every run returns a results list, and reading it well is most of the integration work. Text from the standard streams arrives as result items, and a Python exception arrives on out.error, so the agent can tell a wrong answer from a failed run and retry its own code.

Charts come back as images. Each matplotlib figure arrives as a PNG encoded in Base64, which writes binary data as ASCII text, so the chart image travels inside the response and can go to a reviewer or back to a vision model.

Solari can also return a structured view of the chart: its type, title, axis labels and series. That view is extracted inside the guest and is empty on the default base template, so code checks charts.length and falls back to the PNG.

Knowing what comes back leads to the harder question of where the code ran.

Which Isolation Tier Fits an Interpreter

An interpreter runs whatever the model wrote, and the model writes from whatever it read. A file or web page with planted instructions can steer it, the pattern OWASP calls prompt injection, so the boundary around the interpreter matters as much as the interpreter. Solari sets that boundary with the isolation field at create time.

The figure shows how each tier treats interpreter work.

Dedicated is the default and suits most agents, because the whole filesystem belongs to the sandbox and installs work normally. Hardened is the same microVM with all outbound network blocked, which fits code fed by data nobody has reviewed. Shared is cheaper and starts faster but runs only commands and runCode, and its system directories are read-only, so packages go into /work with pip install --target and a matching PYTHONPATH.

Whichever tier fits, the next lever is the bill.

What an Interpreter Sandbox Costs

Solari bills a sandbox for the CPU and memory it runs with, so a small machine for quick sums costs less than a large one for heavy analysis. On the Professional plan the rate is $0.0245 per vCPU-hour and $0.0077 per GB-hour.

The Free plan costs $0 with $3 of monthly credits, and at a zero balance new sandboxes stop launching rather than running up an overage. That makes it a safe place to wire an interpreter into an agent before sizing production machines.

Size is set at create time, which is where setup begins.

How to Set Up an Interpreter Sandbox on Solari

Setup takes an API key, the @solarisdk/sandbox package and a short sequence: create a dedicated sandbox, install the libraries and take a snapshot. A snapshot saves the running machine, and sandboxes created fromSnapshot open with the libraries already in place.

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({ apiKey: process.env.SOLARI_API_KEY! })
const base = await sandboxes.create({ template: "base", memMb: 4096 })
await base.connect()
await base.commands.run("sh", { args: ["-c", "pip install pandas matplotlib"] })
const snapId = await base.snapshot("analysis-ready")
const sbx = await sandboxes.create({ template: "base", fromSnapshot: snapId, memMb: 4096 })

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({ apiKey: process.env.SOLARI_API_KEY! })
const base = await sandboxes.create({ template: "base", memMb: 4096 })
await base.connect()
await base.commands.run("sh", { args: ["-c", "pip install pandas matplotlib"] })
const snapId = await base.snapshot("analysis-ready")
const sbx = await sandboxes.create({ template: "base", fromSnapshot: snapId, memMb: 4096 })

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({ apiKey: process.env.SOLARI_API_KEY! })
const base = await sandboxes.create({ template: "base", memMb: 4096 })
await base.connect()
await base.commands.run("sh", { args: ["-c", "pip install pandas matplotlib"] })
const snapId = await base.snapshot("analysis-ready")
const sbx = await sandboxes.create({ template: "base", fromSnapshot: snapId, memMb: 4096 })

The copy passes the same memory size as its source, because a snapshot carries its memory layout. Each copy is then reached by its id, and that id needs care: a sandbox id and its control URLs let whoever holds them run commands as root, so they stay out of logs, screenshots and tickets.

Beyond the sandbox, the same account starts cloud browsers when the agent also has to read the web.

Choosing the Right Setup

A code interpreter sandbox comes down to state, boundary and size. Use runCode for Python that builds on earlier steps and commands.run for every other language. Pick dedicated for everyday analysis, hardened for code fed by untrusted data and shared only for quick sums where cost matters most, then snapshot the installed libraries so every new sandbox starts ready.

Get Started With Solari

Start with the job from the opener: create a dedicated sandbox, load the figures and let runCode return the sum instead of an estimate. Solari sandboxes are ready in 90 ms, and over a sandbox's full lifecycle Solari is about 1.3x faster than E2B and almost 3x cheaper per sandbox hour. Create a free Solari account and the Free plan's credits cover the first sandbox.