Python quickstart - BoxLite Documentation

BoxLite runs any command or untrusted code inside a lightweight virtual machine, giving you process-level isolation, fast startup, and no exposure of the host system. Typical scenarios include an AI agent executing LLM-generated code, multi-tenant execution of user-submitted scripts, and running untrusted builds in CI.

Prerequisites

The boxlite Python package and a machine with hardware virtualization — see Installation.

Install:

pip install boxlite

Verify the install (prints the installed version, which should be the latest published version; you can also check with pip show boxlite):

python3 -c "import boxlite; print(boxlite.__version__)"

Quick Example (shortest path)

Save the following as hello.py and run it with python hello.py. It is a complete, standalone script: it pulls an image, starts a Box, runs a command, prints the result, and cleans up automatically.

# hello.py — your first BoxLite sandbox
import asyncio
import boxlite

async def main() -> None:
    try:
        # async with: the box is created and started on entry, and stopped and cleaned up on exit (auto_remove defaults to True)
        async with boxlite.SimpleBox(image="python:alpine") as box:
            print(f"Sandbox started: {box.id}")

            # exec does not raise on a non-zero exit code; check exit_code yourself
            result = await box.exec("python", "-c", "print('Hello from BoxLite!')")

            print("stdout:", result.stdout.strip())
            print("exit_code:", result.exit_code)
            if result.exit_code != 0:
                print("stderr:", result.stderr.strip())
    except RuntimeError as exc:
        # Image pull failure / startup failure without virtualization both raise a standard RuntimeError
        print(f"Sandbox failed to run: {exc}")

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

Expected output:

Sandbox started: <box-id>
stdout: Hello from BoxLite!
exit_code: 0

The first run downloads the python:alpine image and may take tens of seconds; later runs hit the local cache and start quickly.

What happens:

BoxLite pulls the python:alpine OCI image (first run only).
It starts a lightweight microVM from that image.
It runs python -c "..." inside the VM.
It streams stdout / stderr / exit code back to the host process.
On exit from async with, it stops and removes the Box automatically.

Next Step: Executing Untrusted Code (CodeBox)

CodeBox is a subclass of SimpleBox with a built-in Python image. It provides run() to run code directly and install_package() to install dependencies dynamically — the typical pattern for an AI agent executing LLM-generated code. Save this as codebox.py:

# codebox.py — safely execute untrusted code in a sandbox
import asyncio
import boxlite

async def main() -> None:
    code = """
import requests
response = requests.get('https://api.github.com/zen')
print(response.text)
"""
    try:
        # CodeBox's default image is python:slim; no need to pass image
        async with boxlite.CodeBox() as codebox:
            # Third-party dependencies must be installed into the sandbox first, otherwise the import inside run will fail
            await codebox.install_package("requests")

            # run returns a stdout string (not an ExecResult)
            output = await codebox.run(code)
            print(output)
    except RuntimeError as exc:
        print(f"Code execution failed: {exc}")

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

CodeBox.run(code) returns the stdout string, whereas SimpleBox.exec(...) returns an ExecResult object (with exit_code / stdout / stderr). Do not confuse the two.

Parameters and Returns

Common `SimpleBox(...)` constructor parameters

SimpleBox is lazily created: the constructor only validates arguments; the actual create/start happens when you enter async with.

Parameter	Required	Type	Default	Description
`image`	one of two	`str`	—	OCI image reference, e.g. `"python:alpine"`. Provide either this or `rootfs_path`, otherwise `ValueError`
`rootfs_path`	one of two	`str`	—	Path to a local OCI image layout directory (the on-disk form of a container image); an alternative to `image`
`cpus`	no	`int`	`None`	Number of vCPUs. Defaults to `None`, meaning the runtime’s default VM size applies
`memory_mib`	no	`int`	`None`	Memory limit in MiB. Defaults to `None`, meaning the runtime’s default VM size applies
`name`	no	`str`	auto	Box name; must be unique
`auto_remove`	no	`bool`	`True`	Whether to remove the Box on stop
`reuse_existing`	no	`bool`	`False`	Reuse an existing Box with the same name instead of erroring
`working_dir`	no	`str`	image config	Default working directory (passed through `**kwargs` to `BoxOptions`)
`env`	no	`list[tuple[str,str]]`	`[]`	Box-level environment variables (passed through `**kwargs`; note it is a list of tuples)

Note: cpus and memory_mib default to None, which means BoxLite applies the runtime’s default VM size rather than a value you set. To see the actual resources inside a Box, run nproc and read /proc/meminfo inside it. In production, set the resources explicitly. See Compute resources.

`box.exec(cmd, *args, ...)` parameters

