Code interpreter

An agent that answers questions about data needs to write Python, look at the result, and keep going. The usual way to give it that is a code interpreter: a python tool backed by a long-running Jupyter kernel, so a dataframe loaded in one call is still in memory for the next, just like cells in a notebook. In this guide you build one on Archil and use it to analyze a year of Ookla’s open speed test data. Archil handles the three parts that are usually awkward:

The data stays where it is. The public S3 bucket is attached as an Archil disk and mounted read-only, so the kernel reads the Parquet files directly. There’s no download step, and pandas fetches only the columns it asks for.
The kernel’s memory survives between sessions. The kernel runs in a persistent sandbox. When you pause the sandbox, the kernel is frozen with it, and the next session finds the dataframes still loaded.
Results outlive the sandbox. The agent writes charts and reports to a second Archil disk, which your app can read without going through the sandbox.

Prerequisites

Export your Archil API key, a region where sandboxes are available (aws-us-east-1, aws-us-west-2, or aws-eu-west-1), and an AI Gateway key for the model. The Ookla bucket is in us-west-2, so that region is the closest to the data.

export ARCHIL_API_KEY=key-...
export ARCHIL_REGION=aws-us-west-2
export AI_GATEWAY_API_KEY=...

Then install the dependencies. The TypeScript agent uses the AI SDK; the Python agent calls the same model through the gateway’s OpenAI-compatible API.

npm init -y && npm pkg set type=module
npm install disk ai zod tsx

pip install archil openai

Run a kernel in the sandbox

Two files run inside the sandbox. The first is a setup script that installs pandas and Jupyter’s ipykernel into a virtual environment and starts a kernel as a supervised service named kernel. The kernel’s connection file, which holds its ports and signing key, is written in advance to /root/kernel.json, so clients can find the kernel and it keeps the same address if the service restarts. MPLBACKEND=Agg makes matplotlib render to files instead of trying to display plots.

setup.sh

set -euo pipefail

python3 -m venv /opt/kernel
/opt/kernel/bin/pip install --quiet ipykernel pandas pyarrow matplotlib

/opt/kernel/bin/python -c 'from jupyter_client import write_connection_file; write_connection_file("/root/kernel.json")'
archil-sandbox services create kernel --dir /workspace --env MPLBACKEND=Agg -- \
  /opt/kernel/bin/python -m ipykernel_launcher -f /root/kernel.json

The second is a small client that runs one piece of code in that kernel, the same way a notebook runs a cell. It reads the code from the CODE environment variable, prints whatever the code prints, the value of its last expression, and any traceback, and exits. The kernel keeps running, so the next call sees the same variables. If code runs for more than 100 seconds, the client interrupts it, like pressing stop in a notebook, and the kernel’s state is kept.

run.py

import os
import re

from jupyter_client import BlockingKernelClient

client = BlockingKernelClient()
client.load_connection_file("/root/kernel.json")
client.start_channels()
client.wait_for_ready(timeout=60)

output = []


def collect(msg):
    content = msg["content"]
    if msg["msg_type"] == "stream":
        output.append(content["text"])
    elif msg["msg_type"] in ("execute_result", "display_data"):
        output.append(content["data"].get("text/plain", "") + "\n")
    elif msg["msg_type"] == "error":
        # Tracebacks are colored with ANSI escape codes; strip them for the model
        output.append(re.sub(r"\x1b\[[0-9;]*m", "", "\n".join(content["traceback"])) + "\n")


try:
    client.execute_interactive(os.environ["CODE"], timeout=100, output_hook=collect)
except TimeoutError:
    # Interrupt the running code so the kernel is ready for the next call
    client.control_channel.send(client.session.msg("interrupt_request", {}))
    output.append("Timed out after 100 seconds and interrupted.\n")

print("".join(output)[-10_000:], end="")

The kernel has no network port, so nothing outside the sandbox can reach it. Your code talks to it only through sandbox.exec.

Define the agent

The agent has one tool, python, that runs run.py with sandbox.exec. The instructions describe the dataset, so the agent doesn’t spend steps discovering it, and tell it to load data once and reuse it.

import { ToolLoopAgent, isStepCount, tool } from "ai";
import type { Sandbox } from "disk";
import { z } from "zod";

