What is a code interpreter?

Agents can answer data and math questions more reliably when they can run the code they write. For example, a model can write a script that parses an uploaded comma-separated values (CSV) file, sums a column, and returns the computed result. A code interpreter runs that script and sends the output back to the model. Putting this capability into production means deciding which tool the model calls, where its code runs, and what that code can access.

Copy link to headingWhat is a code interpreter in an AI agent?

A code interpreter is a tool a large language model (LLM) can call to run generated code in an isolated environment and read the result back into its context. OpenAI, Anthropic, and Google each offer hosted code execution through their APIs. A custom interpreter follows the same pattern but sends code to an execution environment configured by the application, whether that environment runs on the team's infrastructure or on a managed service.

The interpreter combines the tool definition that the model sees with the executor that handles its calls; the sandbox is where the generated code runs. A custom execution tool can remain reusable across models that support its interface, while provider-hosted tools require provider-specific integration. The environment determines which resources the code can access, how execution is billed, and which state survives a failed or stopped run.

Copy link to headingHow does an agent use a code interpreter?

A typical code-executing agent follows a four-step cycle:

• Generate: The model writes a script for a task that benefits from computation, such as parsing a file or summing a column.

• Run: The executor sends the script to an environment that provides the configured runtime, files, and network access.

• Observe: The executor returns available output and error information to the model. Command-based executors can include standard output, standard error, and an exit code.

• Iterate: If execution fails or the result needs correction, the model uses the available error or validation feedback to revise the script.

The cycle ends when the application accepts the result, the model finishes, or a configured limit stops execution. A cap on attempts prevents repeated failures from consuming compute indefinitely; validating the output helps distinguish a successful process exit from a correct answer.

Copy link to headingHow do hosted code interpreters differ from running your own sandbox?

The main difference is in which settings the application can configure. Hosted interpreters execute code in provider-managed environments under provider-specific limits. A custom tool backed by Vercel Sandbox lets the application configure its execution environment while Vercel operates the infrastructure. The four constraints below affect that choice; for multi-turn analysis, distinguish execution time, idle expiry, and retained state:

OpenAI's Code Interpreter containers expire after 20 minutes of inactivity, so an application must save the required files externally and create a new container upon expiry. Active use refreshes the inactivity timer. Vercel Sandbox saves the filesystem when a persistent session stops and restores it on resume, preserving files and installed packages across idle gaps. Its session duration limits and snapshot retention are separate settings. Hosted tools remain suitable for analyses that fit the provider's runtime and state-retention limits.

Copy link to headingWhat does a code interpreter change for agents?

Code execution lets an agent calculate results rather than relying entirely on text-based reasoning. It affects agent behavior in four ways:

• Calculation accuracy: Program-aided language models (PAL) delegate calculations to an interpreter, reducing some arithmetic errors. On GSM8K, a grade-school math benchmark, PAL using OpenAI's code-davinci-002 outperformed chain-of-thought prompting with PaLM-540B by about 15 percentage points.

• Tool consolidation: An agent that writes and runs code can handle some tasks using general-purpose scripts rather than separate, single-purpose tools.

• Error recovery: Execution errors provide the model with concrete feedback it can use to revise a script.

• Isolation requirement: Running generated code gives model output access to system resources, so the application needs an execution boundary and limits on what the code can reach.

The benefit depends on the model and task. In the PAL study, chain-of-thought prompting outperformed program-aided prompting on the weakest text model tested, while stronger models showed the reverse. Self-debugging also has limits: a script that exits successfully may still use the wrong formula, misinterpret a column, or produce an invalid answer. Code execution can reduce calculation errors, but the application still needs to validate inputs, methods, and results.

Copy link to headingChatGPT Code Interpreter vs. API tools

ChatGPT's Code Interpreter brought this approach to file analysis in a chat interface. It launched in 2023 and was called Advanced Data Analysis later that year, allowing people to upload files and have ChatGPT write and run Python to analyze them.

Developers can add the Code Interpreter tool to an application through OpenAI's Responses API. The application configures the API tool directly, while ChatGPT exposes code execution through its own interface. Agents can use a provider's API tool or a custom tool backed by a configurable sandbox; either approach combines a model-facing tool, an execution environment, and an application loop.

Copy link to headingThe three layers of an agent code interpreter

