Execute AI-generated code

CodeBox is BoxLite’s purpose-built sandbox for running untrusted Python code. It auto-installs missing packages, captures output, and keeps your host system completely safe. This tutorial walks through the core workflow.

What you’ll build

A script that:

Creates an isolated CodeBox
Runs untrusted Python code inside it
Auto-installs required packages
Returns the output to your application

Prerequisites

Python
Node.js

pip install boxlite

Requires Python 3.10+.

npm install @boxlite-ai/boxlite

Requires Node.js 18+.

Step 1: Run simple code

Start with a basic example — execute a Python snippet and print the result.

Python
Node.js

run_code.py

import asyncio
import boxlite


async def main():
    async with boxlite.CodeBox() as codebox:
        result = await codebox.run("""
x = sum(range(100))
print(f"Sum of 0-99: {x}")
""")
        print(result)


if __name__ == "__main__":
    asyncio.run(main())

python run_code.py
# Output: Sum of 0-99: 4950

run_code.js

import { CodeBox } from '@boxlite-ai/boxlite';

async function main() {
  const codebox = new CodeBox({ memoryMib: 512 });
  try {
    const result = await codebox.run(`
x = sum(range(100))
print(f"Sum of 0-99: {x}")
    `);
    console.log(result);
  } finally {
    await codebox.stop();
  }
}

main();

node run_code.js
# Output: Sum of 0-99: 4950

What’s happening:

CodeBox creates a lightweight VM with a Python runtime pre-installed
Your code runs inside the VM — completely isolated from the host
Output is captured and returned as a string
The VM is cleaned up automatically when the context exits

Step 2: Auto-install packages

CodeBox detects missing imports and installs them automatically. No manual pip install needed.

Python
Node.js

auto_install.py

import asyncio
import boxlite


async def main():
    async with boxlite.CodeBox() as codebox:
        # requests is not pre-installed — CodeBox installs it for you
        result = await codebox.run("""
import requests
response = requests.get('https://api.github.com/zen')
print(response.text)
""")
        print(result)


if __name__ == "__main__":
    asyncio.run(main())

Auto-install is a Python SDK feature. In Node.js, use installPackage() before running code that needs third-party packages.

auto_install.js

import { CodeBox } from '@boxlite-ai/boxlite';

async function main() {
  const codebox = new CodeBox();
  try {
    // Node.js SDK requires explicit package installation
    await codebox.installPackage('requests');

    const result = await codebox.run(`
import requests
response = requests.get('https://api.github.com/zen')
print(response.text)
    `);
    console.log(result);
  } finally {
    await codebox.stop();
  }
}

main();

Step 3: Install packages explicitly

When you need specific versions or want to pre-install packages before running code, use install_package().

Python
Node.js

explicit_install.py

import asyncio
import boxlite


async def main():
    async with boxlite.CodeBox() as codebox:
        # Pre-install specific packages
        await codebox.install_package("pandas")
        await codebox.install_package("matplotlib")

        result = await codebox.run("""
import pandas as pd
import matplotlib
print(f"pandas {pd.__version__}, matplotlib {matplotlib.__version__}")

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
print(df.describe())
""")
        print(result)


if __name__ == "__main__":
    asyncio.run(main())

explicit_install.js

import { CodeBox } from '@boxlite-ai/boxlite';

async function main() {
  const codebox = new CodeBox();
  try {
    await codebox.installPackage('pandas');
    await codebox.installPackage('matplotlib');

    const result = await codebox.run(`
import pandas as pd
import matplotlib
print(f"pandas {pd.__version__}, matplotlib {matplotlib.__version__}")

df = pd.DataFrame({"x": [1, 2, 3], "y": [4, 5, 6]})
print(df.describe())
    `);
    console.log(result);
  } finally {
    await codebox.stop();
  }
}

main();

For data-heavy workloads (pandas, numpy, matplotlib), increase memory to 4096 MiB or more. The default 2048 MiB is enough for most code execution.

Step 4: Run a script file

Use run_script() to execute a Python script from your host filesystem inside the box.

run_script() reads the script from your host machine and executes it inside the box. It does not look for files already inside the guest.