const instructions = `You are a data analyst with a Python tool backed by a persistent Jupyter kernel.
Variables and dataframes stay in memory between calls, so load data once and reuse it.
pandas, pyarrow, and matplotlib are installed. Keep printed output short.
/data (read-only) holds Ookla's open fixed-broadband speed tests for 2024, one Parquet file per quarter:
  /data/quarter=1/2024-01-01_performance_fixed_tiles.parquet, and likewise quarter=2 (2024-04-01),
  quarter=3 (2024-07-01), and quarter=4 (2024-10-01). About 6.6 million rows each.
Each row is a map tile about 600 m across. Columns: tile_x (longitude), tile_y (latitude),
avg_d_kbps, avg_u_kbps, avg_lat_ms, tests, devices. Weight averages by tests. Read only the columns you need.
Save charts with matplotlib's savefig and write reports to /workspace/output.
Keep your final answer to three sentences.`;

export async function runPython(sandbox: Sandbox, code: string) {
  const result = await sandbox.exec("/opt/kernel/bin/python /root/run.py", {
    env: { CODE: code },
    timeoutSeconds: 120,
  });
  return `${result.stdout}${result.stderr}` || "(no output)";
}

export function createAnalyst(sandbox: Sandbox) {
  const python = tool({
    description:
      "Run Python code in a persistent Jupyter kernel. Returns printed output, the value of the last expression, and errors.",
    inputSchema: z.object({ code: z.string() }),
    execute: async ({ code }) => {
      const output = await runPython(sandbox, code);
      console.log(`\n>>> ${code.trim().replaceAll("\n", "\n... ")}\n${output}`);
      return output;
    },
  });

  return new ToolLoopAgent({
    model: "anthropic/claude-sonnet-5.5",
    instructions,
    tools: { python },
    stopWhen: isStepCount(20),
  });
}

import json
import os

from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gateway.vercel.sh/v1",
    api_key=os.environ["AI_GATEWAY_API_KEY"],
)

INSTRUCTIONS = """You are a data analyst with a Python tool backed by a persistent Jupyter kernel.
Variables and dataframes stay in memory between calls, so load data once and reuse it.
pandas, pyarrow, and matplotlib are installed. Keep printed output short.
/data (read-only) holds Ookla's open fixed-broadband speed tests for 2024, one Parquet file per quarter:
  /data/quarter=1/2024-01-01_performance_fixed_tiles.parquet, and likewise quarter=2 (2024-04-01),
  quarter=3 (2024-07-01), and quarter=4 (2024-10-01). About 6.6 million rows each.
Each row is a map tile about 600 m across. Columns: tile_x (longitude), tile_y (latitude),
avg_d_kbps, avg_u_kbps, avg_lat_ms, tests, devices. Weight averages by tests. Read only the columns you need.
Save charts with matplotlib's savefig and write reports to /workspace/output.
Keep your final answer to three sentences."""

PYTHON_TOOL = {
    "type": "function",
    "function": {
        "name": "python",
        "description": "Run Python code in a persistent Jupyter kernel. "
        "Returns printed output, the value of the last expression, and errors.",
        "parameters": {
            "type": "object",
            "properties": {"code": {"type": "string"}},
            "required": ["code"],
        },
    },
}


def run_python(sandbox, code):
    result = sandbox.exec(
        "/opt/kernel/bin/python /root/run.py",
        env={"CODE": code},
        timeout_seconds=120,
    )
    return f"{result.stdout}{result.stderr}" or "(no output)"


def run_agent(sandbox, prompt, max_steps=20):
    messages = [
        {"role": "system", "content": INSTRUCTIONS},
        {"role": "user", "content": prompt},
    ]
    for _ in range(max_steps):
        reply = client.chat.completions.create(
            model="anthropic/claude-sonnet-5.5",
            messages=messages,
            tools=[PYTHON_TOOL],
        ).choices[0].message
        messages.append(reply)
        if not reply.tool_calls:
            return reply.content
        for call in reply.tool_calls:
            code = json.loads(call.function.arguments)["code"]
            output = run_python(sandbox, code)
            print("\n>>> " + code.strip().replace("\n", "\n... ") + "\n" + output)
            messages.append({"role": "tool", "tool_call_id": call.id, "content": output})
    return f"Stopped after {max_steps} steps."

