# BoxLite

> Persistent compute for AI agents. Hardware-isolated microVMs that keep their
> filesystem, stop when idle, and wake when an agent comes back — run on
> BoxLite Cloud, or on your own machines.

## Two ways to run the same runtime

BoxLite ships as one runtime with two deployment paths. The SDK surface and the
core API are the same in both; only where the boxes run differs.

- **BoxLite Cloud** (https://boxlite.ai) — a hosted agent runtime. Reached over a
  REST URL with an API key. Managed storage, managed box lifecycle, nothing to
  operate.
- **BoxLite Open Source** (https://boxlite.ai/oss) — Apache 2.0, runs in-process
  on your laptop, your servers, or air-gapped. No account, no daemon, no root,
  no data leaving the machine.

## What a box is

Each box is a real virtual machine with its own Linux kernel, isolated in
hardware via KVM on Linux, Hypervisor.framework on macOS, or WSL2 on Windows —
not a shared-kernel container. Boxes are stateful: packages, files and
environment survive stop and restart, and full state can be snapshotted and
forked copy-on-write.

Images differ by where the box runs, and this is the first thing an agent gets
wrong. The open-source runtime takes any OCI image unmodified. **Cloud takes
three aliases and rejects everything else** with
`Unsupported image '…'`: `base`, `python`, `node`. A Docker
reference such as `python:slim` or `ubuntu` fails at create time.

## BoxLite Cloud

Connect an existing SDK to the hosted runtime with two environment variables:

```bash
export BOXLITE_API_KEY="blk_live_..."   # created in the console, shown once
export BOXLITE_REST_URL="https://app.boxlite.ai/api"
```

```python
from boxlite import Boxlite, BoxliteRestOptions
from boxlite import ApiKeyCredential, BoxOptions
import os

rt = Boxlite.rest(BoxliteRestOptions(
    url=os.environ["BOXLITE_REST_URL"],
    credential=ApiKeyCredential(os.environ["BOXLITE_API_KEY"]),
))

box = await rt.create(BoxOptions(image="python"))
await box.start()

result = await box.exec("python", args=["-c", "print(2 + 2)"])
print(result.stdout)
```

Cloud-specific behaviour:

- **Two shapes, one API**: a disposable box for untrusted code, or a persistent
  agent home that keeps working between sessions.
- **Managed volumes**: storage that outlives the box it was created in.
  Created and attached through the REST volumes endpoints — the SDK's
  `volumes=[(host, guest)]` argument is a host bind-mount, and on Cloud it is
  accepted and then silently dropped. Use `copy_in`/`copy_out` for files.
- **Idle-stop and wake-on-access**: boxes stop when idle and wake when something
  touches them; the lifecycle is not yours to babysit.

### Pricing

New accounts start with $100 in credits. Boxes are metered per hour on three
dimensions, so a box costs what you sized it:

| Dimension | Rate |
| --- | --- |
| CPU | $0.0504 per vCPU-hour |
| Memory | $0.0144 per GiB-hour |
| Disk | $0.00018 per GiB-hour |

The smallest box — 1 vCPU, 1 GiB memory, 10 GiB disk — is $0.0666/hr. The
console's New box dialog quotes the total for a given size before you create it.

Each plan carries an included usage quota that resets per billing cycle, and a
prepaid wallet funds anything beyond it. An account can also run wallet-only
with no plan at all.

| Plan | Price | Included quota | Concurrency |
| --- | --- | --- | --- |
| Starter | $19/mo | $30 | 20 boxes |
| Pro | $149/mo | $250 | 100 boxes |
| Max | $499/mo | $900 | 1,000 boxes |
| Enterprise | Custom | Committed capacity | Custom limits |

Per-box ceilings apply on every plan: 4 vCPU, 32 GiB memory, 120 GiB storage.

## BoxLite Open Source

```bash
pip install boxlite
```

```python
import asyncio
import boxlite

async def main():
    async with boxlite.SimpleBox(image="python:slim") as box:
        result = await box.exec("python", "-c", "print(2 + 2)")
        print(result.stdout)  # "4"

asyncio.run(main())
```

Rust core with native bindings; SDKs for Python, Node.js, Go and C, plus the
Rust crate itself and a CLI. No daemon and no control plane required.

## Use cases

- Build a code interpreter for an LLM — generated Python executes in a
  disposable microVM.
- Build a data analysis agent — CSV in, model-written pandas analysis out.
- Review untrusted pull requests — run the suite on code nobody has read.
- Run a coding agent such as Claude Code confined to a microVM.
- Scrape and analyse the web safely — a browser box plus a parsing box.
- Give each user a persistent shell — stateful, one per user, branch or agent.
- Expose a sandbox as an MCP tool.

## Developer resources

Each of these is named so it can be found by name, and lives at a stable URL.

| Resource | URL | What it is |
| --- | --- | --- |
| BoxLite agent guide | https://boxlite.ai/agent.md | Complete guide for coding agents using BoxLite Cloud. Every code sample is executed against the live API before release. |
| BoxLite documentation | https://docs.boxlite.ai | Human-facing docs: getting started, reference, tutorials. |
| BoxLite Cloud quickstart | https://docs.boxlite.ai/cloud/quickstart | API key, environment variables, first box. |
| BoxLite REST API | https://app.boxlite.ai/api | The Cloud control plane. Bearer-token auth with an API key. Interactive Swagger UI is served at the API root. |
| BoxLite API keys | https://docs.boxlite.ai/cloud/api-keys | How to create and scope a key. |
| BoxLite Python SDK | https://pypi.org/project/boxlite/ | `pip install boxlite` |
| BoxLite Node.js SDK | https://www.npmjs.com/package/@boxlite-ai/boxlite | `npm install @boxlite-ai/boxlite` |
| BoxLite CLI | https://sh.boxlite.ai | `curl -fsSL https://sh.boxlite.ai | sh` |
| BoxLite source | https://github.com/boxlite-ai/boxlite | Apache 2.0 runtime, Rust core with native bindings. |
| BoxLite MCP | https://docs.boxlite.ai/use-cases | Exposing a box as an MCP tool. |

## Reading this site as markdown

Every page has a markdown twin at a stable URL — append `.md`, with the home
page at `/index.md`. Prefer these: they are plain URLs, so they can be linked,
cached and quoted, and they need no special request header.

| Page | Markdown |
| --- | --- |
| https://boxlite.ai/ | https://boxlite.ai/index.md |
| https://boxlite.ai/oss | https://boxlite.ai/oss.md |
| https://boxlite.ai/about | https://boxlite.ai/about.md |
| https://boxlite.ai/contact | https://boxlite.ai/contact.md |

The same pages also answer to `Accept: text/markdown` at their normal URL, and
every HTML response advertises its twin in a `Link: rel="alternate"` header and
a `<link rel="alternate" type="text/markdown">` tag.

```bash
curl https://boxlite.ai/oss.md                          # plain URL
curl -H "Accept: text/markdown" https://boxlite.ai/oss   # same content
```

Unknown paths return HTTP 404 with a markdown body listing every real page, so
a guessed URL is recoverable without a second blind request. An `Accept` header
that rules out both HTML and markdown returns 406 with a JSON body naming what
is supported.

## Links

- Cloud: https://boxlite.ai
- Open source: https://boxlite.ai/oss
- Pricing: https://boxlite.ai/#pricing
- About: https://boxlite.ai/about
- Contact: https://boxlite.ai/contact
- Agent guide: https://boxlite.ai/agent.md
- Sitemap: https://boxlite.ai/sitemap.xml
- Documentation: https://docs.boxlite.ai
- Cloud docs: https://docs.boxlite.ai/cloud
- Cloud quickstart: https://docs.boxlite.ai/cloud/quickstart
- Billing: https://docs.boxlite.ai/cloud/billing
- Use cases: https://docs.boxlite.ai/use-cases
- Console: https://app.boxlite.ai
- GitHub: https://github.com/boxlite-ai/boxlite
- Discord: https://go.boxlite.ai/discord
- Support: support@boxlite.ai