starred/planning-with-files

Fork 0

mirror of https://github.com/OthmanAdi/planning-with-files.git synced 2026-04-26 00:16:01 +03:00

[GH-ISSUE #84] Proposal: Add BoxLite integration/use-case entry (optional sandbox path) #51

New issue

Closed

opened 2026-03-03 18:50:17 +03:00 by kerem · 2 comments

kerem commented

2026-03-03 18:50:17 +03:00

Owner

Originally created by @DorianZheng on GitHub (Feb 26, 2026).
Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/84

Summary

Could we add a BoxLite integration/use-case entry as an optional sandbox path?

This is a docs/ecosystem request, not a core architecture replacement.

Why

Useful for users who want an optional micro-VM sandbox mode.
Keeps current project behavior unchanged.
Improves discoverability of secure runtime options.

Tiny example (Node.js)

import { SimpleBox } from '@boxlite-ai/boxlite';

async function main() {
  const box = new SimpleBox({ image: 'alpine:latest', autoRemove: true });
  try {
    const result = await box.exec('echo', 'hello');
    console.log(result.stdout);
    const m = await box.metrics();
    console.log(`totalCreateDurationMs=${m.totalCreateDurationMs}`);
  } finally {
    await box.stop();
  }
}

main();

Warm startup is typically under 200ms; cold starts can be higher depending on image/cache state.

Suggested scope

Add a BoxLite integration/use-case section (or skill entry).
Include compatibility notes and known limits.
Include quick validation steps.

Originally created by @DorianZheng on GitHub (Feb 26, 2026). Original GitHub issue: https://github.com/OthmanAdi/planning-with-files/issues/84 ## Summary Could we add a **BoxLite integration/use-case entry** as an optional sandbox path? This is a docs/ecosystem request, not a core architecture replacement. ## Why - Useful for users who want an optional micro-VM sandbox mode. - Keeps current project behavior unchanged. - Improves discoverability of secure runtime options. ## Tiny example (Node.js) ```ts import { SimpleBox } from '@boxlite-ai/boxlite'; async function main() { const box = new SimpleBox({ image: 'alpine:latest', autoRemove: true }); try { const result = await box.exec('echo', 'hello'); console.log(result.stdout); const m = await box.metrics(); console.log(`totalCreateDurationMs=${m.totalCreateDurationMs}`); } finally { await box.stop(); } } main(); ``` Warm startup is typically under 200ms; cold starts can be higher depending on image/cache state. ## Suggested scope 1. Add a BoxLite integration/use-case section (or skill entry). 2. Include compatibility notes and known limits. 3. Include quick validation steps.

kerem closed this issue

2026-03-03 18:50:17 +03:00

kerem commented

2026-03-03 18:50:17 +03:00

Author

Owner

@OthmanAdi commented on GitHub (Feb 26, 2026):

Hi @DorianZheng,

Solid proposal. I went deep on this before responding. Here is everything I found and exactly what will be built.

What BoxLite actually is:

BoxLite (boxlite.ai, Apache-2.0, actively maintained at v0.2.11) is a micro-VM sandbox runtime. The analogy their team uses is 'SQLite for sandboxing': you embed it as a library, no daemon, no root, no Docker Desktop required. It uses KVM on Linux and Hypervisor.framework on macOS to give each box its own kernel. Not containers, not namespaces. Hardware isolation.

SDKs exist for Python (3.10+), Node.js (18+), Rust, and C. The key properties that matter for this integration: boxes are stateful and persistent (install packages, create files, come back later and pick up where you left off), they support snapshots (checkpoint before a risky planning phase), and they boot fast.

The real integration layer:

BoxLite has a dedicated Claude Code integration called ClaudeBox (pip install claudebox, github.com/boxlite-ai/claudebox). This is not a third-party wrapper. BoxLite's own team built it. ClaudeBox runs Claude Code CLI inside a BoxLite micro-VM and has its own Python-based skill system:

from claudebox import ClaudeBox, Skill

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_CONTENT
    }
)

async with ClaudeBox(skills=[PLANNING_SKILL]) as box:
    result = await box.code('Plan and implement the authentication feature')
    print(result.response)

