feat(boxlite): use official node sdk locally

Author: guo-yu

CHANGELOG.md

@@ -16,6 +16,7 @@ All notable changes to this project will be documented in this file.
 
 ### Changed
 - README terminal capability updated from ❌ to ✅ for all providers (ttyd-based implementation)
+- `@sandbank.dev/boxlite` local mode now uses the official `@boxlite-ai/boxlite` Node.js SDK instead of the Python bridge
 
 ## [0.1.0] - 2026-02-27
 

docs/boxlite-troubleshooting.md

@@ -2,6 +2,8 @@
 
 BoxLite 是一个嵌入式微虚拟机运行时，使用 libkrun（基于 KVM/Hypervisor.framework）在硬件隔离的 VM 中运行 OCI 容器。BoxRun 是其 CLI 管理层，提供 REST API。
 
+> 当前 Sandbank JS SDK 的 local 模式使用官方 `@boxlite-ai/boxlite` Node.js SDK。本文中关于 `boxlite` Python 库和 BoxRun v0.3.0 的内容主要是历史排障背景，用于理解旧版本兼容性问题。
+
 ## 平台支持
 
 | 平台 | 状态 | 虚拟化后端 |
@@ -14,7 +16,18 @@ BoxLite 是一个嵌入式微虚拟机运行时，使用 libkrun（基于 KVM/Hy
 
 ## 安装
 
-### BoxLite Python 库
+### BoxLite Node.js SDK
+
+Sandbank 的 `@sandbank.dev/boxlite` local 模式会通过 `@boxlite-ai/boxlite` 直接调用官方 Node.js SDK，不需要再配置 Python venv：
+
+```typescript
+new BoxLiteAdapter({
+  mode: 'local',
+  boxliteHome: '~/.boxlite',
+})
+```
+
+### BoxLite Python 库（历史排障）
 
 ```bash
 # 需要 Python 3.10+
@@ -108,7 +121,7 @@ EOF
 chmod +x ~/.boxrun/runtime/boxlite-shim
 ```
 
-**解决方案（macOS）：** BoxRun v0.3.0 在 macOS 上还有额外问题（jailer 被禁用），wrapper shim 不够。建议直接使用 boxlite Python 库：
+**解决方案（macOS）：** BoxRun v0.3.0 在 macOS 上还有额外问题（jailer 被禁用），wrapper shim 不够。当前 JS SDK 建议使用 `@sandbank.dev/boxlite` local 模式；旧版排障也可以直接使用 boxlite Python 库验证底层 runtime：
 
 ```python
 import boxlite, asyncio
@@ -136,7 +149,7 @@ BoxRun v0.3.0 在 macOS 上不启用 seatbelt sandbox，而 boxlite v0.6.0 需
 | Guest rootfs | 直接引用 image disk | Reflink + version key 管理 |
 | 结果 | ❌ Timeout | ✅ 正常启动 |
 
-**解决方案：** 在 macOS 上使用 boxlite Python 库而非 BoxRun。
+**解决方案：** 在 macOS 上使用官方 SDK（Sandbank JS local 模式或 Python 库）而非旧 BoxRun。
 
 #### 1c. Hypervisor entitlement 缺失
 
@@ -396,10 +409,11 @@ log stream --predicate 'eventMessage CONTAINS "Sandbox:" AND eventMessage CONTAI
 
 ## 版本兼容性矩阵
 
-| BoxRun | boxlite (Python) | boxlite-shim | DB Schema | 兼容性 |
-|--------|------------------|--------------|-----------|--------|
+| BoxRun | SDK | boxlite-shim | DB Schema | 兼容性 |
+|--------|-----|--------------|-----------|--------|
 | v0.3.0 | — | v0.5.10 | v4 | ✅ (Linux/WSL2 only) |
-| v0.3.0 | v0.6.0 | v0.6.0 | v4 vs v6 ❌ | ❌ 不兼容 |
-| — | v0.6.0 | v0.6.0 | v6 | ✅ (Python 直接使用) |
+| v0.3.0 | Python v0.6.0 | v0.6.0 | v4 vs v6 ❌ | ❌ 不兼容 |
+| — | Python v0.6.0 | v0.6.0 | v6 | ✅ (Python 直接使用) |
+| — | Node.js `@boxlite-ai/boxlite` v0.9.7 | v0.9.7 | current | ✅ (Sandbank JS local mode) |
 
-**建议：** 在 BoxRun 更新到兼容 v0.6.0 之前，macOS 上优先使用 boxlite Python 库直接操作 VM。
+**建议：** Sandbank JS SDK 优先使用 local Node.js SDK 路径；只有在排查旧 BoxRun 或 Python 调用方时才使用 Python 库。

docs/sandbank-agent-configuration.ja.md

@@ -182,7 +182,7 @@ await runWorkspaceSandboxTask({
 | Fly.io | `FLY_API_TOKEN`、`FLY_APP_NAME`。任意で `FLY_REGION` |
 | Cloudflare | `env.SANDBOX` などの Worker Durable Object binding。volume には任意の storage config |
 | BoxLite remote | `BOXLITE_API_URL` と、`BOXLITE_API_TOKEN` または OAuth2 client credentials |
-| BoxLite local | ローカルの `boxlite` Python package。任意で `pythonPath` と `boxliteHome` |
+| BoxLite local | 公式 `@boxlite-ai/boxlite` Node.js SDK。任意で `boxliteHome` |
 | E2B | `E2B_API_KEY`。論理イメージは E2B template にマップされます |
 
 ## イメージ要件

docs/sandbank-agent-configuration.md

@@ -182,7 +182,7 @@ await runWorkspaceSandboxTask({
 | Fly.io | `FLY_API_TOKEN`, `FLY_APP_NAME`; optional `FLY_REGION` |
 | Cloudflare | Worker Durable Object binding such as `env.SANDBOX`; optional storage config for volumes |
 | BoxLite remote | `BOXLITE_API_URL` plus `BOXLITE_API_TOKEN` or OAuth2 client credentials |
-| BoxLite local | local `boxlite` Python package; optional `pythonPath` and `boxliteHome` |
+| BoxLite local | official `@boxlite-ai/boxlite` Node.js SDK; optional `boxliteHome` |
 | E2B | `E2B_API_KEY`; logical images map to E2B templates |
 
 ## Image Requirements

docs/sandbank-agent-configuration.zh-CN.md

@@ -182,7 +182,7 @@ await runWorkspaceSandboxTask({
 | Fly.io | `FLY_API_TOKEN`、`FLY_APP_NAME`；可选 `FLY_REGION` |
 | Cloudflare | Worker Durable Object binding，例如 `env.SANDBOX`；volume 需要可选 storage config |
 | BoxLite remote | `BOXLITE_API_URL`，以及 `BOXLITE_API_TOKEN` 或 OAuth2 client credentials |
-| BoxLite local | 本机 `boxlite` Python package；可选 `pythonPath` 和 `boxliteHome` |
+| BoxLite local | 官方 `@boxlite-ai/boxlite` Node.js SDK；可选 `boxliteHome` |
 | E2B | `E2B_API_KEY`；逻辑镜像映射到 E2B template |
 
 ## 镜像要求

packages/boxlite/README.md

@@ -5,20 +5,14 @@
 BoxLite provides lightweight micro-VMs using libkrun (Hypervisor.framework on macOS, KVM on Linux). This adapter supports two modes of operation:
 
 - **Remote mode** — Connect to a [BoxRun](https://github.com/nicholasgasior/boxlite) REST API server
-- **Local mode** — Run VMs directly on the local machine via the boxlite Python SDK
+- **Local mode** — Run VMs directly on the local machine via the official BoxLite Node.js SDK
 
 ## Install
 
 ```bash
 pnpm add @sandbank.dev/core @sandbank.dev/boxlite
 ```
 
-For local mode, you also need the boxlite Python package:
-
-```bash
-pip install boxlite
-```
-
 ## Usage
 
 ### Remote mode (BoxRun REST API)
@@ -44,7 +38,7 @@ const { stdout } = await sandbox.exec('uname -a')
 await provider.destroy(sandbox.id)
 ```
 
