Box Types - BoxLite Documentation

BoxLite provides several specialized box types, each designed for specific use cases. All box types support both async context managers (async with) and explicit lifecycle management.

SimpleBox

Context manager for basic command execution with automatic cleanup.

from boxlite import SimpleBox

Constructor

SimpleBox(
    image: str = None,
    rootfs_path: str = None,
    memory_mib: int = None,
    cpus: int = None,
    runtime: Boxlite = None,
    name: str = None,
    auto_remove: bool = True,
    reuse_existing: bool = False,
    **kwargs
)

Parameter	Type	Default	Description
`image`	`str`	None	Container image to use (e.g., `"python:slim"`)
`rootfs_path`	`str`	None	Path to local OCI layout directory (alternative to `image`)
`memory_mib`	`int`	System default	Memory limit in MiB
`cpus`	`int`	System default	Number of CPU cores
`runtime`	`Boxlite`	Global default	Runtime instance
`name`	`str`	None	Optional unique name
`auto_remove`	`bool`	`True`	Remove box when stopped
`reuse_existing`	`bool`	`False`	If `True` and a box with the given `name` exists, reuse it instead of raising an error
`**kwargs`			Additional options: `env`, `volumes`, `ports`, `working_dir`

Either image or rootfs_path must be provided. If both are given, rootfs_path takes precedence.

Properties

Property	Type	Description
`id`	`str`	Box ID (raises if not started)
`created`	`bool \| None`	`True` if newly created, `False` if reused (via `reuse_existing`). `None` if not started yet.

Methods

Method	Signature	Description
`start()`	`() -> Self`	Explicitly start the box (async)
`exec()`	`(cmd, *args, env=None) -> ExecResult`	Execute command and wait (async)
`info()`	`() -> BoxInfo`	Get box metadata
`shutdown()`	`() -> None`	Shutdown and release resources
`copy_in()`	`(host_path, container_dest, *, overwrite=True, follow_symlinks=False, include_parent=True) -> None`	Copy files from host into the container (async)
`copy_out()`	`(container_src, host_dest, *, overwrite=True, follow_symlinks=False, include_parent=True) -> None`	Copy files from container to host (async)

Example

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

CodeBox

Specialized box for Python code execution with package management.

from boxlite import CodeBox

Constructor

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

Methods

Method	Signature	Description
`run()`	`(code: str, timeout: int = None) -> str`	Execute Python code (async)
`run_script()`	`(script_path: str) -> str`	Execute Python script file (async)
`install_package()`	`(package: str) -> str`	Install package with pip (async)
`install_packages()`	`(*packages: str) -> str`	Install multiple packages (async)

Example

async with CodeBox() as cb:
    # Install packages
    await cb.install_package("requests")

    # Run code
    result = await cb.run("""
import requests
print(requests.get('https://api.github.com/zen').text)
""")
    print(result)

BrowserBox

Box configured for browser automation with Chrome DevTools Protocol.

from boxlite import BrowserBox, BrowserBoxOptions

`BrowserBoxOptions`

Field	Type	Default	Description
`browser`	`str`	`"chromium"`	Browser type: `"chromium"`, `"firefox"`, `"webkit"`
`memory`	`int`	`2048`	Memory in MiB
`cpu`	`int`	`2`	Number of CPU cores

Default image

All browser types use a single Playwright image: mcr.microsoft.com/playwright:v1.58.0-jammy The Playwright Server listens on port 3000. The CDP endpoint (for Puppeteer) is on port 9222.

Properties

Property	Type	Description
`browser`	`str`	The browser type (`"chromium"`, `"firefox"`, or `"webkit"`)

Methods

Method	Signature	Description
`endpoint()`	`(timeout: int = 60) -> str`	Get CDP endpoint URL for Puppeteer (async)
`playwright_endpoint()`	`(timeout: int = 60) -> str`	Get WebSocket endpoint URL for Playwright (async)
`connect()`	`(timeout: int = 60) -> Browser`	Connect and return a Playwright Browser instance (async). Requires `playwright` installed.