The Skill object injects files directly into the VM's filesystem at startup. Claude Code running inside the VM finds the skill at the expected path. Hooks (PreToolUse, PostToolUse, Stop) work because Claude Code is the one executing them inside the sandbox. Planning files (task_plan.md, findings.md, progress.md) persist across sessions because ClaudeBox workspaces live at ~/.claudebox/sessions/.

There is also boxlite-mcp (boxlite-labs/boxlite-mcp) for MCP-based integration and boxlite-ai/claudebox/examples for working reference code.

What I will build:

No .boxlite/ folder at repo root. BoxLite does not do file-system skill discovery, so creating one would be misleading. The integration lives in documentation and examples.

docs/boxlite.md: Full guide following the same structure as docs/mastra.md. Covers what BoxLite/ClaudeBox is, ClaudeBox installation, the Python Skill object pattern with working code, session persistence, how hooks work inside the VM, session recovery, troubleshooting, and a 'See Also' section with all relevant links.
examples/boxlite/quickstart.py: Working Python example using ClaudeBox's Skill API that pre-loads planning-with-files into the VM.
examples/boxlite/README.md: Context for the example.
README update: New 'Sandbox Runtimes' section after the 16-platform IDE table. BoxLite is infrastructure, not an IDE. Keeping them separate is the honest thing to do.
CHANGELOG: v2.18.0 entry crediting this issue.
CONTRIBUTORS.md: Your name in the Issue Reporters section.
Release: v2.18.0 tag with your username in the contributors section.

Starting implementation now.

Ahmad

@OthmanAdi commented on GitHub (Feb 26, 2026): Hi @DorianZheng, Solid proposal. I went deep on this before responding. Here is everything I found and exactly what will be built. **What BoxLite actually is:** BoxLite (boxlite.ai, Apache-2.0, actively maintained at v0.2.11) is a micro-VM sandbox runtime. The analogy their team uses is 'SQLite for sandboxing': you embed it as a library, no daemon, no root, no Docker Desktop required. It uses KVM on Linux and Hypervisor.framework on macOS to give each box its own kernel. Not containers, not namespaces. Hardware isolation. SDKs exist for Python (3.10+), Node.js (18+), Rust, and C. The key properties that matter for this integration: boxes are stateful and persistent (install packages, create files, come back later and pick up where you left off), they support snapshots (checkpoint before a risky planning phase), and they boot fast. **The real integration layer:** BoxLite has a dedicated Claude Code integration called ClaudeBox (`pip install claudebox`, github.com/boxlite-ai/claudebox). This is not a third-party wrapper. BoxLite's own team built it. ClaudeBox runs Claude Code CLI inside a BoxLite micro-VM and has its own Python-based skill system: ```python from claudebox import ClaudeBox, Skill 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_CONTENT } ) async with ClaudeBox(skills=[PLANNING_SKILL]) as box: result = await box.code('Plan and implement the authentication feature') print(result.response) ``` The Skill object injects files directly into the VM's filesystem at startup. Claude Code running inside the VM finds the skill at the expected path. Hooks (PreToolUse, PostToolUse, Stop) work because Claude Code is the one executing them inside the sandbox. Planning files (task_plan.md, findings.md, progress.md) persist across sessions because ClaudeBox workspaces live at `~/.claudebox/sessions/`. There is also boxlite-mcp (boxlite-labs/boxlite-mcp) for MCP-based integration and boxlite-ai/claudebox/examples for working reference code. **What I will build:** No `.boxlite/` folder at repo root. BoxLite does not do file-system skill discovery, so creating one would be misleading. The integration lives in documentation and examples. - `docs/boxlite.md`: Full guide following the same structure as `docs/mastra.md`. Covers what BoxLite/ClaudeBox is, ClaudeBox installation, the Python Skill object pattern with working code, session persistence, how hooks work inside the VM, session recovery, troubleshooting, and a 'See Also' section with all relevant links. - `examples/boxlite/quickstart.py`: Working Python example using ClaudeBox's Skill API that pre-loads planning-with-files into the VM. - `examples/boxlite/README.md`: Context for the example. - README update: New 'Sandbox Runtimes' section after the 16-platform IDE table. BoxLite is infrastructure, not an IDE. Keeping them separate is the honest thing to do. - CHANGELOG: v2.18.0 entry crediting this issue. - CONTRIBUTORS.md: Your name in the Issue Reporters section. - Release: v2.18.0 tag with your username in the contributors section. Starting implementation now. Ahmad