-### Local mode (Python SDK)
+### Local mode (Node.js SDK)
 
 ```typescript
 import { createProvider } from '@sandbank.dev/core'
@@ -53,8 +47,7 @@ import { BoxLiteAdapter } from '@sandbank.dev/boxlite'
 const provider = createProvider(
   new BoxLiteAdapter({
     mode: 'local',
-    pythonPath: '/usr/bin/python3', // optional, defaults to 'python3'
-    boxliteHome: '~/.boxlite',     // optional
+    boxliteHome: '~/.boxlite', // optional
   })
 )
 
@@ -90,15 +83,15 @@ new BoxLiteAdapter({
 | `terminal` | ✅ | ✅ |
 | `sleep` | ✅ | ✅ |
 | `port.expose` | ✅ | ✅ |
-| `snapshot` | ✅ | — |
+| `snapshot` | ✅ | ✅ |
 
 ## Characteristics
 
 - **Runtime:** Micro-VM (libkrun)
 - **Cold start:** ~3-5s
 - **File I/O:** tar archive upload/download
 - **Hypervisor:** Hypervisor.framework (macOS) / KVM (Linux)
-- **Local dependency:** `boxlite` Python package (local mode only)
+- **Local dependency:** official `@boxlite-ai/boxlite` Node.js SDK (local mode only)
 
 ## Architecture
 
@@ -108,10 +101,10 @@ new BoxLiteAdapter({
 │  mode: 'remote' | 'local'          │
 ├──────────────┬──────────────────────┤
 │ REST Client  │  Local Client        │
-│ (fetch)      │  (Python subprocess) │
+│ (fetch)      │  (Node.js SDK)       │
 ├──────────────┼──────────────────────┤
-│ BoxRun API   │  boxlite Python SDK  │
-│ (HTTP/JSON)  │  (JSON-line bridge)  │
+│ BoxRun API   │  @boxlite-ai/boxlite │
+│ (HTTP/JSON)  │  (N-API binding)     │
 └──────────────┴──────────────────────┘
 ```
 

packages/boxlite/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sandbank.dev/boxlite",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "BoxLite bare-metal sandbox adapter for Sandbank",
   "license": "MIT",
   "type": "module",
@@ -32,6 +32,7 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
+    "@boxlite-ai/boxlite": "^0.9.7",
     "@sandbank.dev/core": "workspace:*"
   },
   "devDependencies": {

packages/boxlite/src/index.ts

@@ -1,4 +1,4 @@
-// @sandbank.dev/boxlite — BoxLite sandbox adapter (remote REST API + local Python SDK)
+// @sandbank.dev/boxlite — BoxLite sandbox adapter (remote REST API + local Node.js SDK)
 export { BoxLiteAdapter } from './adapter.js'
 export type {
   BoxLiteAdapterConfig,