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
}

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" },
  });
}