191 lines
6.5 KiB
Markdown
191 lines
6.5 KiB
Markdown
# BoxLite Setup
|
|
|
|
Using planning-with-files inside [BoxLite](https://boxlite.ai) micro-VM sandboxes via [ClaudeBox](https://github.com/boxlite-ai/claudebox).
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
BoxLite is a micro-VM sandbox runtime — hardware-isolated, stateful, embeddable as a library with no daemon and no root required. The analogy their team uses is "SQLite for sandboxing": you import it directly into your application and each box gets its own kernel, not just namespaces or containers.
|
|
|
|
[ClaudeBox](https://github.com/boxlite-ai/claudebox) is BoxLite's official Claude Code integration layer. It runs the Claude Code CLI inside a BoxLite micro-VM with persistent workspaces, optional skills, security policies, and resource limits. planning-with-files loads into ClaudeBox as a Skill object — the skill's SKILL.md and scripts get injected into the VM filesystem at startup, exactly where Claude Code expects to find them.
|
|
|
|
**Why use this combination:**
|
|
- Run untrusted AI-generated code in hardware isolation without touching your host filesystem
|
|
- planning files (`task_plan.md`, `findings.md`, `progress.md`) persist across sessions via ClaudeBox's stateful workspaces at `~/.claudebox/sessions/`
|
|
- Snapshot before a risky phase, roll back if needed
|
|
- All hooks (PreToolUse, PostToolUse, Stop) work because Claude Code runs natively inside the VM
|
|
|
|
---
|
|
|
|
## Prerequisites
|
|
|
|
- Python 3.10+
|
|
- BoxLite runtime (installed automatically as a ClaudeBox dependency)
|
|
- Docker — used to pull and manage OCI images (the sandbox itself runs as a micro-VM, not a Docker container)
|
|
- `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` set
|
|
|
|
---
|
|
|
|
## Installation
|
|
|
|
### Install ClaudeBox
|
|
|
|
```bash
|
|
pip install claudebox
|
|
```
|
|
|
|
### Set your API credentials
|
|
|
|
```bash
|
|
export CLAUDE_CODE_OAUTH_TOKEN=sk-ant-oat01-...
|
|
# or
|
|
export ANTHROPIC_API_KEY=sk-ant-...
|
|
```
|
|
|
|
---
|
|
|
|
## Quick Start
|
|
|
|
The minimal example — planning-with-files inside a BoxLite VM:
|
|
|
|
```python
|
|
import asyncio
|
|
from pathlib import Path
|
|
from claudebox import ClaudeBox, Skill
|
|
|
|
# Load the SKILL.md content from the installed skill
|
|
SKILL_MD = Path.home() / ".claude" / "skills" / "planning-with-files" / "SKILL.md"
|
|
|
|
PLANNING_SKILL = Skill(
|
|
name="planning-with-files",
|
|
description="Manus-style file-based planning with persistent markdown",
|
|
files={
|
|
"/root/.claude/skills/planning-with-files/SKILL.md": SKILL_MD.read_text()
|
|
}
|
|
)
|
|
|
|
async def main():
|
|
async with ClaudeBox(
|
|
session_id="my-project",
|
|
skills=[PLANNING_SKILL]
|
|
) as box:
|
|
result = await box.code(
|
|
"Plan and implement a user authentication feature for the Express API"
|
|
)
|
|
print(result.response)
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
Claude Code finds the skill at `/root/.claude/skills/planning-with-files/SKILL.md` inside the VM. The three planning files (`task_plan.md`, `findings.md`, `progress.md`) are written to the box's working directory and persist across sessions.
|
|
|
|
---
|
|
|
|
## Persistent Sessions
|
|
|
|
ClaudeBox workspaces survive restarts. Pick up exactly where you left off:
|
|
|
|
```python
|
|
async def main():
|
|
# First session — starts the plan
|
|
async with ClaudeBox(session_id="auth-feature", skills=[PLANNING_SKILL]) as box:
|
|
await box.code("Create task_plan.md for the authentication feature")
|
|
|
|
# Later session — same workspace, plan files still there
|
|
async with ClaudeBox.reconnect("auth-feature") as box:
|
|
await box.code("Continue implementing the login endpoint from the plan")
|
|
|
|
# Clean up when done
|
|
await ClaudeBox.cleanup_session("auth-feature", remove_workspace=True)
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
---
|
|
|
|
## How Hooks Work Inside the VM
|
|
|
|
ClaudeBox runs Claude Code CLI natively inside the BoxLite micro-VM. This means planning-with-files hooks execute exactly as they do on your local machine:
|
|
|
|
| Hook | Trigger | What It Does |
|
|
|------|---------|--------------|
|
|
| **PreToolUse** | Before Write, Edit, Bash, Read, Glob, Grep | Reads first 30 lines of `task_plan.md` — keeps goals in attention |
|
|
| **PostToolUse** | After Write, Edit | Reminds agent to update plan status after file changes |
|
|
| **Stop** | When agent finishes | Runs completion check script before stopping |
|
|
|
|
The hook scripts need to be injected alongside SKILL.md. See the full example in `examples/boxlite/quickstart.py` for how to include them.
|
|
|
|
---
|
|
|
|
## Session Recovery
|
|
|
|
When your context fills up and you run `/clear`, the skill recovers the previous session automatically on next activation. Inside a ClaudeBox session, run manually:
|
|
|
|
```python
|
|
async with ClaudeBox.reconnect("my-project") as box:
|
|
await box.code(
|
|
"Run session catchup: python3 ~/.claude/skills/planning-with-files/scripts/session-catchup.py $(pwd)"
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Snapshots
|
|
|
|
BoxLite supports checkpointing. Snapshot before a risky implementation phase:
|
|
|
|
```python
|
|
from claudebox import ClaudeBox
|
|
from boxlite import Box
|
|
|
|
async def main():
|
|
async with ClaudeBox(session_id="risky-refactor", skills=[PLANNING_SKILL]) as box:
|
|
# Phase 1 complete — snapshot before the destructive refactor
|
|
await box.box.snapshot("pre-refactor")
|
|
|
|
result = await box.code("Refactor the database layer")
|
|
|
|
if "error" in result.response.lower():
|
|
await box.box.restore("pre-refactor")
|
|
print("Rolled back to pre-refactor snapshot")
|
|
|
|
asyncio.run(main())
|
|
```
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### Skill not activating inside the VM?
|
|
|
|
The skill file must be at `/root/.claude/skills/planning-with-files/SKILL.md` inside the VM. Verify by injecting a validation step:
|
|
|
|
```python
|
|
result = await box.code("ls ~/.claude/skills/planning-with-files/")
|
|
print(result.response)
|
|
```
|
|
|
|
### Hooks not running?
|
|
|
|
The Stop hook script (`check-complete.sh`) must also be injected. Add it to the `files` dict in your Skill object. See `examples/boxlite/quickstart.py` for the full implementation.
|
|
|
|
### Docker not found?
|
|
|
|
ClaudeBox uses Docker to pull OCI images for the VM. Install Docker Desktop (macOS/Windows) or Docker Engine (Linux). The sandbox itself does not run as a Docker container — Docker is only used for image management.
|
|
|
|
### BoxLite not available on Windows host?
|
|
|
|
BoxLite requires Linux KVM (Linux) or Hypervisor.framework (macOS). On Windows, use WSL2 with KVM enabled.
|
|
|
|
---
|
|
|
|
## See Also
|
|
|
|
- [BoxLite documentation](https://docs.boxlite.ai)
|
|
- [ClaudeBox repository](https://github.com/boxlite-ai/claudebox)
|
|
- [boxlite-mcp](https://github.com/boxlite-labs/boxlite-mcp) — MCP server for BoxLite sandboxing
|
|
- [Quick Start Guide](quickstart.md)
|
|
- [Workflow Diagram](workflow.md)
|
|
- [Author: @OthmanAdi](https://github.com/OthmanAdi)
|