Python SDK reference

# pip install boxlite
import asyncio

from boxlite import SimpleBox, ExecError

async def main() -> None:
    try:
        # The sandbox is created and started only when entering the async with block
        async with SimpleBox(image="alpine:latest") as box:
            result = await box.exec("echo", "hello from boxlite")
            # A non-zero exit code does not raise; check exit_code yourself
            if result.exit_code != 0:
                raise ExecError("echo", result.exit_code, result.stderr)
            print(result.stdout.strip())  # -> hello from boxlite
    except RuntimeError as e:
        # Environment issues such as image pull failure / missing virtualization raise a standard RuntimeError
        print(f"box failed to start: {e}")

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

import boxlite

print(boxlite.__version__)  # reads importlib.metadata.version("boxlite")

import asyncio
from boxlite import Boxlite, Options, ImageRegistry

async def main() -> None:
    # Note: data methods are async and must be awaited inside an event loop.
    # Only one runtime can exist per BOXLITE_HOME at a time -- pick one of the two below; do not construct both.

    # (A) Default runtime (data directory ~/.boxlite)
    runtime = Boxlite.default()

    # (B) Custom runtime + private registry (host without the http:// prefix);
    #     to use this, comment out the default() above or call runtime.close() on it first.
    # runtime = Boxlite(Options(
    #     image_registries=[
    #         ImageRegistry(
    #             host="registry.example.com",
    #             username="<YOUR_REGISTRY_USER>",     # TODO: replace
    #             password="<YOUR_REGISTRY_PASSWORD>",  # TODO: replace
    #         )
    #     ]
    # ))

    try:
        # List all sandboxes: list_info() is async and must be awaited;
        # BoxInfo.state is a BoxStateInfo whose field name is status
        for info in await runtime.list_info():
            print(info.id, info.state.status)
    except Exception as e:
        print(f"runtime error: {e}")
    finally:
        runtime.close()  # close() is synchronous

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

Options(home_dir=None, image_registries=[])

~/.boxlite/
├── images/   # OCI image cache (blobs, index.json)
├── boxes/    # Per-box data (config.json, disk image)
├── init/     # Shared guest rootfs
├── logs/     # Runtime logs
├── db/       # SQLite databases (boxes.db, images.db)
└── lock      # Filesystem lock file

import asyncio
from boxlite import Boxlite, Options

async def main() -> None:
    # Override the runtime base directory in code (takes precedence over the default ~/.boxlite).
    runtime = Boxlite(Options(home_dir="/custom/path"))
    try:
        for info in await runtime.list_info():
            print(info.id)
    finally:
        runtime.close()

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

BoxOptions(
    image=None, rootfs_path=None,
    cpus=None, memory_mib=None, disk_size_gb=None,
    working_dir=None, env=[], volumes=[], network=None, ports=[],
    auto_remove=None, detach=None,
    auto_stop=None, auto_delete=None, auto_resume=None,
    entrypoint=None, cmd=None, user=None,
    advanced=None, secrets=[],
)

from boxlite import NetworkSpec

# Enable networking, allowing only the specified hosts
network = NetworkSpec(mode="enabled", allow_net=["api.openai.com"])
# Fully disable networking (removes the guest network interface)
network_off = NetworkSpec(mode="disabled")

from boxlite import BoxOptions

opts = BoxOptions(
    image="alpine:latest",
    volumes=[
        ("/host/config", "/etc/app/config", True),   # read-only
        ("/host/data", "/mnt/data", False),           # read-write
        ("/host/cache", "/mnt/cache"),                 # 2-tuple = read-write by default
    ],
)

from boxlite import BoxOptions, SecurityOptions
from boxlite import AdvancedBoxOptions

opts = BoxOptions(
    image="alpine:latest",
    advanced=AdvancedBoxOptions(security=SecurityOptions.maximum()),
)

from boxlite import BoxOptions, Secret

opts = BoxOptions(
    image="alpine:latest",
    secrets=[
        Secret(
            name="openai",
            value="<YOUR_OPENAI_API_KEY>",   # TODO: replace
            hosts=["api.openai.com"],
            # placeholder defaults to "<BOXLITE_SECRET:openai>"
        )
    ],
)