Passing the code in an environment variable hands it to the kernel exactly as the model wrote it, with no shell quoting. runPython is exported so your own code can use the kernel too, which the second session does.

Run the first analysis

The first session creates two disks. ookla-speedtests is backed by the public ookla-open-data bucket, so it needs no credentials, and it’s mounted at /data. analysis-workspace is an empty disk for results, mounted at /workspace. The script then creates the sandbox, runs setup.sh, and asks the agent a question that takes several steps to answer.

A disk backed by a public bucket is read-only: Archil has no credentials to write to someone else’s bucket. Always mount it with readOnly: true (read_only=True in Python), and send everything the agent writes to a separate disk.

When the agent finishes, archil sync flushes the kernel’s writes to the disk, and the script reads the chart and the report straight from analysis-workspace with getObject. Finally, it pauses the sandbox, which stops compute and snapshots memory, including the kernel.

import * as archil from "disk";
import { readFile, writeFile } from "node:fs/promises";
import { createAnalyst } from "./agent.ts";

const { disk: speedtests } = await archil.createDisk({
  name: "ookla-speedtests",
  mounts: [
    {
      type: "s3",
      bucketName: "ookla-open-data",
      bucketPrefix: "parquet/performance/type=fixed/year=2024/",
    },
  ],
});
const { disk: workspace } = await archil.createDisk({ name: "analysis-workspace" });
const sandbox = await archil.createSandbox({
  name: "code-interpreter",
  baseImage: "python:3.13",
  vcpuCount: 4,
  memSizeMiB: 8192,
  mounts: [
    { disk: speedtests, path: "/data", readOnly: true },
    { disk: workspace, path: "/workspace" },
  ],
});

for (const file of ["setup.sh", "run.py"]) {
  await sandbox.files.uploadFile(await readFile(file), `/root/${file}`);
}
const setup = await sandbox.exec("bash /root/setup.sh", { timeoutSeconds: 600 });
if (setup.exitCode !== 0) throw new Error(setup.stderr);

const agent = createAnalyst(sandbox);
const { text } = await agent.generate({
  prompt:
    "How did fixed broadband download speeds change over 2024? Load all four quarters into one " +
    "dataframe named tiles with tile_x, tile_y, avg_d_kbps, avg_lat_ms, tests, and a quarter column. " +
    "Compare the test-weighted mean download speed per quarter worldwide and in the contiguous US " +
    "(longitude -125 to -66, latitude 24 to 50). Save a chart " +
    "to /workspace/output/download-by-quarter.png and a short Markdown report to /workspace/output/report.md.",
});
console.log(`\n${text}`);

// Flush the kernel's writes, then read the results from the disk instead of the sandbox
await sandbox.exec("archil sync /workspace");
await writeFile("download-by-quarter.png", await workspace.getObject("output/download-by-quarter.png"));
console.log(new TextDecoder().decode(await workspace.getObject("output/report.md")));

await sandbox.pause();

import archil

from agent import run_agent

speedtests = archil.create_disk(
    name="ookla-speedtests",
    mounts=[
        archil.S3Mount(
            bucket_name="ookla-open-data",
            bucket_prefix="parquet/performance/type=fixed/year=2024/",
        )
    ],
).disk
workspace = archil.create_disk(name="analysis-workspace").disk
sandbox = archil.create_sandbox(
    name="code-interpreter",
    base_image="python:3.13",
    vcpu_count=4,
    mem_size_mib=8192,
    mounts=[
        archil.SandboxMountSpec(disk=speedtests, path="/data", read_only=True),
        archil.SandboxMountSpec(disk=workspace, path="/workspace"),
    ],
)

for file in ["setup.sh", "run.py"]:
    sandbox.files.upload_file(file, f"/root/{file}")
setup = sandbox.exec("bash /root/setup.sh", timeout_seconds=600)
if setup.exit_code != 0:
    raise RuntimeError(setup.stderr)

text = run_agent(
    sandbox,
    "How did fixed broadband download speeds change over 2024? Load all four quarters into one "
    "dataframe named tiles with tile_x, tile_y, avg_d_kbps, avg_lat_ms, tests, and a quarter column. "
    "Compare the test-weighted mean download speed per quarter worldwide and in the contiguous US "
    "(longitude -125 to -66, latitude 24 to 50). Save a chart "
    "to /workspace/output/download-by-quarter.png and a short Markdown report to /workspace/output/report.md.",
)
print(f"\n{text}")

