Skip to content
Cloudflare Docs

Code Interpreter

Execute Python, JavaScript, and TypeScript code with support for data visualizations, tables, and rich output formats. Contexts maintain state (variables, imports, functions) across executions.

Methods

createCodeContext()

Create a persistent execution context for running code.

TypeScript
const context = await sandbox.createCodeContext(options?: CreateContextOptions): Promise<CodeContext>

Parameters:

  • options (optional):
    • language - "python" | "javascript" | "typescript" (default: "python")
    • cwd - Working directory (default: "/workspace")
    • envVars - Environment variables
    • timeout - Request timeout in milliseconds (default: 30000)

Returns: Promise<CodeContext> with id, language, cwd, createdAt, lastUsed

JavaScript
const ctx = await sandbox.createCodeContext({
  language: "python",
  envVars: { API_KEY: env.API_KEY },
});

runCode()

Execute code in a context and return the complete result.

TypeScript
const result = await sandbox.runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>

Parameters:

  • code - The code to execute (required)
  • options (optional):
    • context - Context to run in (recommended - see below)
    • language - "python" | "javascript" | "typescript" (default: "python")
    • timeout - Execution timeout in milliseconds (default: 60000)
    • onStdout, onStderr, onResult, onError - Streaming callbacks

Returns: Promise<ExecutionResult> with:

  • code - The executed code
  • logs - stdout and stderr arrays
  • results - Array of rich outputs (see Rich Output Formats)
  • error - Execution error if any
  • executionCount - Execution counter

Recommended usage - create explicit context:

JavaScript
const ctx = await sandbox.createCodeContext({ language: "python" });


await sandbox.runCode("import math; radius = 5", { context: ctx });
const result = await sandbox.runCode("math.pi * radius ** 2", { context: ctx });


console.log(result.results[0].text); // "78.53981633974483"

Error handling:

JavaScript
const result = await sandbox.runCode("x = 1 / 0", { language: "python" });


if (result.error) {
  console.error(result.error.name); // "ZeroDivisionError"
  console.error(result.error.value); // "division by zero"
  console.error(result.error.traceback); // Stack trace array
}

JavaScript and TypeScript features:

JavaScript and TypeScript code execution supports top-level await and persistent variables across executions within the same context.

JavaScript
const ctx = await sandbox.createCodeContext({ language: "javascript" });


// Execution 1: Fetch data with top-level await
await sandbox.runCode(
  `
const response = await fetch('https://api.example.com/data');
const data = await response.json();
`,
  { context: ctx },
);


// Execution 2: Use the data from previous execution
const result = await sandbox.runCode("console.log(data)", { context: ctx });
console.log(result.logs.stdout); // Data persists across executions

Variables declared with const, let, or var persist across executions, enabling multi-step workflows:

JavaScript
const ctx = await sandbox.createCodeContext({ language: "javascript" });


await sandbox.runCode("const x = 10", { context: ctx });
await sandbox.runCode("let y = 20", { context: ctx });
const result = await sandbox.runCode("x + y", { context: ctx });


console.log(result.results[0].text); // "30"

listCodeContexts()

List all active code execution contexts.

TypeScript
const contexts = await sandbox.listCodeContexts(): Promise<CodeContext[]>
JavaScript
const contexts = await sandbox.listCodeContexts();
console.log(`Found ${contexts.length} contexts`);

deleteCodeContext()

Delete a code execution context and free its resources.

TypeScript
await sandbox.deleteCodeContext(contextId: string): Promise<void>
JavaScript
const ctx = await sandbox.createCodeContext({ language: "python" });
await sandbox.runCode('print("Hello")', { context: ctx });
await sandbox.deleteCodeContext(ctx.id);

Rich Output Formats

Results include: text, html, png, jpeg, svg, latex, markdown, json, chart, data

Charts (matplotlib):

JavaScript
const result = await sandbox.runCode(
  `
import matplotlib.pyplot as plt
import numpy as np


x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x))
plt.show()
`,
  { language: "python" },
);


if (result.results[0]?.png) {
  const imageBuffer = Buffer.from(result.results[0].png, "base64");
  return new Response(imageBuffer, {
    headers: { "Content-Type": "image/png" },
  });
}

Tables (pandas):

JavaScript
const result = await sandbox.runCode(
  `
import pandas as pd
df = pd.DataFrame({'Name': ['Alice', 'Bob'], 'Age': [25, 30]})
df
`,
  { language: "python" },
);


if (result.results[0]?.html) {
  return new Response(result.results[0].html, {
    headers: { "Content-Type": "text/html" },
  });
}