# BoxLite

> Source: `docs/deploy/boxlite.mdx`
> Canonical URL: https://sandboxagent.dev/docs/deploy/boxlite
> Description: Run Sandbox Agent inside a BoxLite micro-VM.

---
BoxLite is a local-first micro-VM sandbox — no cloud account needed.
See [BoxLite docs](https://docs.boxlite.ai) for platform requirements (KVM on Linux, Apple Silicon on macOS).

## Prerequisites

- `@boxlite-ai/boxlite` installed (requires KVM or Apple Hypervisor)
- Docker (to build the base image)
- `ANTHROPIC_API_KEY` or `OPENAI_API_KEY`

## Base image

Build a Docker image with Sandbox Agent pre-installed, then export it as an OCI layout
that BoxLite can load directly (BoxLite has its own image store separate from Docker):

```dockerfile
FROM node:22-bookworm-slim
RUN apt-get update && apt-get install -y curl ca-certificates && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL https://releases.rivet.dev/sandbox-agent/0.4.x/install.sh | sh
RUN sandbox-agent install-agent claude
RUN sandbox-agent install-agent codex
```

```bash
docker build -t sandbox-agent-boxlite .
mkdir -p oci-image
docker save sandbox-agent-boxlite | tar -xf - -C oci-image
```

## TypeScript example

```typescript
import { SimpleBox } from "@boxlite-ai/boxlite";
import { SandboxAgent } from "sandbox-agent";

const env: Record<string, string> = {};
if (process.env.ANTHROPIC_API_KEY) env.ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
if (process.env.OPENAI_API_KEY) env.OPENAI_API_KEY = process.env.OPENAI_API_KEY;

const box = new SimpleBox({
  rootfsPath: "./oci-image",
  env,
  ports: [{ hostPort: 3000, guestPort: 3000 }],
  diskSizeGb: 4,
});

await box.exec("sh", "-c",
  "nohup sandbox-agent server --no-token --host 0.0.0.0 --port 3000 >/tmp/sandbox-agent.log 2>&1 &"
);

const baseUrl = "http://localhost:3000";
const sdk = await SandboxAgent.connect({ baseUrl });

const session = await sdk.createSession({ agent: "claude" });
const off = session.onEvent((event) => {
  console.log(event.sender, event.payload);
});

await session.prompt([{ type: "text", text: "Summarize this repository" }]);
off();

await box.stop();
```