# Flush the kernel's writes, then read the results from the disk instead of the sandbox
sandbox.exec("archil sync /workspace")
with open("download-by-quarter.png", "wb") as f:
    f.write(workspace.get_object("output/download-by-quarter.png"))
print(workspace.get_object("output/report.md").decode())

sandbox.pause()

npx tsx session-1.ts

python session-1.py

The agent prints each piece of code it runs, followed by the output. Its first call loads the four quarters, about 26 million rows, into tiles, and every call after that works on the dataframe already in memory. Output from one run, trimmed:

>>> import pandas as pd, pyarrow.parquet as pq, os
... fs=[]
... for q in range(1,5):
...     p=f"/data/quarter={q}/2024-{(q-1)*3+1:02d}-01_performance_fixed_tiles.parquet"
...     d=pd.read_parquet(p,columns=['tile_x','tile_y','avg_d_kbps','avg_lat_ms','tests']);d['quarter']=q;fs.append(d)
... tiles=pd.concat(fs,ignore_index=True)
... print(tiles.shape);print(tiles.isna().sum().to_dict());print(tiles.describe().T[['min','max','mean']])
(26364521, 6)
(output trimmed)

>>> def wm(g): return (g.avg_d_kbps*g.tests).sum()/g.tests.sum()
... us=tiles[tiles.tile_x.between(-125,-66)&tiles.tile_y.between(24,50)]
(code trimmed)
         world_mbps  us_mbps  world_tests  us_tests  world_tiles  us_tiles
quarter
1             168.8    269.4    118589626  19831638      6655986   1707697
2             175.7    273.6    104427060  18476595      6492072   1726030
3             180.6    280.7    107417601  19345051      6655377   1744184
4             195.9    303.1    104326033  19550227      6561086   1733619

(two more calls trimmed: a sanity check, then the chart and report)

Fixed broadband download speeds rose every quarter of 2024. The test-weighted mean went from 168.8 Mbps in Q1 to 195.9 Mbps in Q4 worldwide (+16%). In the contiguous US it went from 269.4 to 303.1 Mbps (+12.5%), and the biggest jump in both came in Q4.
(answer and report trimmed)

The chart, downloaded from the disk to download-by-quarter.png:

Line chart of test-weighted mean fixed broadband download speed by quarter in 2024, rising from 169 to 196 Mbps worldwide and from 269 to 303 Mbps in the contiguous US

Continue in a later session

A paused sandbox keeps its memory, so the kernel and everything in it come back on resume(). Before handing the agent its next question, the script runs a line of its own in the kernel to show that tiles is still loaded. The agent then builds on it without reading the files again.

import * as archil from "disk";
import { writeFile } from "node:fs/promises";
import { createAnalyst, runPython } from "./agent.ts";

const sandbox = (await archil.listSandboxes()).find((s) => s.name === "code-interpreter")!;
await sandbox.resume();
console.log(await runPython(sandbox, 'print(f"tiles: {len(tiles):,} rows in memory")'));

const agent = createAnalyst(sandbox);
const { text } = await agent.generate({
  prompt:
    "Using the tiles dataframe that's already loaded, look at latency in Q4: what share of tests had " +
    "an average latency under 20 ms, worldwide and in the contiguous US? Save a chart to " +
    "/workspace/output/latency-q4.png and append a section to /workspace/output/report.md.",
});
console.log(`\n${text}`);

await sandbox.exec("archil sync /workspace");
const mount = sandbox.mounts.find((m) => m.path === "/workspace")!;
const workspace = await archil.getDisk(mount.diskId);
await writeFile("latency-q4.png", await workspace.getObject("output/latency-q4.png"));
console.log(new TextDecoder().decode(await workspace.getObject("output/report.md")));

await sandbox.pause();

import archil

from agent import run_agent, run_python

sandbox = next(s for s in archil.list_sandboxes() if s.name == "code-interpreter")
sandbox.resume()
print(run_python(sandbox, 'print(f"tiles: {len(tiles):,} rows in memory")'))

