{"_id":"@douglas-agent/sandbank-boxlite","name":"@douglas-agent/sandbank-boxlite","dist-tags":{"latest":"0.6.1"},"versions":{"0.6.1":{"name":"@douglas-agent/sandbank-boxlite","version":"0.6.1","description":"BoxLite bare-metal sandbox adapter for Sandbank","license":"MIT","type":"module","homepage":"https://sandbank.dev","repository":{"type":"git","url":"git+https://github.com/Xeonice/sandbank-douglas-agent.git","directory":"packages/boxlite"},"keywords":["sandbox","ai-agent","boxlite","bare-metal","kvm"],"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"}},"scripts":{"build":"tsc","typecheck":"tsc --noEmit","clean":"rm -rf dist"},"dependencies":{"@douglas-agent/sandbank-core":"^0.3.6"},"devDependencies":{"@types/node":"^25.3.0","typescript":"^5.7.3"},"gitHead":"0589f4137bb7d4e3bafb0f4dd1ef45e50253cd45","_id":"@douglas-agent/sandbank-boxlite@0.6.1","bugs":{"url":"https://github.com/Xeonice/sandbank-douglas-agent/issues"},"_nodeVersion":"24.15.0","_npmVersion":"11.14.1","dist":{"integrity":"sha512-3GMgUbHVcx/l+00p/Vwq736oFI9mZrFB+M06onKycO5UGmFLQDJXHrLKAjo9n1DF4PdliYuY3RXrMi5bRklM2A==","shasum":"129f81e60d74cc4c3257a5455fd5849bcd27dc85","tarball":"https://registry.npmjs.org/@douglas-agent/sandbank-boxlite/-/sandbank-boxlite-0.6.1.tgz","fileCount":17,"unpackedSize":73782,"attestations":{"url":"https://registry.npmjs.org/-/npm/v1/attestations/@douglas-agent%2fsandbank-boxlite@0.6.1","provenance":{"predicateType":"https://slsa.dev/provenance/v1"}},"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIHxX1KPjgm/joHZCrBIy12T5n5ZBT7WVfNVDBJs/AhYkAiEA99FaKOzUeFOLlZps+80mq8vt4wGmBl5rhDQMlH4rpcw="}]},"_npmUser":{"name":"douglasdong","email":"ad546971975@gmail.com"},"directories":{},"maintainers":[{"name":"douglasdong","email":"ad546971975@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sandbank-boxlite_0.6.1_1779268720871_0.10954718027896804"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-20T09:18:40.733Z","0.6.1":"2026-05-20T09:18:41.031Z","modified":"2026-05-20T09:18:41.385Z"},"maintainers":[{"name":"douglasdong","email":"ad546971975@gmail.com"}],"description":"BoxLite bare-metal sandbox adapter for Sandbank","homepage":"https://sandbank.dev","keywords":["sandbox","ai-agent","boxlite","bare-metal","kvm"],"repository":{"type":"git","url":"git+https://github.com/Xeonice/sandbank-douglas-agent.git","directory":"packages/boxlite"},"bugs":{"url":"https://github.com/Xeonice/sandbank-douglas-agent/issues"},"license":"MIT","readme":"# @douglas-agent/sandbank-boxlite\n\n> BoxLite bare-metal micro-VM sandbox adapter for [Sandbank](../../README.md).\n\nBoxLite provides lightweight micro-VMs using libkrun (Hypervisor.framework on macOS, KVM on Linux). This adapter supports two modes of operation:\n\n- **Remote mode** — Connect to a [BoxRun](https://github.com/nicholasgasior/boxlite) REST API server\n- **Local mode** — Run VMs directly on the local machine via the boxlite Python SDK\n\n## Install\n\n```bash\npnpm add @douglas-agent/sandbank-core @douglas-agent/sandbank-boxlite\n```\n\nFor local mode, you also need the boxlite Python package:\n\n```bash\npip install boxlite\n```\n\n## Usage\n\n### Remote mode (BoxRun REST API)\n\n```typescript\nimport { createProvider } from '@douglas-agent/sandbank-core'\nimport { BoxLiteAdapter } from '@douglas-agent/sandbank-boxlite'\n\nconst provider = createProvider(\n  new BoxLiteAdapter({\n    apiUrl: 'http://localhost:9090',\n    apiToken: process.env.BOXLITE_API_TOKEN,\n    prefix: 'default', // multi-tenant prefix (optional)\n  })\n)\n\nconst sandbox = await provider.create({\n  image: 'ubuntu:24.04',\n  resources: { cpu: 2, memory: 1024 },\n})\n\nconst { stdout } = await sandbox.exec('uname -a')\nawait provider.destroy(sandbox.id)\n```\n\n### Local mode (Python SDK)\n\n```typescript\nimport { createProvider } from '@douglas-agent/sandbank-core'\nimport { BoxLiteAdapter } from '@douglas-agent/sandbank-boxlite'\n\nconst provider = createProvider(\n  new BoxLiteAdapter({\n    mode: 'local',\n    pythonPath: '/usr/bin/python3', // optional, defaults to 'python3'\n    boxliteHome: '~/.boxlite',     // optional\n  })\n)\n\nconst sandbox = await provider.create({ image: 'ubuntu:24.04' })\nconst { stdout } = await sandbox.exec('echo hello')\nawait provider.destroy(sandbox.id)\n```\n\n### Local OCI rootfs (skip registry pull)\n\nIf `image` is an absolute path, it is treated as a local OCI layout directory:\n\n```typescript\n// Export image: skopeo copy docker-daemon:myimage:latest oci:~/.boxlite/myimage-oci:latest\nconst sandbox = await provider.create({ image: '/Users/you/.boxlite/myimage-oci' })\n```\n\n### OAuth2 authentication (remote mode)\n\n```typescript\nnew BoxLiteAdapter({\n  apiUrl: 'http://boxrun.example.com:9090',\n  clientId: process.env.BOXLITE_CLIENT_ID,\n  clientSecret: process.env.BOXLITE_CLIENT_SECRET,\n})\n```\n\n## Capabilities\n\n| Capability | Remote | Local |\n|------------|:------:|:-----:|\n| `exec.stream` | ✅ | ✅ |\n| `terminal` | ✅ | ✅ |\n| `sleep` | ✅ | ✅ |\n| `port.expose` | ✅ | ✅ |\n| `snapshot` | ✅ | — |\n\n## Characteristics\n\n- **Runtime:** Micro-VM (libkrun)\n- **Cold start:** ~3-5s\n- **File I/O:** tar archive upload/download\n- **Hypervisor:** Hypervisor.framework (macOS) / KVM (Linux)\n- **Local dependency:** `boxlite` Python package (local mode only)\n\n## Architecture\n\n```\n┌─────────────────────────────────────┐\n│         BoxLiteAdapter              │\n│  mode: 'remote' | 'local'          │\n├──────────────┬──────────────────────┤\n│ REST Client  │  Local Client        │\n│ (fetch)      │  (Python subprocess) │\n├──────────────┼──────────────────────┤\n│ BoxRun API   │  boxlite Python SDK  │\n│ (HTTP/JSON)  │  (JSON-line bridge)  │\n└──────────────┴──────────────────────┘\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-fa85606e0b11f773a99e7a1a0b7108a3"}