Python
Node.js

analysis.py

# This file lives on the HOST at ./analysis.py
import json
data = {"status": "success", "items": [1, 2, 3]}
print(json.dumps(data, indent=2))

run_script.py

import asyncio
import boxlite


async def main():
    async with boxlite.CodeBox() as codebox:
        # run_script() reads ./analysis.py from the HOST filesystem
        # and executes it inside the box
        result = await codebox.run_script("./analysis.py")
        print(result)


if __name__ == "__main__":
    asyncio.run(main())

python run_script.py
# Output:
# {
#   "status": "success",
#   "items": [1, 2, 3]
# }

run_script.js

import { CodeBox } from '@boxlite-ai/boxlite';

async function main() {
  const codebox = new CodeBox({ memoryMib: 512 });
  try {
    // runScript() reads ./analysis.py from the HOST filesystem
    // and executes it inside the box
    const result = await codebox.runScript('./analysis.py');
    console.log(result);
  } finally {
    await codebox.stop();
  }
}

main();

Step 5: Run multiple snippets in the same box

A single CodeBox can run many snippets sequentially. Filesystem state persists between calls — installed packages and written files remain available. However, in-memory state (variables, functions) does not persist.

Each run() call spawns a separate Python process. Variables and functions defined in one run() call are not available in the next. Use the filesystem to share data between calls.

Python
Node.js

multi_run.py

import asyncio
import boxlite


async def main():
    async with boxlite.CodeBox() as codebox:
        # First run: compute results and write to a file
        await codebox.run("""
import json

data = {"a": 1, "b": 2, "c": 3}
output = {k: v * 2 for k, v in data.items()}

with open('/tmp/results.json', 'w') as f:
    json.dump(output, f)
print("Saved results to /tmp/results.json")
""")

        # Second run: read the file from the previous run
        result = await codebox.run("""
import json

with open('/tmp/results.json') as f:
    data = json.load(f)
print(json.dumps(data))
""")
        print(result)  # {"a": 2, "b": 4, "c": 6}


if __name__ == "__main__":
    asyncio.run(main())

multi_run.js

import { CodeBox } from '@boxlite-ai/boxlite';

async function main() {
  const codebox = new CodeBox({ memoryMib: 512 });
  try {
    // First run: compute results and write to a file
    await codebox.run(`
import json

data = {"a": 1, "b": 2, "c": 3}
output = {k: v * 2 for k, v in data.items()}

with open('/tmp/results.json', 'w') as f:
    json.dump(output, f)
print("Saved results to /tmp/results.json")
    `);

    // Second run: read the file from the previous run
    const result = await codebox.run(`
import json

with open('/tmp/results.json') as f:
    data = json.load(f)
print(json.dumps(data))
    `);
    console.log(result);  // {"a": 2, "b": 4, "c": 6}
  } finally {
    await codebox.stop();
  }
}

main();

What’s next?

Upload & download files

Move files in and out of your sandbox to process data and retrieve results.

Connect to an LLM

Wire up OpenAI function calling so an LLM can execute code in your sandbox.

CodeBox API reference

Full API docs for run(), run_script(), install_package(), and more.

AI agent integration

Advanced patterns: concurrency, timeouts, security presets, and production configuration.

Getting Started

Tutorials

Guides

SDK Reference

Architecture

Resources

Development

What you’ll build

Prerequisites

Step 1: Run simple code

Step 2: Auto-install packages

Step 3: Install packages explicitly

Step 4: Run a script file

Step 5: Run multiple snippets in the same box

What’s next?

Upload & download files

Connect to an LLM

CodeBox API reference

AI agent integration

​What you’ll build

​Prerequisites

​Step 1: Run simple code

​Step 2: Auto-install packages

​Step 3: Install packages explicitly

​Step 4: Run a script file

​Step 5: Run multiple snippets in the same box

​What’s next?

Upload & download files

Connect to an LLM

CodeBox API reference

AI agent integration

What you’ll build

Prerequisites

Step 1: Run simple code

Step 2: Auto-install packages

Step 3: Install packages explicitly

Step 4: Run a script file

Step 5: Run multiple snippets in the same box

What’s next?