These three layers separate the responsibilities for tool configuration, access to execution, and failure recovery. The application needs to account for each layer, even when a provider manages part of the implementation.

Copy link to headingThe tool

The tool defines the code-execution capability available to the model and how calls are handled. A provider-executed tool, such as Anthropic's code execution tool in the AI SDK, is configured through the provider integration and runs on the provider's infrastructure.

A custom tool uses an application-defined executor, for example, an AI SDK tool that submits generated code to Vercel Sandbox. The application authenticates to Sandbox using a Vercel OpenID Connect (OIDC) token or another supported authentication method.

This choice affects execution control and approval. Provider-executed tools use the provider's environment, while custom tools can target the systems and runtimes configured by the application. AI SDK toolApproval applies to tools executed by the SDK, rather than provider-executed tools. To require approval before enabling a hosted interpreter, the application must gate the request that makes that tool available. Choose the execution and approval flow before deciding where credentials and limits belong.

Copy link to headingThe environment

The environment is where generated code runs, and its isolation mechanisms determine how the workload interacts with the host. A standard Docker container uses namespaces and control groups to restrict what a process can see and consume while sharing the host kernel. gVisor provides a user-space application kernel that handles system calls and reduces direct exposure to the host kernel. Firecracker runs workloads in microVMs with separate guest kernels using the Linux Kernel-based Virtual Machine (KVM).

Choose the isolation boundary for the workload's trust level and required system access. A vulnerability reachable from a shared-kernel container can allow an escape; microVMs and sandbox runtimes such as gVisor provide additional isolation through different mechanisms. Both still depend on secure configuration and well-maintained infrastructure. The microVM vs container comparison explains the architectural tradeoffs.

Copy link to headingThe loop

The loop coordinates model calls, execution, feedback, and stopping conditions. A loop running in one application process can return each error to the model before another attempt; Anthropic's Bash execution results, for example, include stdout, stderr, and return_code. A durable loop built with Vercel Workflows can recover after interruptions by replaying recorded steps, as demonstrated by this durable code agent, which passes the previous error into the next attempt and stops after three attempts.

The application loop also controls credential handling and cleanup. An execution environment can serve a single bounded job or a longer analysis session, while the application keeps credentials out of the generated code's reach. When the application manages sandbox sessions, stop them explicitly after their work finishes instead of waiting for a timeout to reclaim compute resources.

Copy link to heading4 best practices to secure a code interpreter in production

A production code interpreter needs controls for untrusted execution, credentials, network access, and resource consumption. The following four controls address generated code alongside the broader production agent guardrails used across the application.

Copy link to headingIsolate generated code in a microVM

Executing generated code in the application's process can expose the application's files, credentials, and other resources. LangChain's PALChain illustrates this risk: CVE-2023-36258 documents arbitrary code execution through its use of Python's exec. A Next.js route that sends untrusted model output to eval, new Function, or child_process.exec likewise risks executing code with the application's privileges.

Run generated scripts in an isolated environment outside the application. A microVM provides a separate guest kernel and a hardware-backed virtualization boundary; a sandbox runtime such as gVisor takes a different approach to reducing host exposure. Restrict files, network access, and resource use within that boundary, and treat generated code as untrusted regardless of its length.

Copy link to headingKeep credentials out of the sandbox

Credentials exposed to generated code can be disclosed or misused after prompt injection. For example, an application might copy its environment variables into the execution process, allowing a malicious instruction to make generated code print a database connection string. An OWASP Gen AI Security Project incident roundup recommends the controls below for a compromised CyberGym workload hosted on Modal. It maps that incident to Unexpected Code Execution (ASI05), an Open Worldwide Application Security Project (OWASP) agentic security risk:

• Per-workload isolation: Run each workload in an isolated environment.

• Tokens outside the container: Keep platform tokens outside the execution environment.

• Egress allowlisting: Deny outbound access except to approved destinations.

• Process logging: Record process execution to investigate unexpected commands.

Keep application credentials outside the sandbox, including keys needed for the task, when authenticated requests can be brokered externally. Do not copy application secrets into environment variables or mounted files. If a workload requires a credential inside the sandbox, grant a narrowly scoped, short-lived credential deliberately and account for the possibility that generated code can read it.

Copy link to headingDeny outbound network access by default