SimpleBox(
    image=None, rootfs_path=None,
    memory_mib=None, cpus=None,
    runtime=None, name=None,
    auto_remove=True, reuse_existing=False,
    **kwargs,   # forwarded to BoxOptions: env, volumes, ports, working_dir, network, secrets...
)

import asyncio
from boxlite import SimpleBox, ExecError

async def main() -> None:
    try:
        async with SimpleBox(image="python:slim", memory_mib=1024) as box:
            result = await box.exec("python", "-c", "print('Hello!')")
            print(result.stdout)       # "Hello!\n"
            print(result.exit_code)    # 0

            # Per-command options: env takes a dict, timeout is a float in seconds
            result = await box.exec("env", env={"FOO": "bar"})
            result = await box.exec("pwd", cwd="/tmp")
            result = await box.exec("whoami", user="nobody")
            result = await box.exec("sleep", "30", timeout=2.0)
            if result.exit_code != 0:
                raise ExecError("sleep", result.exit_code, result.stderr)
    except RuntimeError as e:
        print(f"box error: {e}")

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

CodeBox(image="python:slim", memory_mib=None, cpus=None, runtime=None, **kwargs)

import asyncio
from boxlite import CodeBox

async def main() -> None:
    try:
        async with CodeBox() as cb:
            await cb.install_package("requests")
            out = await cb.run(
                "import requests; print(requests.get('https://api.github.com/zen').text)"
            )
            print(out)
    except RuntimeError as e:
        print(f"codebox error: {e}")

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

info = await box.info()     # async
print(info.state.status)    # correct path: BoxInfo.state -> BoxStateInfo.status (str)
print(info.state.running)   # bool
print(info.id, info.image, info.cpus, info.memory_mib)

# box must be a native Box; for the SimpleBox wrapper, use box._box.metrics()
metrics = await box.metrics()        # native Box; for SimpleBox use await box._box.metrics()
if metrics.memory_bytes is not None:
    print(f"Memory: {metrics.memory_bytes / (1024**2):.2f} MB")
if metrics.cpu_percent is not None:
    print(f"CPU: {metrics.cpu_percent:.1f}%")

BoxliteError (base class, inherits Exception)
├── ExecError      # fields: command, exit_code, stderr
├── TimeoutError
└── ParseError

# pip install "boxlite[sync]"
try:
    from boxlite import SyncSimpleBox  # raises ImportError when [sync] is missing
    with SyncSimpleBox(image="python:slim") as box:
        result = box.exec("python", "-c", "print('Hello!')")
        print(result.stdout)
except ImportError:
    print("Sync API unavailable; install with: pip install 'boxlite[sync]'")
except RuntimeError as e:
    print(f"box error: {e}")

import os
from boxlite import Boxlite, BoxliteRestOptions, ApiKeyCredential

try:
    runtime = Boxlite.rest(BoxliteRestOptions(
        url="<YOUR_BOXLITE_REST_URL>",  # TODO: e.g. https://api.boxlite.ai
        credential=ApiKeyCredential(os.environ["BOXLITE_API_KEY"]),  # TODO: set the environment variable
    ))
    for info in await runtime.list_info():
        print(info.id, info.state.status)
except KeyError:
    print("Please set the BOXLITE_API_KEY environment variable")
except Exception as e:
    print(f"REST error: {e}")

# Wrong
BoxOptions(volumes=[("/host", "/mnt", "ro")])
# -> TypeError: 'str' object cannot be cast as 'bool'

BoxOptions(volumes=[("/host", "/mnt", True)])   # read-only

# Wrong
import boxlite
boxlite.AdvancedBoxOptions(...)   # AttributeError

# Correct
from boxlite import AdvancedBoxOptions

from boxlite import BoxOptions, SecurityOptions
from boxlite import AdvancedBoxOptions

BoxOptions(image="alpine:latest",
           advanced=AdvancedBoxOptions(security=SecurityOptions.maximum()))

result = await box.exec("false")
if result.exit_code != 0:
    print(result.stderr)  # handle the failure yourself