kerem commented

2026-03-03 18:50:17 +03:00

Author

Owner

@OthmanAdi commented on GitHub (Feb 26, 2026):

This is done. v2.18.0 is live.

Here is exactly what shipped:

docs/boxlite.md - Full integration guide. Covers what BoxLite and ClaudeBox actually are (not just links, actual explanation), the ClaudeBox Python Skill API pattern with working code, persistent sessions across reconnects, how all three hooks work inside the VM and why (Claude Code is running natively, not in a wrapper), snapshot/rollback before risky phases, session recovery, troubleshooting for the three most common failure modes, and a See Also section with every relevant link including boxlite-mcp.

examples/boxlite/quickstart.py - Working Python example. Loads planning-with-files via ClaudeBox's Skill object, injects SKILL.md and the stop hook script into /root/.claude/skills/ inside the VM, runs a full planning session, shows the created files. Includes a second example for multi-session workflows with reconnect and cleanup. Graceful error handling if the skill is not installed locally.

examples/boxlite/README.md - Clean context for the example directory.

README - New Sandbox Runtimes section after the 16-platform IDE table. BoxLite is infrastructure, not an IDE. Collapsing it into that table would have been technically wrong and confusing for users. The section is separate, clearly labeled, and links to the full guide. BoxLite badge added. Documentation table updated. Version bumped to 2.18.0.

The decision not to create a .boxlite/ folder was the right one. ClaudeBox loads skills through its Python Skill object at runtime. A .boxlite/skills/planning-with-files/SKILL.md file at repo root would never be read by anything and would create a false impression that BoxLite has native skill discovery. It does not. The docs show the real path.

You have been added to CONTRIBUTORS.md in the Issue Reporters section and credited in the v2.18.0 release notes.

Release: https://github.com/OthmanAdi/planning-with-files/releases/tag/v2.18.0

Thank you for bringing this one. BoxLite is genuinely interesting infrastructure and the ClaudeBox layer makes the integration clean. This was worth doing properly.

Ahmad

@OthmanAdi commented on GitHub (Feb 26, 2026): This is done. v2.18.0 is live. Here is exactly what shipped: **docs/boxlite.md** - Full integration guide. Covers what BoxLite and ClaudeBox actually are (not just links, actual explanation), the ClaudeBox Python Skill API pattern with working code, persistent sessions across reconnects, how all three hooks work inside the VM and why (Claude Code is running natively, not in a wrapper), snapshot/rollback before risky phases, session recovery, troubleshooting for the three most common failure modes, and a See Also section with every relevant link including boxlite-mcp. **examples/boxlite/quickstart.py** - Working Python example. Loads planning-with-files via ClaudeBox's Skill object, injects SKILL.md and the stop hook script into /root/.claude/skills/ inside the VM, runs a full planning session, shows the created files. Includes a second example for multi-session workflows with reconnect and cleanup. Graceful error handling if the skill is not installed locally. **examples/boxlite/README.md** - Clean context for the example directory. **README** - New Sandbox Runtimes section after the 16-platform IDE table. BoxLite is infrastructure, not an IDE. Collapsing it into that table would have been technically wrong and confusing for users. The section is separate, clearly labeled, and links to the full guide. BoxLite badge added. Documentation table updated. Version bumped to 2.18.0. The decision not to create a .boxlite/ folder was the right one. ClaudeBox loads skills through its Python Skill object at runtime. A .boxlite/skills/planning-with-files/SKILL.md file at repo root would never be read by anything and would create a false impression that BoxLite has native skill discovery. It does not. The docs show the real path. You have been added to CONTRIBUTORS.md in the Issue Reporters section and credited in the v2.18.0 release notes. Release: https://github.com/OthmanAdi/planning-with-files/releases/tag/v2.18.0 Thank you for bringing this one. BoxLite is genuinely interesting infrastructure and the ClaudeBox layer makes the integration clean. This was worth doing properly. Ahmad

kerem referenced this issue

2026-03-03 18:50:25 +03:00

[PR #51] [MERGED] Add the start command #68

No labels

bug

pull-request

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

starred/planning-with-files#51

No description provided.

Rows
Columns