Skip to main content
BoxRun is the management layer for BoxLite sandboxes — create, list, stop, and delete boxes through CLI, REST API, Python SDK, or web dashboard. All in a single binary, no Docker, no Kubernetes, no external dependencies.
Want to embed sandboxing as a library instead? See the BoxLite SDK quickstarts.

​
What you get

CLI

One command to create a VM and drop into a shell. Manage boxes, execute commands, transfer files — all from your terminal.
boxrun shell ubuntu

Python SDK

Async client for managing boxes programmatically. Create sandboxes, stream output, upload/download files.
pip install boxrun-sdk

REST API

Full HTTP API for integration with any language or platform. SSE streaming for real-time output, WebSocket for interactive terminals.

Web dashboard

Built-in UI at localhost:9090/ui. View all boxes, start/stop/delete them, and see execution history.

​
How it works

The boxrun serve process runs an HTTP/Unix socket server that manages the full lifecycle of micro-VMs via BoxLite. Clients — the CLI, Python SDK, or a browser — talk to this server. State is persisted in a single SQLite database; real-time output is streamed via SSE. BoxLite provides the underlying micro-VM runtime. BoxRun adds lifecycle management, persistence, and a multi-client server layer on top.

​
Box lifecycle

creating --> running <--> stopped
                |              |
                +--> error     +--> (rm)
                       |
                       +--> (rm)
  • creating — box is being provisioned by BoxLite
  • running — box is up and accepting commands
  • stopped — box is paused, disk state preserved
  • error — box creation or runtime failure
Disk state persists across stop/start cycles. Only rm (remove) destroys data.

​
What’s next

Quick Start

Install BoxRun and run your first sandbox in minutes.

CLI Reference

All commands, flags, interactive terminal, volume mounts.

Python SDK

Full SDK API, data types, error handling, AI agent patterns.

REST API

HTTP endpoints, WebSocket attach, SSE streaming.