> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxlite.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Execute AI-generated code

> Create a CodeBox, run untrusted Python code safely, auto-install packages, and capture output — the #1 BoxLite use case for AI agents.

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:

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

## Prerequisites

<Tabs>
  <Tab title="Python">
    ```bash theme={null}
    pip install boxlite
    ```

    Requires Python 3.10+.
  </Tab>

  <Tab title="Node.js">
    ```bash theme={null}
    npm install @boxlite-ai/boxlite
    ```

    Requires Node.js 18+.
  </Tab>
</Tabs>

## Step 1: Run simple code

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

<Tabs>
  <Tab title="Python">
    ```python title="run_code.py" theme={null}
    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())
    ```

    ```bash theme={null}
    python run_code.py
    # Output: Sum of 0-99: 4950
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript title="run_code.js" theme={null}
    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();
    ```

    ```bash theme={null}
    node run_code.js
    # Output: Sum of 0-99: 4950
    ```
  </Tab>
</Tabs>

**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.

<Tabs>
  <Tab title="Python">
    ```python title="auto_install.py" theme={null}
    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())
    ```
  </Tab>

  <Tab title="Node.js">
    <Note>
      Auto-install is a Python SDK feature. In Node.js, use `installPackage()` before running code that needs third-party packages.
    </Note>

    ```javascript title="auto_install.js" theme={null}
    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();
    ```
  </Tab>
</Tabs>

## Step 3: Install packages explicitly

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

<Tabs>
  <Tab title="Python">
    ```python title="explicit_install.py" theme={null}
    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())
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript title="explicit_install.js" theme={null}
    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();
    ```
  </Tab>
</Tabs>

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

## Step 4: Run a script file

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

<Note>
  `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.
</Note>

<Tabs>
  <Tab title="Python">
    ```python title="analysis.py" theme={null}
    # This file lives on the HOST at ./analysis.py
    import json
    data = {"status": "success", "items": [1, 2, 3]}
    print(json.dumps(data, indent=2))
    ```

    ```python title="run_script.py" theme={null}
    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())
    ```

    ```bash theme={null}
    python run_script.py
    # Output:
    # {
    #   "status": "success",
    #   "items": [1, 2, 3]
    # }
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript title="run_script.js" theme={null}
    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();
    ```
  </Tab>
</Tabs>

## 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.

<Warning>
  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.
</Warning>

<Tabs>
  <Tab title="Python">
    ```python title="multi_run.py" theme={null}
    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())
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript title="multi_run.js" theme={null}
    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();
    ```
  </Tab>
</Tabs>

## What's next?

<CardGroup cols={2}>
  <Card title="Upload & download files" icon="arrows-rotate" href="/tutorials/file-transfer">
    Move files in and out of your sandbox to process data and retrieve results.
  </Card>

  <Card title="Connect to an LLM" icon="robot" href="/tutorials/llm-integration">
    Wire up OpenAI function calling so an LLM can execute code in your sandbox.
  </Card>

  <Card title="CodeBox API reference" icon="book" href="/reference/python/box-types#codebox">
    Full API docs for run(), run\_script(), install\_package(), and more.
  </Card>

  <Card title="AI agent integration" icon="gear" href="/guides/ai-agent-integration">
    Advanced patterns: concurrency, timeouts, security presets, and production configuration.
  </Card>
</CardGroup>