Example

from boxlite import BrowserBox, BrowserBoxOptions

opts = BrowserBoxOptions(browser="chromium", memory=4096)
async with BrowserBox(opts) as browser:
    # Option 1: Use with Playwright (recommended)
    pw_browser = await browser.connect()
    page = await pw_browser.new_page()
    await page.goto("https://example.com")

    # Option 2: Get endpoints manually
    ws = await browser.playwright_endpoint()   # "ws://localhost:3000/"
    cdp = await browser.endpoint()             # "ws://localhost:3000/..."

ComputerBox

Box with full desktop environment and GUI automation capabilities. Uses the lscr.io/linuxserver/webtop:ubuntu-xfce image by default.

from boxlite import ComputerBox

Constructor

ComputerBox(
    cpu: int = 2,
    memory: int = 2048,
    gui_http_port: int = 3000,
    gui_https_port: int = 3001,
    runtime: Boxlite = None,
    **kwargs
)

Mouse Methods

Method	Signature	Description
`mouse_move()`	`(x: int, y: int) -> None`	Move cursor to coordinates (async)
`left_click()`	`() -> None`	Left click at current position (async)
`right_click()`	`() -> None`	Right click at current position (async)
`middle_click()`	`() -> None`	Middle click at current position (async)
`double_click()`	`() -> None`	Double left click (async)
`triple_click()`	`() -> None`	Triple left click (async)
`left_click_drag()`	`(start_x, start_y, end_x, end_y) -> None`	Drag from start to end (async)
`cursor_position()`	`() -> Tuple[int, int]`	Get current cursor (x, y) (async)

Keyboard Methods

Method	Signature	Description
`type()`	`(text: str) -> None`	Type text characters (async)
`key()`	`(text: str) -> None`	Press key or key combination (async)

Key Syntax Reference

The key() method uses xdotool key syntax:

Key	Syntax
Enter	`Return`
Tab	`Tab`
Escape	`Escape`
Backspace	`BackSpace`
Delete	`Delete`
Arrow keys	`Up`, `Down`, `Left`, `Right`
Function keys	`F1`, `F2`, … `F12`
Modifiers	`ctrl`, `alt`, `shift`, `super`
Combinations	`ctrl+c`, `ctrl+shift+s`, `alt+Tab`

Examples:

await computer.key("Return")        # Press Enter
await computer.key("ctrl+c")        # Copy
await computer.key("ctrl+shift+s")  # Save As
await computer.key("alt+Tab")       # Switch window
await computer.key("ctrl+a Delete") # Select all and delete

Display Methods

Method	Signature	Description
`wait_until_ready()`	`(timeout: int = 60) -> None`	Wait for desktop ready (async)
`screenshot()`	`() -> dict`	Capture screen (async)
`scroll()`	`(x, y, direction, amount=3) -> None`	Scroll at position (async)
`get_screen_size()`	`() -> Tuple[int, int]`	Get screen dimensions (async)

Screenshot Return Format

{
    "data": str,    # Base64-encoded PNG
    "width": int,   # 1024 (default)
    "height": int,  # 768 (default)
    "format": str   # "png"
}

Scroll Directions

Direction	Description
`"up"`	Scroll up
`"down"`	Scroll down
`"left"`	Scroll left
`"right"`	Scroll right

Example

async with ComputerBox() as desktop:
    await desktop.wait_until_ready()

    # Take screenshot
    screenshot = await desktop.screenshot()

    # Mouse interaction
    await desktop.mouse_move(100, 200)
    await desktop.left_click()

    # Type text
    await desktop.type("Hello, World!")
    await desktop.key("Return")

    # Get screen size
    width, height = await desktop.get_screen_size()

InteractiveBox

Box for interactive terminal sessions with PTY support.

from boxlite import InteractiveBox

Constructor

InteractiveBox(
    image: str,
    shell: str = "/bin/sh",
    tty: bool = None,
    memory_mib: int = None,
    cpus: int = None,
    runtime: Boxlite = None,
    name: str = None,
    auto_remove: bool = True,
    **kwargs
)