Unrestricted outbound access can let injected instructions turn accessible data into an exfiltration payload. Filesystem isolation limits which files code can read, but it does not prevent those files from being sent over the network. Sensitive files placed or mounted inside the sandbox, such as Secure Shell (SSH) keys, remain exposed to code running in the sandbox.

Use a default-deny network policy and allow only the registries and APIs required by the task. A dependency that downloads from an additional host needs an allowlist update; another package from an already allowed registry may not. Review each allowed destination for the access it grants and whether it can receive private data.

Copy link to headingBound execution and retries

Unbounded execution and retries can consume compute without producing a usable result. A generated script may loop indefinitely or launch repeated processes, while an application may keep requesting revisions after the same failure. Execution timeouts and retry caps bound different parts of that consumption.

Apply a sandbox session timeout and an explicit limit on the number of agent-loop steps. The AI SDK's ToolLoopAgent stops after 20 steps by default, while WorkflowAgent has no default step limit; the loop-control documentation explains how to configure stopping conditions. Record a limit being reached as an incomplete or failed job, and investigate before increasing the allowance.

Copy link to headingBuild a code interpreter with Vercel Sandbox

Vercel Sandbox provides managed execution infrastructure with microVM isolation, network policies, credential brokering, and configurable session timeouts. The application still configures these controls, enforces agent retry limits, and decides which outputs count as valid.

Copy link to headingRun code in a microVM

The sandbox adapter connects the tool to Vercel Sandbox, which controls the available programs, files, and network access. The AI SDK’s Bash Tool lets a model issue shell commands and receive stdout, stderr, and an exit code. Commands can invoke Python for calculations and file analysis.

Install the dependencies using Node.js 22.13 or newer:

npm install ai @ai-sdk/tool-bash @ai-sdk/sandbox-vercel @vercel/sandbox

Configure Sandbox authentication and AI Gateway authentication in the application environment. This example gives the agent a CSV file and asks it to calculate a total:

import { ToolLoopAgent, isStepCount } from 'ai';
import { experimental_createBashTool as createBashTool } from '@ai-sdk/tool-bash';
import { createVercelSandboxSessionFromNativeSandbox } from '@ai-sdk/sandbox-vercel';
import { Sandbox } from '@vercel/sandbox';

const nativeSandbox = await Sandbox.create({
  timeout: 60_000,
  persistent: false,
  networkPolicy: 'deny-all',
});

try {
  const sandbox =
    createVercelSandboxSessionFromNativeSandbox(nativeSandbox);

  await sandbox.writeTextFile({
    path: 'sales.csv',
    content: 'product,amount\nApples,20\nPears,30\n',
  });

  const bash = await createBashTool({
    sandbox,
    timeout: 10_000,
  });

  const agent = new ToolLoopAgent({
    model: 'anthropic/claude-sonnet-5.5',
    tools: { bash },
    stopWhen: isStepCount(5),
  });

  const result = await agent.generate({
    prompt:
      'Use Python through the bash tool to read sales.csv, ' +
      'sum the amount column, and report the computed total.',
  });

  if (result.finishReason !== 'stop' || !result.text.trim()) {
    throw new Error('Agent stopped without a final answer.');
  }

  console.log(result.text);
} finally {
  await nativeSandbox.stop();
}

The computed total should be 50. The Bash Tool returns execution results to the agent so it can inspect failures and revise its commands. The example sets a 10-second command timeout, a 60-second sandbox session timeout, and a five-step agent limit. The finally block stops the sandbox.

Model requests originate from the application, so the sandbox’s outbound network restriction does not block them. Before accepting an answer, verify that the agent successfully executed the code and that the computed result is valid.

The Bash Tool currently uses an experimental export. Pin package versions when adopting the example.

Copy link to headingVercel injects credentials at the firewall

Generated code may need to authenticate to a third-party API. Giving it the API key makes that key readable inside the sandbox. Brokering requests outside the VM, through a proxy or a managed firewall feature, allows authenticated calls without exposing the credentials directly.

Vercel Sandbox supports network-policy transform rules that add or replace headers on matching outbound requests at the firewall. The injected key stays outside the VM, and a configured replacement overrides the same-named header supplied by sandbox code. Scope credentials and request rules to the required operations. The Claude Managed Agents integration uses this credential brokering with restrictive egress policies for its sandbox runner.

