@sandbank.dev/boxlite 0.1.1 → 0.3.0

package/README.md

@@ -0,0 +1,111 @@
+# @sandbank.dev/boxlite
+
+> BoxLite bare-metal micro-VM sandbox adapter for [Sandbank](../../README.md).
+
+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
+
+## 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)
+
+```typescript
+import { createProvider } from '@sandbank.dev/core'
+import { BoxLiteAdapter } from '@sandbank.dev/boxlite'
+
+const provider = createProvider(
+  new BoxLiteAdapter({
+    apiUrl: 'http://localhost:9090',
+    apiToken: process.env.BOXLITE_API_TOKEN,
+    prefix: 'default', // multi-tenant prefix (optional)
+  })
+)
+
+const sandbox = await provider.create({
+  image: 'ubuntu:24.04',
+  resources: { cpu: 2, memory: 1024 },
+})
+
+const { stdout } = await sandbox.exec('uname -a')
+await provider.destroy(sandbox.id)
+```
+
+### Local mode (Python SDK)
+
+```typescript
+import { createProvider } from '@sandbank.dev/core'
+import { BoxLiteAdapter } from '@sandbank.dev/boxlite'
+
+const provider = createProvider(
+  new BoxLiteAdapter({
+    mode: 'local',
+    pythonPath: '/usr/bin/python3', // optional, defaults to 'python3'
+    boxliteHome: '~/.boxlite',     // optional
+  })
+)
+
+const sandbox = await provider.create({ image: 'ubuntu:24.04' })
+const { stdout } = await sandbox.exec('echo hello')
+await provider.destroy(sandbox.id)
+```
+
+### OAuth2 authentication (remote mode)
+
+```typescript
+new BoxLiteAdapter({
+  apiUrl: 'http://boxrun.example.com:9090',
+  clientId: process.env.BOXLITE_CLIENT_ID,
+  clientSecret: process.env.BOXLITE_CLIENT_SECRET,
+})
+```
+
+## Capabilities
+
+| Capability | Remote | Local |
+|------------|:------:|:-----:|
+| `exec.stream` | ✅ | ✅ |
+| `terminal` | ✅ | ✅ |
+| `sleep` | ✅ | ✅ |
+| `port.expose` | ✅ | ✅ |
+| `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)
+
+## Architecture
+
+```
+┌─────────────────────────────────────┐
+│         BoxLiteAdapter              │
+│  mode: 'remote' | 'local'          │
+├──────────────┬──────────────────────┤
+│ REST Client  │  Local Client        │
+│ (fetch)      │  (Python subprocess) │
+├──────────────┼──────────────────────┤
+│ BoxRun API   │  boxlite Python SDK  │
+│ (HTTP/JSON)  │  (JSON-line bridge)  │
+└──────────────┴──────────────────────┘
+```
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -5,12 +5,14 @@ export declare class BoxLiteAdapter implements SandboxAdapter {
     readonly capabilities: ReadonlySet<Capability>;
     private readonly client;
     private readonly config;
-    /** Track port mappings per box: boxId → Map<guestPort, hostPort> */
+    private readonly host;
     private readonly portMaps;
     constructor(config: BoxLiteAdapterConfig);
     createSandbox(config: CreateConfig): Promise<AdapterSandbox>;
     getSandbox(id: string): Promise<AdapterSandbox>;
     listSandboxes(filter?: ListFilter): Promise<SandboxInfo[]>;
     destroySandbox(id: string): Promise<void>;
+    /** Dispose the adapter and clean up resources (e.g. Python bridge process) */
+    dispose(): Promise<void>;
 }
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,YAAY,EAGZ,UAAU,EACV,cAAc,EACd,WAAW,EAIZ,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EAAE,oBAAoB,EAAc,MAAM,YAAY,CAAA;AAsKlE,qBAAa,cAAe,YAAW,cAAc;IACnD,QAAQ,CAAC,IAAI,aAAY;IACzB,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAM5C;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,oEAAoE;IACpE,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;gBAEtD,MAAM,EAAE,oBAAoB;IAKlC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IA0C5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAW/C,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA0B1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAShD"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,YAAY,EAGZ,UAAU,EACV,cAAc,EACd,WAAW,EAIZ,MAAM,oBAAoB,CAAA;AAI3B,OAAO,KAAK,EAAE,oBAAoB,EAA6B,MAAM,YAAY,CAAA;AAoKjF,qBAAa,cAAe,YAAW,cAAc;IACnD,QAAQ,CAAC,IAAI,aAAY;IACzB,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAAA;IAE9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAQ;IAC7B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAyC;gBAEtD,MAAM,EAAE,oBAAoB;IAalC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAuC5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAW/C,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IA0B1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAU/C,8EAA8E;IACxE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/adapter.js

@@ -1,5 +1,6 @@
 import { SandboxNotFoundError, ProviderError } from '@sandbank.dev/core';
-import { createBoxLiteClient } from './client.js';
+import { createBoxLiteRestClient } from './client.js';
+import { createBoxLiteLocalClient } from './local-client.js';
 /** Map BoxLite box status to Sandbank SandboxState */
 function mapState(status) {
     switch (status) {
@@ -15,26 +16,26 @@ function mapState(status) {
             return 'error';
     }
 }
-/** Extract host from API URL for port exposure */
-function getApiHost(apiUrl) {
+/** Resolve the host used for port exposure and terminal URLs */
+function resolveHost(config) {
+    if (config.mode === 'local')
+        return '127.0.0.1';
     try {
-        const url = new URL(apiUrl);
-        return url.hostname;
+        return new URL(config.apiUrl).hostname;
     }
     catch {
-        return apiUrl;
+        return config.apiUrl;
     }
 }
 /** Wrap a BoxLite box into an AdapterSandbox */
-function wrapBox(box, client, config, portMappings) {
+function wrapBox(box, client, host, portMappings) {
     return {
-        get id() { return box.box_id; },
+        get id() { return box.id; },
         get state() { return mapState(box.status); },
         get createdAt() { return box.created_at; },
         async exec(command, options) {
-            const result = await client.exec(box.box_id, {
-                command: 'bash',
-                args: ['-c', command],
+            const result = await client.exec(box.id, {
+                cmd: ['bash', '-c', command],
                 working_dir: options?.cwd,
                 timeout_seconds: options?.timeout ? Math.ceil(options.timeout / 1000) : undefined,
             });
@@ -45,9 +46,8 @@ function wrapBox(box, client, config, portMappings) {
             };
         },
         async execStream(command, options) {
-            return client.execStream(box.box_id, {
-                command: 'bash',
-                args: ['-c', command],
+            return client.execStream(box.id, {
+                cmd: ['bash', '-c', command],
                 working_dir: options?.cwd,
                 timeout_seconds: options?.timeout ? Math.ceil(options.timeout / 1000) : undefined,
             });
@@ -58,7 +58,6 @@ function wrapBox(box, client, config, portMappings) {
                 data = archive;
             }
             else {
-                // Collect ReadableStream into Uint8Array
                 const reader = archive.getReader();
                 const chunks = [];
                 while (true) {
@@ -75,62 +74,55 @@ function wrapBox(box, client, config, portMappings) {
                     offset += chunk.length;
                 }
             }
-            await client.uploadFiles(box.box_id, destDir ?? '/', data);
+            await client.uploadFiles(box.id, destDir ?? '/', data);
         },
         async downloadArchive(srcDir) {
-            return client.downloadFiles(box.box_id, srcDir ?? '/');
+            return client.downloadFiles(box.id, srcDir ?? '/');
         },
         async sleep() {
-            await client.stopBox(box.box_id);
+            await client.stopBox(box.id);
         },
         async wake() {
-            await client.startBox(box.box_id);
+            await client.startBox(box.id);
         },
         async createSnapshot(name) {
             const snapshotName = name ?? `snap-${Date.now()}`;
-            await client.createSnapshot(box.box_id, snapshotName);
+            await client.createSnapshot(box.id, snapshotName);
             return { snapshotId: snapshotName };
         },
         async restoreSnapshot(snapshotId) {
-            await client.restoreSnapshot(box.box_id, snapshotId);
+            await client.restoreSnapshot(box.id, snapshotId);
         },
         async exposePort(port) {
             const hostPort = portMappings.get(port) ?? port;
-            const host = getApiHost(config.apiUrl);
             return { url: `http://${host}:${hostPort}` };
         },
         async startTerminal(options) {
             const port = 7681;
             const shell = options?.shell ?? '/bin/bash';
-            const ttydUrl = 'https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd.x86_64';
-            // 1. Ensure ttyd is available
-            const check = await client.exec(box.box_id, { command: 'which', args: ['ttyd'] });
+            const ttydBase = 'https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd';
+            const check = await client.exec(box.id, { cmd: ['which', 'ttyd'] });
             if (check.exitCode !== 0) {
-                await client.exec(box.box_id, {
-                    command: 'bash',
-                    args: ['-c',
-                        `command -v curl > /dev/null && curl -sL ${ttydUrl} -o /usr/local/bin/ttyd`
-                            + ` || { command -v wget > /dev/null && wget -qO /usr/local/bin/ttyd ${ttydUrl}; }`
-                            + ` || { apt-get update -qq && apt-get install -y -qq wget > /dev/null && wget -qO /usr/local/bin/ttyd ${ttydUrl}; }`,
+                await client.exec(box.id, {
+                    cmd: ['bash', '-c',
+                        `ARCH=$(uname -m); case "$ARCH" in aarch64|arm64) ARCH=aarch64;; x86_64) ARCH=x86_64;; *) echo "Unsupported arch: $ARCH" >&2; exit 1;; esac; `
+                            + `TTYD_URL="${ttydBase}.$ARCH"; `
+                            + `command -v curl > /dev/null && curl -sL "$TTYD_URL" -o /usr/local/bin/ttyd`
+                            + ` || { command -v wget > /dev/null && wget -qO /usr/local/bin/ttyd "$TTYD_URL"; }`
+                            + ` || { apt-get update -qq && apt-get install -y -qq wget > /dev/null && wget -qO /usr/local/bin/ttyd "$TTYD_URL"; }`,
                     ],
                 });
-                await client.exec(box.box_id, {
-                    command: 'chmod',
-                    args: ['+x', '/usr/local/bin/ttyd'],
+                await client.exec(box.id, {
+                    cmd: ['chmod', '+x', '/usr/local/bin/ttyd'],
                 });
             }
-            // 2. Start ttyd in background (-W enables write)
-            await client.exec(box.box_id, {
-                command: 'bash',
-                args: ['-c', `nohup ttyd -W -p ${port} '${shell.replace(/'/g, "'\\''")}' > /dev/null 2>&1 &`],
+            await client.exec(box.id, {
+                cmd: ['bash', '-c', `nohup ttyd -W -p ${port} '${shell.replace(/'/g, "'\\''")}' > /dev/null 2>&1 &`],
             });
-            // 3. Wait for ttyd to be ready
-            await client.exec(box.box_id, {
-                command: 'bash',
-                args: ['-c', `for i in $(seq 1 20); do pgrep -x ttyd > /dev/null && break || sleep 0.5; done`],
+            await client.exec(box.id, {
+                cmd: ['bash', '-c', `for i in $(seq 1 20); do pgrep -x ttyd > /dev/null && break || sleep 0.5; done`],
             });
             const hostPort = portMappings.get(port) ?? port;
-            const host = getApiHost(config.apiUrl);
             return {
                 url: `ws://${host}:${hostPort}/ws`,
                 port,
@@ -143,55 +135,60 @@ function isNotFound(err) {
     const msg = err instanceof Error ? err.message : String(err);
     return msg.includes('404') || msg.includes('not found') || msg.includes('Not Found');
 }
+/** Create the appropriate client based on config mode */
+function createClient(config) {
+    if (config.mode === 'local') {
+        return createBoxLiteLocalClient(config);
+    }
+    return createBoxLiteRestClient(config);
+}
 export class BoxLiteAdapter {
     name = 'boxlite';
-    capabilities = new Set([
-        'exec.stream',
-        'terminal',
-        'sleep',
-        'snapshot',
-        'port.expose',
-    ]);
+    capabilities;
     client;
     config;
-    /** Track port mappings per box: boxId → Map<guestPort, hostPort> */
+    host;
     portMaps = new Map();
     constructor(config) {
         this.config = config;
-        this.client = createBoxLiteClient(config);
+        this.host = resolveHost(config);
+        this.client = createClient(config);
+        // Local mode: snapshots not supported yet
+        const caps = ['exec.stream', 'terminal', 'sleep', 'port.expose'];
+        if (config.mode !== 'local') {
+            caps.push('snapshot');
+        }
+        this.capabilities = new Set(caps);
     }
     async createSandbox(config) {
         try {
             const box = await this.client.createBox({
                 image: config.image,
-                cpus: config.resources?.cpu,
-                memory_mib: config.resources?.memory,
+                cpu: config.resources?.cpu,
+                memory_mb: config.resources?.memory,
                 env: config.env,
                 auto_remove: false,
             });
-            // Store port mappings if they were specified at creation
             const portMap = new Map();
-            this.portMaps.set(box.box_id, portMap);
-            // Start the box if it was created in configured state
+            this.portMaps.set(box.id, portMap);
             if (box.status === 'configured' || box.status === 'stopped') {
-                await this.client.startBox(box.box_id);
+                await this.client.startBox(box.id);
             }
-            // Wait for box to be running (timeout is in seconds per CreateConfig docs)
             const timeoutSec = config.timeout ?? 30;
             const maxAttempts = Math.max(1, timeoutSec);
             let current = box;
             for (let i = 0; i < maxAttempts; i++) {
-                current = await this.client.getBox(box.box_id);
+                current = await this.client.getBox(box.id);
                 if (current.status === 'running')
                     break;
                 await new Promise(r => setTimeout(r, 1000));
             }
             if (current.status !== 'running') {
-                await this.client.deleteBox(box.box_id, true).catch(() => { });
-                this.portMaps.delete(box.box_id);
+                await this.client.deleteBox(box.id, true).catch(() => { });
+                this.portMaps.delete(box.id);
                 throw new ProviderError('boxlite', new Error(`Sandbox failed to start within ${timeoutSec}s (status: ${current.status})`));
             }
-            return wrapBox(current, this.client, this.config, portMap);
+            return wrapBox(current, this.client, this.host, portMap);
         }
         catch (err) {
             if (err instanceof ProviderError)
@@ -203,7 +200,7 @@ export class BoxLiteAdapter {
         try {
             const box = await this.client.getBox(id);
             const portMap = this.portMaps.get(id) ?? new Map();
-            return wrapBox(box, this.client, this.config, portMap);
+            return wrapBox(box, this.client, this.host, portMap);
         }
         catch (err) {
             if (isNotFound(err))
@@ -215,7 +212,7 @@ export class BoxLiteAdapter {
         try {
             const boxes = await this.client.listBoxes();
             let infos = boxes.map((b) => ({
-                id: b.box_id,
+                id: b.id,
                 state: mapState(b.status),
                 createdAt: b.created_at,
                 image: b.image,
@@ -244,4 +241,8 @@ export class BoxLiteAdapter {
             throw new ProviderError('boxlite', err, id);
         }
     }
+    /** Dispose the adapter and clean up resources (e.g. Python bridge process) */
+    async dispose() {
+        await this.client.dispose?.();
+    }
 }

package/dist/client.d.ts

@@ -1,23 +1,7 @@
-import type { BoxLiteAdapterConfig, BoxLiteBox, BoxLiteCreateParams, BoxLiteExecRequest, BoxLiteSnapshot } from './types.js';
-export declare function createBoxLiteClient(config: BoxLiteAdapterConfig): {
-    createBox(params: BoxLiteCreateParams): Promise<BoxLiteBox>;
-    getBox(boxId: string): Promise<BoxLiteBox>;
-    listBoxes(status?: string, pageSize?: number): Promise<BoxLiteBox[]>;
-    deleteBox(boxId: string, force?: boolean): Promise<void>;
-    startBox(boxId: string): Promise<void>;
-    stopBox(boxId: string): Promise<void>;
-    exec(boxId: string, req: BoxLiteExecRequest): Promise<{
-        stdout: string;
-        stderr: string;
-        exitCode: number;
-    }>;
-    execStream(boxId: string, req: BoxLiteExecRequest): Promise<ReadableStream<Uint8Array>>;
-    uploadFiles(boxId: string, path: string, tarData: Uint8Array): Promise<void>;
-    downloadFiles(boxId: string, path: string): Promise<ReadableStream<Uint8Array>>;
-    createSnapshot(boxId: string, name: string): Promise<BoxLiteSnapshot>;
-    restoreSnapshot(boxId: string, name: string): Promise<void>;
-    listSnapshots(boxId: string): Promise<BoxLiteSnapshot[]>;
-    deleteSnapshot(boxId: string, name: string): Promise<void>;
-};
-export type BoxLiteClient = ReturnType<typeof createBoxLiteClient>;
+import type { BoxLiteClient, BoxLiteRemoteConfig } from './types.js';
+/**
+ * Create a BoxLite REST client for communicating with a BoxRun REST API.
+ * Used in remote mode.
+ */
+export declare function createBoxLiteRestClient(config: BoxLiteRemoteConfig): BoxLiteClient;
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,oBAAoB,EACpB,UAAU,EACV,mBAAmB,EACnB,kBAAkB,EAElB,eAAe,EAEhB,MAAM,YAAY,CAAA;AAEnB,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,oBAAoB;sBA4HpC,mBAAmB,GAAG,OAAO,CAAC,UAAU,CAAC;kBAO7C,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;uBAIvB,MAAM,aAAa,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;qBASnD,MAAM,oBAAkB,OAAO,CAAC,IAAI,CAAC;oBAMtC,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;mBAIvB,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;gBAOlC,MAAM,OACR,kBAAkB,GACtB,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;sBAwBvD,MAAM,OACR,kBAAkB,GACtB,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;uBAuEb,MAAM,QAAQ,MAAM,WAAW,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;yBAkBvD,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;0BAwBzD,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;2BAO9C,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;yBAMtC,MAAM,GAAG,OAAO,CAAC,eAAe,EAAE,CAAC;0BAIlC,MAAM,QAAQ,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;EAMnE;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,CAAC,OAAO,mBAAmB,CAAC,CAAA"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,aAAa,EAIb,mBAAmB,EAGpB,MAAM,YAAY,CAAA;AAEnB;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,mBAAmB,GAAG,aAAa,CAgQlF"}