Parameter	Type	Default	Description
`image`	`str`	Required	Container image
`shell`	`str`	`"/bin/sh"`	Shell to run
`tty`	`bool \| None`	`None`	TTY mode (see below)
`memory_mib`	`int`	System default	Memory limit in MiB
`cpus`	`int`	System default	Number of CPU cores
`runtime`	`Boxlite`	Global default	Runtime instance
`name`	`str`	None	Optional unique name
`auto_remove`	`bool`	`True`	Remove box when stopped
`**kwargs`			Additional options: `env`, `volumes`, `ports`, `working_dir`

TTY Mode

Value	Behavior
`None`	Auto-detect from `sys.stdin.isatty()`
`True`	Force TTY mode with I/O forwarding
`False`	No I/O forwarding (programmatic control)

Methods

Method	Signature	Description
`wait()`	`() -> None`	Wait for shell to exit (async)

Example

# Interactive shell session
async with InteractiveBox(image="alpine:latest") as box:
    # You're now in an interactive shell
    # Type commands, see output in real-time
    # Type "exit" to close
    await box.wait()

BoxOptions

Configuration options shared across all box types. See BoxOptions reference for the full specification.

Field	Type	Default	Description
`image`	`str`	Required	OCI image URI (e.g., `"python:slim"`, `"alpine:latest"`)
`cpus`	`int`	`1`	Number of CPU cores (1 to host CPU count)
`memory_mib`	`int`	`2048`	Memory limit in MiB (128-65536)
`disk_size_gb`	`int \| None`	`None`	Persistent disk size in GB (None = ephemeral)
`working_dir`	`str`	`"/root"`	Working directory inside container
`env`	`List[Tuple[str, str]]`	`[]`	Environment variables as (key, value) pairs
`volumes`	`List[Tuple[str, str, bool]]`	`[]`	Volume mounts as (host_path, guest_path, read_only)
`ports`	`List[Tuple[int, int, str]]`	`[]`	Port forwarding as (host_port, guest_port, protocol)
`auto_remove`	`bool`	`True`	Auto cleanup when stopped
`detach`	`bool`	`False`	Survive parent process exit

BoxInfo

Metadata about a box, returned by box.info() and runtime.list().

Field	Type	Description
`id`	`str`	Unique box identifier (ULID)
`name`	`str \| None`	Optional user-assigned name
`status`	`str`	Current status: `"running"`, `"stopped"`, `"created"`
`created_at`	`datetime`	Creation timestamp
`pid`	`int \| None`	Process ID (if running)
`image`	`str`	OCI image used
`cpus`	`int`	Allocated CPU cores
`memory_mib`	`int`	Allocated memory in MiB

BoxStateInfo

Detailed state information for a box.

Value	Description
`Created`	Box created but not yet started
`Starting`	Box is initializing
`Running`	Box is running and ready
`Stopping`	Box is shutting down
`Stopped`	Box is stopped
`Failed`	Box encountered an error

​SimpleBox

​Constructor

​Properties

​Methods

​Example

​CodeBox

​Constructor

​Methods

​Example

​BrowserBox

​BrowserBoxOptions

​Default image

​Properties

​Methods

​Example

​ComputerBox

​Constructor

​Mouse Methods

​Keyboard Methods

​Key Syntax Reference

​Display Methods

​Screenshot Return Format

​Scroll Directions

​Example

​InteractiveBox

​Constructor

​TTY Mode

​Methods

​Example

​BoxOptions

​BoxInfo

​BoxStateInfo

​See Also

SimpleBox

Constructor

Properties

Methods

Example

CodeBox

Constructor

Methods

Example

BrowserBox

`BrowserBoxOptions`

Default image

Properties

Methods

Example

ComputerBox

Constructor

Mouse Methods

Keyboard Methods

Key Syntax Reference

Display Methods

Screenshot Return Format

Scroll Directions

Example

InteractiveBox

Constructor

TTY Mode

Methods

Example

BoxOptions

BoxInfo

BoxStateInfo

See Also