CodeInterpreter

Handles Python code interpretation and execution within a Sandbox.

Provides methods to execute code (currently only Python) in isolated interpreter contexts, manage contexts, and stream execution output via callbacks.

For other languages, use the codeRun method from the Process interface, or execute the appropriate command directly in the sandbox terminal.

Constructors

new CodeInterpreter()

new CodeInterpreter(
   clientConfig: Configuration,
   apiClient: InterpreterApi,
   getPreviewToken: () => Promise<string>,
   ensureToolboxUrl: () => Promise<void>): CodeInterpreter

Parameters:

• clientConfig Configuration
• apiClient InterpreterApi
• getPreviewToken () => Promise<string>
• ensureToolboxUrl () => Promise<void>

Returns:

• CodeInterpreter

Methods

createContext()

createContext(cwd?: string): Promise<InterpreterContext>

Create a new isolated interpreter context.

Parameters:

• cwd? string - Working directory for the context. Uses sandbox working directory if omitted.

Returns:

• Promise<InterpreterContext> - The created context.

Example:

const ctx = await sandbox.codeInterpreter.createContext()
await sandbox.codeInterpreter.runCode('x = 10', { context: ctx })
await sandbox.codeInterpreter.deleteContext(ctx.id!)

deleteContext()

deleteContext(context: InterpreterContext): Promise<void>

Delete an interpreter context and shut down its worker process.

Parameters:

• context InterpreterContext - Context to delete.

Returns:

• Promise<void>

Example:

const ctx = await sandbox.codeInterpreter.createContext()
// ... use context ...
await sandbox.codeInterpreter.deleteContext(ctx)

listContexts()

listContexts(): Promise<InterpreterContext[]>

List all user-created interpreter contexts (default context is excluded).

Returns:

• Promise<InterpreterContext[]> - List of contexts.

Example:

const contexts = await sandbox.codeInterpreter.listContexts()
for (const ctx of contexts) {
  console.log(ctx.id, ctx.language, ctx.cwd)
}

runCode()

runCode(code: string, options: RunCodeOptions): Promise<ExecutionResult>

Run Python code in the sandbox.

Parameters:

• code string - Code to run.
• options RunCodeOptions = - Execution options (context, envs, callbacks, timeout).

Returns:

• Promise<ExecutionResult> - ExecutionResult containing stdout, stderr and optional error info.

Example:

const handleStdout = (msg: OutputMessage) => process.stdout.write(`STDOUT: ${msg.output}`)
const handleStderr = (msg: OutputMessage) => process.stdout.write(`STDERR: ${msg.output}`)
const handleError = (err: ExecutionError) =>
  console.error(`ERROR: ${err.name}: ${err.value}\n${err.traceback ?? ''}`)

const code = `
import sys
import time
for i in range(5):
    print(i)
    time.sleep(1)
sys.stderr.write("Counting done!")
`

const result = await codeInterpreter.runCode(code, {
  onStdout: handleStdout,
  onStderr: handleStderr,
  onError: handleError,
  timeout: 10,
})

ExecutionError

Represents an error that occurred during code execution.

Properties:

• name string - Error type/class name (e.g., “ValueError”, “SyntaxError”).
• traceback? string - Full traceback for the error, if available.
• value string - Error value/message.

ExecutionResult

Result of code execution.

Properties:

• error? ExecutionError - Details about an execution error, if one occurred.
• stderr string - Standard error captured during execution.
• stdout string - Standard output captured during execution.

OutputMessage

Represents stdout or stderr output from code execution.

Properties:

• output string - Output content.

RunCodeOptions

Options for executing code in the interpreter.

Properties:

• context? InterpreterContext - Interpreter context to run code in.

• envs? Record<string, string> - Environment variables for this execution.

• onError()? (error: ExecutionError) => any - Callback for execution errors (e.g., runtime exceptions).

  Parameters:

  • error ExecutionError

  Returns:

  • any

• onStderr()? (message: OutputMessage) => any - Callback for stderr messages.

  Parameters:

  • message OutputMessage

  Returns:

  • any

• onStdout()? (message: OutputMessage) => any - Callback for stdout messages.

  Parameters:

  • message OutputMessage

  Returns:

  • any

• timeout? number - Timeout in seconds. Set to 0 for no timeout. Default is 10 minutes.