Skip to main content
The core of isol8 is the execute() method, which runs code in an isolated container and returns structured results.

​
ExecutionRequest

const result = await isol8.execute({
  code: 'print("hello")',           // Source code (required)
  runtime: "python",                // Runtime (required)
  timeoutMs: 5000,                  // Override default timeout
  env: { MY_VAR: "value" },        // Additional env vars
  stdin: "input data",             // Data piped to process stdin
  files: {                          // Files injected before execution
    "/sandbox/data.csv": "a,b\n1,2",
    "/sandbox/config.json": Buffer.from('{"key":"val"}'),
  },
  outputPaths: ["/sandbox/out.txt"], // Files to retrieve after execution
  installPackages: ["numpy"],        // Packages to install before execution
});

​
Fields

​
code
string
required
The source code to execute.
​
runtime
'python' | 'node' | 'bun' | 'deno' | 'bash'
required
The runtime to use for execution.
​
timeoutMs
number
Execution timeout in milliseconds. Overrides the engine’s default. The process is killed when the timeout is reached.
​
env
Record<string, string>
Additional environment variables to inject into the container.
​
stdin
string
Data piped to the process via stdin. Useful for programs that read from sys.stdin (Python), process.stdin (Node), etc.
​
files
Record<string, string | Buffer>
Files to inject into the container before execution. Keys are absolute paths, values are file contents.
​
outputPaths
string[]
File paths to retrieve from the container after execution. The files are returned base64-encoded in ExecutionResult.files.
​
installPackages
string[]
Packages to install before execution using the runtime’s package manager. The container’s root filesystem is temporarily made writable and network is enabled for installation.

​
ExecutionResult

interface ExecutionResult {
  stdout: string;           // Captured stdout (may be truncated)
  stderr: string;           // Captured stderr
  exitCode: number;         // 0 = success
  durationMs: number;       // Wall-clock execution time
  truncated: boolean;       // Whether output was truncated
  executionId: string;      // UUID for this execution
  runtime: Runtime;         // Runtime that was used
  timestamp: string;        // ISO 8601 timestamp
  containerId?: string;     // Docker container ID
  files?: Record<string, string>; // Retrieved files (base64-encoded)
}

​
Handling Results

const result = await isol8.execute({
  code: 'print("hello")',
  runtime: "python",
});

if (result.exitCode !== 0) {
  console.error("Execution failed:", result.stderr);
} else {
  console.log("Output:", result.stdout);
}

if (result.truncated) {
  console.warn("Output was truncated to", result.stdout.length, "bytes");
}

console.log("Took", result.durationMs, "ms");
console.log("Execution ID:", result.executionId);

​
Retrieving Output Files

const result = await isol8.execute({
  code: `
import json
data = {"result": [1, 2, 3]}
with open("/sandbox/output.json", "w") as f:
    json.dump(data, f)
  `,
  runtime: "python",
  outputPaths: ["/sandbox/output.json"],
});

if (result.files) {
  const content = Buffer.from(result.files["/sandbox/output.json"], "base64");
  console.log(JSON.parse(content.toString()));
}

​
Injecting Input Files

const csvData = "name,age\nAlice,30\nBob,25";

const result = await isol8.execute({
  code: `
import csv, sys
with open("/sandbox/data.csv") as f:
    reader = csv.DictReader(f)
    for row in reader:
        print(f"{row['name']} is {row['age']}")
  `,
  runtime: "python",
  files: {
    "/sandbox/data.csv": csvData,
  },
});

console.log(result.stdout);
// Alice is 30
// Bob is 25

​
Runtime Package Installation

const result = await isol8.execute({
  code: `
import numpy as np
arr = np.array([1, 2, 3, 4, 5])
print(f"Mean: {arr.mean()}, Std: {arr.std():.2f}")
  `,
  runtime: "python",
  installPackages: ["numpy"],
});
For faster execution, bake frequently-used packages into custom images with isol8 setup --python numpy,pandas instead of installing them on every run.