Copy link to headingVercel enforces egress policy outside the VM

Vercel Sandbox enforces an egress policy at a firewall outside the VM, so code inside the VM does not control it. The deny-all mode blocks outbound traffic, including Domain Name System (DNS) lookups. A custom policy allows configured domains or IP address ranges and can deny specific ranges using Classless Inter-Domain Routing (CIDR) notation. Domain rules and IP-range rules grant access independently, so broad IP allowances can undermine a domain restriction.

Policies can be updated in a running sandbox without restarting. An application can allow a registry during dependency installation, then remove that access before running the generated code. Set deny-all or a restrictive custom policy when creating the sandbox, and allow narrow, single-purpose hostnames where possible. Request-transform matchers select which requests are transformed; they do not block other requests to an allowed domain.

Copy link to headingVercel bills only active CPU time

An agent may leave its execution environment idle while the model generates the next script. In a study of Gemma and Qwen configurations across five agent benchmarks, LLM inference accounted for 71–98% of total runtime. This measures those agent workloads rather than interpreter sessions specifically, but illustrates why the treatment of idle time matters when comparing execution costs.

Active CPU billing measures the time code actively uses the central processing unit (CPU). Time waiting for input/output (I/O), including network calls to a model, does not count as active CPU use. Provisioned memory remains billable while the sandbox session is running, in 1-minute minimum increments. Stopping an idle session ends its running-memory charge; persistent snapshots are billed separately.

Copy link to headingPreserve files between sessions

Starting from a fresh environment at every turn can require repeated package installation and data loading. Preserving filesystem state avoids that setup work when the analysis continues.

Vercel sandboxes are persistent by default: when a session stops, its filesystem is snapshotted and restored when the sandbox resumes. Files and installed packages survive, while a new session boots without the previous process memory. Snapshots expire 30 days after their last use by default, and teams can shorten, extend, or remove that expiration. Snapshots are stored in the region where they are created and incur storage charges, so choose a retention period that matches the analysis session's needs.

Copy link to headingShip agents that run generated code safely on Vercel

Code interpreters let agents compute results, but they do not guarantee correct answers. A production rollout needs an isolated execution environment, credentials kept outside generated code, restricted network access, and limits on execution and retries. The application must also validate inputs and outputs, using controls appropriate to its workloads and data.

Vercel Sandbox provides execution controls that the application can configure:

• MicroVM isolation: Each sandbox session runs in a Firecracker microVM with a dedicated guest kernel, providing a boundary between workloads.

• Firewall credential injection: A transform rule adds authentication headers outside the VM, allowing generated code to call an approved service without receiving the API key directly.

• Egress enforcement outside the VM: The application configures deny-all or custom allowlist policies at the firewall rather than relying on controls inside the generated code's environment.

• Persistent state: Persistent sandboxes save the filesystem on stop and restore it on resume, retaining files and installed packages between sessions.

• Active CPU billing: Time spent waiting on the model does not count as active CPU usage, while provisioned memory remains billable during a running session.

Start a new project and connect an executeCode tool to a sandbox, or browse templates for an AI agent starting point.

Copy link to headingFrequently asked questions about code interpreters

Copy link to headingCan a code interpreter read files you upload?

Yes. Hosted interpreters support file I/O through provider-specific APIs and associated limits. In Vercel Sandbox, the application can upload data with writeFiles() before running a script and retrieve results with readFile(). This lets the code process the file without loading its full contents into the model's context; the tool can return only the outputs the model needs.

Copy link to headingDoes a code interpreter keep variables between runs?

It depends on the execution method. Separate shell-launched scripts do not automatically share in-memory variables, so they must save any state needed by later runs. A persistent Vercel sandbox retains files between sessions, but process memory is lost when a session stops and a new one boots.

Copy link to headingWhen should an agent use a code interpreter instead of a regular tool?

Use a code interpreter for calculations, file parsing, or statistics that require code written for the task. The data can remain in a file accessible to the interpreter rather than being loaded into the model's context. Use a predefined function tool for a known operation with fixed inputs and explicit permissions.

Copy link to headingDo code interpreters work with any model?

Provider-hosted interpreters are available through each provider's supported model and API combinations. A custom AI SDK tool backed by Vercel Sandbox can serve models that support the tool's interface, allowing the execution environment to remain the same when the application changes models.