text = run_agent(
    sandbox,
    "Using the tiles dataframe that's already loaded, look at latency in Q4: what share of tests had "
    "an average latency under 20 ms, worldwide and in the contiguous US? Save a chart to "
    "/workspace/output/latency-q4.png and append a section to /workspace/output/report.md.",
)
print(f"\n{text}")

sandbox.exec("archil sync /workspace")
mount = next(m for m in sandbox.mounts if m.path == "/workspace")
workspace = archil.get_disk(mount.disk_id)
with open("latency-q4.png", "wb") as f:
    f.write(workspace.get_object("output/latency-q4.png"))
print(workspace.get_object("output/report.md").decode())

sandbox.pause()

The first line comes from the script’s own runPython call, before the agent does anything. After that, the agent checks what’s in the kernel and answers from tiles without reading any Parquet files. Output from one run, trimmed:

tiles: 26,364,521 rows in memory

>>> try:
...     print(tiles.shape); print(tiles.dtypes); print(tiles.head())
(output and two more inspection calls trimmed)

>>> print(us.columns.tolist(), us.quarter.value_counts().sort_index().to_dict(), us.tile_x.agg(['min','max']).tolist(), us.tile_y.agg(['min','max']).tolist())
... q4=tiles[tiles.quarter==4]
... m=(q4.tile_x.between(-125,-66))&(q4.tile_y.between(24,50))
... def share(d):
...     return d.tests[d.avg_lat_ms<20].sum()/d.tests.sum(), d.tests.sum(), len(d)
... w=share(q4); u=share(q4[m]); print(w,u)
... print((q4[m].avg_d_kbps*q4[m].tests).sum()/q4[m].tests.sum()/1000)
['tile_x', 'tile_y', 'avg_d_kbps', 'avg_lat_ms', 'tests', 'quarter'] {1: 1707697, 2: 1726030, 3: 1744184, 4: 1733619} [-124.99969999999999, -66.0031] [24.003800000000002, 49.998900000000006]
(np.float64(0.8092839397046756), np.int64(104326033), 6561086) (np.float64(0.7952972106155085), np.int64(19550227), 1733619)
303.06130137808634

(chart and report call trimmed)

In Q4 2024, 80.9% of worldwide tests (104.3M) were in tiles with average latency under 20 ms. In the contiguous US the figure was 79.5% (19.6M tests).
(answer and report trimmed)

Pausing is the right default between sessions that are minutes or hours apart. If you stop() the sandbox instead, memory is discarded: the kernel service starts again on the next boot with an empty kernel, and the agent reloads the data. The Python environment on the root filesystem and everything in /workspace are kept either way.

Clean up

A sandbox must be stopped before it can be deleted, and a paused sandbox can be stopped directly. Stop and delete the sandbox, then delete both disks. Deleting ookla-speedtests removes only the Archil disk, not the public bucket behind it.

import * as archil from "disk";

const sandbox = (await archil.listSandboxes()).find((s) => s.name === "code-interpreter")!;
await sandbox.stop();
await sandbox.delete();
for (const mount of sandbox.mounts) {
  await (await archil.getDisk(mount.diskId)).delete();
}

import archil

sandbox = next(s for s in archil.list_sandboxes() if s.name == "code-interpreter")
sandbox.stop()
sandbox.delete()
for mount in sandbox.mounts:
    archil.get_disk(mount.disk_id).delete()

Next steps

Coding agent

Give an agent a bash tool and a persistent sandbox to build and run a web app.

Persistent sandboxes

Lifecycle, services, pausing, and network access in detail.

Sharing disks

Mount one disk in several sandboxes at once with read-only and conditional mounts.

Python SDK

Full reference for sandboxes, disks, and exec options.

Agents

Analytics

Training

Apps & databases

Use Archil on other platforms

Code interpreter

Prerequisites

Run a kernel in the sandbox

Define the agent

Run the first analysis

Continue in a later session

Clean up

Next steps

Coding agent

Persistent sandboxes

Sharing disks

Python SDK

​Prerequisites

​Run a kernel in the sandbox

​Define the agent

​Run the first analysis

​Continue in a later session

​Clean up

​Next steps

Coding agent

Persistent sandboxes

Sharing disks

Python SDK

Prerequisites

Run a kernel in the sandbox

Define the agent

Run the first analysis

Continue in a later session

Clean up

Next steps