Manage sandboxes - BoxLite Documentation

Context manager versus method semantics: Boxlite uses a synchronous with to enter and exit (__enter__/__exit__ are synchronous), but its business methods (create / get_or_create / list_info / remove / shutdown, etc.) are all async and must be awaited. A Box uses async with to enter and exit, and its methods are likewise async — the only exception is the synchronous info().

In this section

Subtopic	Question it answers
Overview and mental model (this page)	The two objects, the state machine, and who cleans up
Box types	Which Box type to choose (`SimpleBox` / `CodeBox` / `BrowserBox` / `ComputerBox` / `InteractiveBox` / `SkillBox`)
Lifecycle	Create / start / stop / remove, plus detach and cross-process reattach
Environment and startup	Variables, `entrypoint` / `cmd`, run user, working directory, image
Compute resources	`cpus`, `memory_mib`, `disk_size_gb` and their defaults
Network access	Port publishing and network modes
Volumes	Host-to-guest bind mounts
Secrets and security	Secret injection and isolation controls
Snapshots	Export and import Box state

Two objects: a runtime and a Box

BoxLite separates “the runtime that manages a group of Boxes” from “operating on a single Box” into two objects. The two have different context manager semantics. Note: whether a context manager is synchronous or asynchronous is an independent question from whether its methods need await.

Object	Role	Context manager	Methods need `await`?
`Boxlite` (runtime)	Create / list / remove / aggregate metrics	Synchronous `with`	Business methods are `async`, must be awaited (`create` / `get_or_create` / `list_info` / `get` / `get_info` / `remove` / `shutdown` / `metrics` / `import_box`)
`Box` / `SimpleBox` / `CodeBox`, etc.	Operate a single Box (exec, copy, stop)	Asynchronous `async with`	Yes, `await` (except `info()`, see below)

Key point: the runtime enters with a synchronous with, but its methods must be awaited; a Box enters with async with, and its methods must also be awaited; only info() is always synchronous and must not be awaited.

In general, prefer the wrapper layer (SimpleBox / CodeBox, etc.). On async with entry they lazily create and automatically start the Box, and on exit they clean up according to auto_remove, so you never have to manage the runtime handle by hand. Operate the Boxlite runtime directly only when you need to manage several Boxes at once.

What a Box goes through

A box is created lazily, becomes running on first use, goes stopped when you call stop() — keeping its disk — and is removed either by auto_remove or by the runtime. Stop is not remove: a stopped box restarts with everything it had installed. The state diagram, the full transition table, and how to read box.info().state.status are on Lifecycle.

Making sure nothing is left running

Cleanup mechanism	Who triggers it	When it happens	Use case
`auto_remove=True`	SDK, automatically	On `async with` exit / when the Box stops	One-off, disposable tasks (wrapper-layer default)
`await runtime.remove(id_or_name, force=False)`	You, explicitly	Any time	Long-lived / cross-process named Boxes
`await runtime.shutdown(timeout=None)`	You, explicitly	Before process exit	Shut down every Box the runtime manages at once

Key point: removal is the runtime’s responsibility, not the Box’s — call await runtime.remove(id_or_name), not box.remove() (which does not exist). The same applies to listing: use await runtime.list_info(), not list(). These runtime methods are all async and must be awaited.

Quick Example

Both examples below are directly runnable.

A. Wrapper layer: lazy create and automatic cleanup (recommended starting point)

SimpleBox lazily creates and starts the Box on async with entry and, on exit, destroys it automatically according to auto_remove (default True), without touching the runtime handle directly.

import asyncio
from boxlite import SimpleBox

async def main():
    try:
        # auto_remove=True is the default: cleanup happens automatically on async with exit
        async with SimpleBox(image="alpine:latest") as box:
            print("box id:", box.id)

            # info() is synchronous; do not await
            info = box.info()
            print("state:", info.state.status)  # BoxStateInfo.status is a string

            # a non-zero exit code does not raise; check exit_code yourself
            result = await box.exec("echo", "hello from boxlite")
            print("exit_code:", result.exit_code)
            print("stdout:", result.stdout.strip())
    except RuntimeError as e:
        # image pull failure / no virtualization raises a standard RuntimeError
        print("startup or pull failed:", e)

asyncio.run(main())

B. Explicit runtime management: create a named Box, reuse it across calls, then remove it explicitly

When you need a long-lived Box or want to reuse one across processes, operate the Boxlite runtime directly. Note two things: Boxlite enters with a synchronous with, but its business methods are async and must be awaited; a single Box is still an async context manager.

import asyncio
from boxlite import Boxlite, BoxOptions

async def main():
    with Boxlite.default() as runtime:
        try:
            # get_or_create is idempotent: reuse an existing Box with the same name, otherwise create one (async, must await)
            box, created = await runtime.get_or_create(
                BoxOptions(image="alpine:latest", auto_remove=False),
                name="my-worker",
            )
            print("created new box?", created)

            # a single Box is an async context manager
            async with box:
                result = await box.exec("uname", "-a")
                print(result.stdout.strip())

            # listing: the runtime method is list_info() (not list()), and it is async, must await
            for bi in await runtime.list_info():
                print(bi.id, bi.name, bi.state.status)

        finally:
            # removal is the runtime's responsibility: await runtime.remove(...), not box.remove()
            try:
                await runtime.remove("my-worker", force=True)
            except Exception as e:
                print("error during removal (ignorable, may already be cleaned up):", e)

asyncio.run(main())

Node equivalent (key differences): the package is @boxlite-ai/boxlite; the runtime class is JsBoxlite (there is no bare Boxlite); listing uses listInfo(); removal uses runtime.remove(idOrName, force?); SimpleBox uses await using for automatic cleanup; info() is synchronous while getInfo() is asynchronous.

import { SimpleBox } from "@boxlite-ai/boxlite";

async function main(): Promise<void> {
  try {
    // await using: cleanup happens automatically at scope exit per autoRemove (default true)
    await using box = new SimpleBox({ image: "alpine:latest" });

    const result = await box.exec("echo", "hello from boxlite");
    console.log("exitCode:", result.exitCode);
    console.log("stdout:", result.stdout.trim());

    // info() is synchronous; getInfo() is asynchronous
    console.log("state:", box.info().state.status);
  } catch (e) {
    console.error("failed:", e);
  }
}

main();

Where to go next

This page is the mental model. Everything below has a home page that goes deeper:

If you want to	Go to
Pick a Box type for your workload	Box types
Full `BoxOptions` reference and every lifecycle method	Lifecycle → Parameters and returns
Keep a Box alive across processes, or reattach to one	Lifecycle → detach and reattach
Size CPU, memory, and disk	Compute resources
Fix a startup failure, an `AttributeError`, or a surprising `exec` result	Error handling
Confirm your platform can run a Box at all	Installation

​In this section

​Two objects: a runtime and a Box

​What a Box goes through

​Making sure nothing is left running

​Quick Example

​A. Wrapper layer: lazy create and automatic cleanup (recommended starting point)

​B. Explicit runtime management: create a named Box, reuse it across calls, then remove it explicitly

​Where to go next