Parameter	Required	Type	Default	Description
`cmd`	yes	`str`	—	The command to run, e.g. `"python"`
`*args`	no	`str`	—	Command arguments, e.g. `"-c", "print(1)"`
`env`	no	`dict[str, str]`	`None`	Environment variables for this execution; use a dict (not a list)
`user`	no	`str`	image default	The user to run as, in the same format as `docker exec --user`
`timeout`	no	`float`	`None` (no timeout)	Execution timeout in seconds. Note this is `timeout`; the native `Box.exec` uses `timeout_secs`
`cwd`	no	`str`	image config	Working directory for this execution

`ExecResult` (the return value of `box.exec`)

Field	Type	Description
`exit_code`	`int`	Process exit code; a non-zero value does not raise; check it yourself
`stdout`	`str`	Standard output (aggregated and decoded)
`stderr`	`str`	Standard error (aggregated and decoded)
`error_message`	`str \| None`	Non-`None` only when the process died abnormally

Listing and cleanup (runtime methods live on the runtime)

Listing and removing Boxes are methods on the runtime (Boxlite), not on a Box:

# list_runtime.py — list all boxes in the runtime
import asyncio
import boxlite

async def main() -> None:
    try:
        runtime = boxlite.Boxlite.default()

        # Use list_info() to list (not list()); returns a list of BoxInfo, newest first
        boxes = await runtime.list_info()
        if not boxes:
            print("No boxes currently.")
            return

        for info in boxes:
            name = info.name or "-"
            # State is at info.state.status (BoxInfo.state is a BoxStateInfo whose field is named status)
            print(f"{name:<16} {info.id[:12]:<14} {info.state.status:<10} {info.image}")

        # Remove by id or name (called on the runtime, not box.remove())
        # await runtime.remove(boxes[0].id, force=False)
    except RuntimeError as exc:
        print(f"Listing failed: {exc}")

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

Boxlite is entered with a synchronous with, and the Boxlite.default() factory is synchronous too. Its instance methods (list_info() / create() / get() / remove() / metrics() / shutdown()) are async — always await them, or you get RuntimeError: no running event loop. The one exception is box.info(), which is synchronous (do not await it).

Troubleshooting

`ValueError: Either 'image' or 'rootfs_path' must be provided`

The SimpleBox constructor requires either image or rootfs_path. CodeBox has a built-in default image (python:slim), so you do not pass image.

A command exited non-zero but no exception was raised

exec does not raise on a non-zero exit code; it returns ExecResult(exit_code != 0). You must check it yourself:

result = await box.exec("false")
if result.exit_code != 0:
    print(f"Command failed, exit_code={result.exit_code}, stderr={result.stderr}")

`RuntimeError`: image pull failure / startup failure without virtualization

On a network failure during the image pull or when the environment has no hardware virtualization, a standard builtins.RuntimeError is raised (not BoxliteError). Catch it with try/except RuntimeError and retry:

try:
    async with boxlite.SimpleBox(image="python:alpine") as box:
        ...
except RuntimeError as exc:
    print(f"Startup failed (possibly network or virtualization unavailable): {exc}")

Environment constraint: hardware virtualization required

macOS (Apple Silicon): uses the built-in Hypervisor.framework, needs no /dev/kvm, and works out of the box.
Linux: needs KVM (/dev/kvm present and accessible).
WSL2: needs KVM enabled and the user in the kvm group.
No virtualization: the Box fails to start (the exception is catchable; the process does not crash).
macOS Intel: not supported.

Confusing `dict` and `list` for environment variables

box.exec(env=...) takes a dict: env={"FOO": "bar"}. The SimpleBox constructor parameter env= (passed through to BoxOptions) takes a list of tuples: env=[("FOO", "bar")]. The two layers use different formats; do not confuse them.

Next Steps

Now that you have your first sandbox, you can continue with:

Reuse and lifecycle: use name + reuse_existing=True to reuse the same Box across sessions; manage Boxes with runtime.list_info() / runtime.remove(id, force=False).
Specialized boxes: BrowserBox (Playwright browser automation), ComputerBox (desktop automation), InteractiveBox (interactive PTY shell), and SkillBox (running Claude Code).
Resources and isolation: use BoxOptions to configure cpus/memory, volumes, ports, an egress allowlist, and secrets, plus security presets via advanced=AdvancedBoxOptions(security=...).
Other languages: see the Node.js quickstart, the Rust quickstart, and the Go quickstart.

​Prerequisites

​Quick Example (shortest path)

​Next Step: Executing Untrusted Code (CodeBox)

​Parameters and Returns

​Common SimpleBox(...) constructor parameters

​box.exec(cmd, *args, ...) parameters

​ExecResult (the return value of box.exec)

​Listing and cleanup (runtime methods live on the runtime)

​Troubleshooting

​ValueError: Either 'image' or 'rootfs_path' must be provided

​A command exited non-zero but no exception was raised

​RuntimeError: image pull failure / startup failure without virtualization

​Environment constraint: hardware virtualization required

​Confusing dict and list for environment variables

​Next Steps