# BoxLite Documentation > BoxLite is an embeddable microVM sandbox for AI agents — stateful, sub-second boot, hardware-level isolation, no daemon required. ## BoxLite Open Source ### Getting started - [BoxLite documentation](/index.md): Run arbitrary code, commands, browsers, desktops, or entire AI agents inside hardware-isolated microVM sandboxes that start in about a secon… - [Introduction to BoxLite](/getting-started/index.md): What a Box actually is, how it differs from a container, and which of its capabilities are ready to build on today. - [Installation](/getting-started/installation.md): Install the four SDKs and the CLI, and confirm your machine meets the virtualization requirement. - [Python quickstart](/getting-started/quickstart-python.md): The shortest path to running your first code in an isolated microVM sandbox: pull an image, start a Box, run a command, and read the result… - [Node.js quickstart](/getting-started/quickstart-nodejs.md): From npm install to a command running inside an isolated microVM, in about five minutes. - [Rust quickstart](/getting-started/quickstart-rust.md): The shortest path to running your first command in an isolated microVM sandbox from Rust: streaming output and an exit code, with no virtual… - [Go quickstart](/getting-started/quickstart-go.md): The shortest path to running your first command in an isolated microVM sandbox from Go: a real exit code and stdout, with no virtual machine… - [C quickstart](/getting-started/quickstart-c.md): Start a sandbox and run a command from C, using the Simple API for the happy path and the Native API when you need streaming or fine-grained… ### Manage sandboxes - [Manage sandboxes](/manage-sandbox/index.md): A Box is a disposable microVM that boots in about a second. The Boxlite runtime creates, lists, and removes boxes; a Box handle only execute… - [Box types](/manage-sandbox/sandbox-types.md): Six one-line constructors, each returning an isolated environment tuned for one job: commands, code, a browser, a desktop, an interactive te… - [Lifecycle](/manage-sandbox/lifecycle.md): The states a box moves through — created, running, stopped, removed — and what survives each transition. - [Environment and startup](/manage-sandbox/environment.md): Shape the Linux environment inside a box — variables, run user, working directory — and control what it starts: the entrypoint, the command,… - [Compute resources](/manage-sandbox/compute-resources.md): Allocate CPU (cpus), memory (memory_mib), and disk (disk_size_gb) so a workload is neither starved nor wasteful. - [Volumes and mounts](/manage-sandbox/volumes.md): Mount a host directory into the sandbox so both sides read and write the same files. - [Network access](/manage-sandbox/network-access.md): Control the sandbox's network boundary: expose a service to the host with port forwarding, restrict outbound traffic with an egress allowlis… - [Snapshots and clones](/manage-sandbox/snapshots.md): Save a sandbox's disk state, create a fully independent copy, or pack an entire sandbox into a portable archive. - [Inject secrets and harden a box](/manage-sandbox/secrets-and-security.md): Deliver credentials to a sandbox without letting the sandbox see them, and tighten the isolation boundary so untrusted code runs safely. ### Agent tools - [Agent tools](/agent-tools/index.md): The capabilities an agent calls inside an isolated sandbox: run commands, run generated code, move files, and drive a terminal, desktop, or… - [Run Python code in a box](/agent-tools/code-execution-python.md): Run Python inside an isolated microVM with CodeBox and read stdout back — the shortest path for an agent's "write code, execute, read result… - [Run any language / command](/agent-tools/code-execution-any-language.md): Run any shell command or executable — in any language — inside a disposable microVM, and read back a structured stdout / stderr / exit code. - [Interactive shell (PTY)](/agent-tools/pseudo-terminal.md): InteractiveBox opens a real interactive terminal inside a sandbox, like docker exec -it — every keystroke reaches the shell or REPL in the b… - [Computer use (desktop)](/agent-tools/computer-use.md): Boot a full Linux desktop inside a sandbox so an agent can see the screen, move the mouse, click, type, and scroll. - [Browser automation](/agent-tools/browser-automation.md): BrowserBox runs a real Chromium, Firefox, or WebKit inside an isolated microVM and exposes a WebSocket endpoint — your Playwright script sta… - [Drive a sandbox from your agent loop](/agent-tools/drive-from-agent-loop.md): Give your agent one safe door to a real machine: the model proposes a command, your loop runs it in a microVM, and the result goes back into… - [Wrap a sandbox as an MCP tool handler](/agent-tools/mcp-server.md): Expose sandboxed command execution to any Model Context Protocol (MCP) client by wrapping BoxLite in a small MCP server of your own. - [GitHub operations](/agent-tools/github-operations.md): Let an agent clone, commit, push, and open pull requests from inside a sandbox — with your GITHUB_TOKEN never entering it. ### Agent in a box - [Agent in a box](/agent-in-box/index.md): Run a complete agent — its file access, command execution, and package installs — inside a microVM instead of on your host. - [Run Claude Code](/agent-in-box/run-claude-code.md): Install and drive the Claude Code CLI inside a microVM, where it can read, write, execute, and install freely without touching the host. - [Run Codex](/agent-in-box/run-codex.md): Install and drive the OpenAI Codex CLI inside a microVM, so the agent can execute freely while the blast radius stays inside a disposable VM… - [Run Pi](/agent-in-box/run-pi.md): Install and drive the Pi coding agent inside a microVM, where it can read, write, and execute freely while your host and your provider key s… - [Run OpenCode](/agent-in-box/run-opencode.md): Install and drive the OpenCode CLI inside a microVM, configuring its provider without writing a config file into the image. - [Run Hermes](/agent-in-box/run-hermes.md): Run the Hermes agent inside a microVM using its official image — one-shot prompts, or the messaging gateway behind a forwarded port. ### Human tools - [Human tools](/human-tools/index.md): Inspect or take over a sandbox's graphical interface from your browser — no VNC client to install. - [Share a desktop with a person in a browser](/human-tools/desktop-access.md): Share a Linux desktop running inside a sandbox with a human, through a browser and with no VNC client. - [Inspect an in-box browser from your DevTools](/human-tools/browser-access.md): Attach your own Chrome DevTools to a browser running inside a sandbox, to watch or drive it by hand. ### From demo to production - [From demo to production](/guides/index.md): Production means four things at once: every agent session gets its own disposable microVM, tool calls stay sandboxed, resources are bounded,… - [Error handling](/guides/error-handling.md): Tell command failure, timeout, parse failure, and low-level runtime errors apart — and recover from each separately. - [Running sandboxes at scale](/guides/at-scale.md): What breaks when you go from one sandbox to many, long-lived ones — and the four controls that keep it from breaking. - [Deploy in Docker or Kubernetes](/guides/deployment.md): Run a BoxLite-backed service inside Docker or on Kubernetes, where each sandbox still needs hardware virtualization. - [Manage remote sandboxes over REST](/guides/agent-service-endpoint.md): Manage a fleet of sandboxes through one REST endpoint — your code needs only a URL and an API key, not local virtualization. - [Image registry configuration](/guides/image-registry-configuration.md): Pull agent images from private or custom OCI registries — a corporate registry, ghcr.io, quay.io, or a local caching proxy — instead of only… ### Architecture - [Architecture overview](/architecture/index.md): The components a box.exec(...) call passes through, where the isolation boundary sits, and how each SDK maps onto the Rust core. - [Core components](/architecture/core-components.md): What each module is responsible for, where its state lives on disk, and which metrics it exposes. - [Security and isolation](/architecture/security-and-isolation.md): How BoxLite's isolation is layered against a guest assumed malicious from the moment it starts, and which layer each SecurityOptions field c… - [Networking](/architecture/networking.md): How a box reaches the network: the user-mode stack, the fixed subnet, DNS handling, and how a host port reaches a service inside the box. - [Storage](/architecture/storage.md): Where a box's bytes live: the digest-keyed image cache, the copy-on-write rootfs, and the two kinds of mount. - [Boot latency analysis](/architecture/boot-latency.md): Where the time goes between start() and a ready container — and why the second start is far faster than the first. ### SDK reference - [SDK reference](/reference/index.md): One Rust runtime behind five bindings — Python, Node.js, Rust, Go, and C. Their capabilities are **not fully aligned**, so this is where you… - [Python SDK reference](/reference/python.md): Complete class / method / parameter / return / exception reference. All signatures and defaults follow the latest published BoxLite source (… - [Node.js SDK reference](/reference/nodejs.md): The complete API surface of @boxlite-ai/boxlite: runtime, box handle, box types, errors, metrics, and the errors people hit most. - [Rust SDK reference](/reference/rust.md): the boxlite crate is the core implementation of BoxLite — a Tokio-based, async-first library for creating, running, and destroying hardware-… - [Go SDK reference](/reference/go.md): github.com/boxlite-ai/boxlite/sdks/go is a CGO binding over the same Rust core every other SDK uses. It has no high-level wrapper like Pytho… - [C SDK reference](/reference/c.md): BoxLite's C SDK embeds hardware-isolated microVM sandboxes into any C/C++ program, game engine, or other language's FFI layer through a stab… - [CLI reference](/reference/cli.md): the boxlite command line offers a docker-like experience for creating, running, and managing isolated lightweight microVM sandboxes from the… ### FAQ and releases - [FAQ and releases](/resources/index.md): Reference material that sits alongside the documentation: answers to recurring questions, and what changed between releases. - [FAQ](/faq.md): Short answers to what teams ask most when adopting BoxLite, with copy-runnable snippets. - [Release notes and your version](/guides/changelog.md): Where BoxLite's release history lives, and how to check which version you are running. ### Contributing - [Contributing](/development/index.md): Documentation for people working on BoxLite itself rather than building on it: how to develop the CLI, how to run the tests that boot real m… - [CLI development guide](/development/cli-development.md): Build, test, and extend the boxlite command — implemented in the boxlite-cli crate under src/cli/. - [VM integration tests, locally and in CI](/development/e2e-local.md): An operations runbook for the VM integration tests, in CI and on your own machine. - [Rust style guide](/development/rust-style.md): Coding conventions for contributors to the BoxLite core (the Rust crates). The goal is for submitted PRs to pass the CI cargo fmt / cargo cl… - [Building from source](/development/building-from-source.md): From git clone to a working local SDK, using the repository's own make targets. - [Debug macOS Seatbelt denials](/development/macos-sandbox-debugging.md): On macOS, BoxLite runs boxlite-shim under a deny-by-default sandbox-exec (Seatbelt) policy. When a rule denies an operation, the box fails t… - [Concurrent execution deadlock investigation](/development/concurrent-exec-deadlock.md): **Resolved and superseded.** A historical record of one deadlock — kept for the debugging method, not as current behaviour. - [BoxLite contributor license agreement](/legal/CLA.md) ## BoxLite Cloud ### Getting started - [What is BoxLite Cloud](/cloud/index.md): A hosted agent runtime built on BoxLite — the same SDK and the same core API, reached with a URL and an API key, with managed storage and a… - [BoxLite Cloud vs open source](/cloud/vs-opensource.md): Every difference between self-hosted BoxLite and BoxLite Cloud — entry point, auth, exec shape, storage, lifecycle, images, and billing — pl… - [Run untrusted code on BoxLite Cloud](/cloud/quickstart.md): Create an API key, point the SDK at BoxLite Cloud, and run a command inside a hardware-isolated box — no local virtualization, no daemon, th… - [API keys and authentication](/cloud/api-keys.md): Create a BoxLite Cloud API key, hand it to the SDK, CLI, or curl through the environment, and rotate it without downtime. ### Boxes - [Boxes](/cloud/boxes.md): A box on BoxLite Cloud is a microVM you address by name or id from anywhere your API key reaches — choose its image and size, and know when… - [Choose an image for a Cloud box](/cloud/box-images.md): The three images the console offers, what an image reference looks like from code, and which one to start from. - [Choose a size for a Cloud box](/cloud/box-sizes.md): The three preset sizes, the per-organization ceilings that bound any single box, and the SDK fields that set them. - [Box lifecycle on Cloud](/cloud/box-lifecycle.md): The three controls that decide when a Cloud box stops, whether it wakes again, and when it is deleted — and the idle rule that can end a job… - [Create, reuse, and remove a box from code](/cloud/box-from-code.md): The full create-start-use-remove cycle over REST, reusing a box by name, managing one from the console, and passing environment variables. ### Volumes - [Volumes](/cloud/volumes.md): Storage that outlives the box that wrote it — create a managed volume, mount it by a name you choose, and keep the data after the box is gon… - [Create a volume and mount it into a box](/cloud/mount-a-volume.md): Create a managed volume, mount it into a box at a path you choose, and write and read through the mount. - [Create, list, inspect, and delete volumes](/cloud/volume-operations.md): The four operations the volume API exposes, one script that runs all of them, and the two behaviours that catch people out: deletion is asyn… - [Keep data when the box is gone](/cloud/data-across-boxes.md): Write to a volume from one box, delete that box, and read the same data back from a new one — the reason managed volumes exist. - [Volume reference](/cloud/volume-reference.md): How a volume is addressed by name or id, the parameters and return shapes of every volume call, the mount tuple, read-only behaviour, and wh… ### Network - [Network](/cloud/network.md): Reach a service running inside a Cloud box, and control what that box is allowed to reach on the way out. - [How tunnels work](/cloud/tunnels.md): The one API behind every way of reaching into a Cloud box: how a tunnel is established, why each one carries a single connection, what it is… - [Serve HTTP from a box and get a public URL](/cloud/serve-http.md): Start an HTTP server inside a Cloud box, open a tunnel to its port, and use the public URL the tunnel gives you. - [Forward a box port to a local port](/cloud/port-forwarding.md): Publish a port inside a Cloud box on an address on your own machine, so any TCP client can reach it without knowing about BoxLite. - [Read and write raw bytes over a tunnel](/cloud/raw-streams.md): Drive a tunnel as a bidirectional byte stream when you are speaking a protocol of your own rather than HTTP. - [Control inbound and outbound access to a box](/cloud/network-policy.md): Decide who may reach a Cloud box — keep it private, share one port through a signed link, or make it public — and set what the box itself is… ### Pricing - [Pricing](/cloud/pricing.md): What BoxLite Cloud charges for: three metered resources billed by the hour, funded by a prepaid wallet or a plan's included quota. - [What a box costs](/cloud/box-costs.md): The three metered rates, the formula they combine into, what the standard sizes come to per hour and per month, and exactly which hours are… - [Stop paying for boxes you have finished with](/cloud/cost-controls.md): The two lifecycle controls that decide how long each half of a box’s bill runs, and the volume pattern that keeps data without keeping a dis… - [Wallet or a plan?](/cloud/plans.md): Two ways to fund usage on BoxLite Cloud, the usage level at which a subscription starts costing less than paying from your wallet, and the c… - [Managing billing](/cloud/billing.md): Fund your wallet, set automatic reload so boxes never stop for lack of balance, read what you have actually been charged, and know the per-b… ## Use cases ### Use cases - [Use cases](/use-cases/index.md): Complete, end-to-end guides for shipping something real with BoxLite. Each one takes a scenario from problem statement to running code, stat… - [Build a code interpreter for your LLM](/use-cases/code-interpreter.md): Let a model write Python freely and execute it inside a hardware-isolated microVM. You get the result; your host never runs the untrusted co… - [Build a data analysis agent](/use-cases/data-analysis-agent.md): Hand a CSV to a model, let it write its own pandas and matplotlib code, and run that code in an isolated microVM. You get the answer and the… - [Preview a sandboxed web app](/use-cases/sandboxed-web-app.md): Run a whole web service — generated by a model or uploaded by a user — inside an isolated microVM, and reach its HTTP endpoints from the hos… - [Expose a sandbox as an MCP tool](/use-cases/mcp-tool-server.md): Wrap an isolated sandbox in a standard MCP server so Claude Desktop, an IDE, or any agent can discover and call it over the protocol — no pe… - [Review untrusted pull requests in a sandbox](/use-cases/sandboxed-ci.md): Run an outside contributor's pull request — install its dependencies, execute its tests, and have a model review it — inside a disposable mi… - [Give an agent a computer](/use-cases/computer-use-agent.md): Run a full Linux desktop inside an isolated microVM and let a vision model drive it — look at the screen, decide, move the mouse, type. A mi… - [Scrape and analyze the web safely](/use-cases/web-scraping-agent.md): Drive a real browser inside a microVM, parse the untrusted HTML it returns in a *second* sandbox, and only then hand clean structured data t… - [Use a custom image as the agent environment](/use-cases/custom-agent-image.md): Give your agent the toolchain it needs on the first boot instead of installing it every time. Any OCI image — a public one, your team's stan… - [Give each user a persistent shell](/use-cases/interactive-dev-environment.md): Give each user, branch, or agent a live shell in its own microVM — cd, install, edit, test, with state surviving between commands. A persona… - [Run untrusted tools safely](/use-cases/untrusted-tool-execution.md): Execute a scanner, a parser, or any third-party binary against a sample you did not write — with the network off, privileges dropped, and th…