@douglas-agent/sandbank-boxlite 0.6.1

package/README.md

@@ -0,0 +1,120 @@
+# @douglas-agent/sandbank-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 @douglas-agent/sandbank-core @douglas-agent/sandbank-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 '@douglas-agent/sandbank-core'
+import { BoxLiteAdapter } from '@douglas-agent/sandbank-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 '@douglas-agent/sandbank-core'
+import { BoxLiteAdapter } from '@douglas-agent/sandbank-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)
+```
+
+### Local OCI rootfs (skip registry pull)
+
+If `image` is an absolute path, it is treated as a local OCI layout directory:
+
+```typescript
+// Export image: skopeo copy docker-daemon:myimage:latest oci:~/.boxlite/myimage-oci:latest
+const sandbox = await provider.create({ image: '/Users/you/.boxlite/myimage-oci' })
+```
+
+### 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

@@ -0,0 +1,19 @@
+import type { AdapterSandbox, Capability, CreateConfig, ListFilter, SandboxAdapter, SandboxInfo } from '@douglas-agent/sandbank-core';
+import type { BoxLiteAdapterConfig, BoxLiteClient } from './types.js';
+export declare class BoxLiteAdapter implements SandboxAdapter {
+    readonly name = "boxlite";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly client;
+    private readonly config;
+    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>;
+    getClient(): BoxLiteClient;
+    /** 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

@@ -0,0 +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,8BAA8B,CAAA;AAIrC,OAAO,KAAK,EAAE,oBAAoB,EAAc,aAAa,EAAwB,MAAM,YAAY,CAAA;AAoKvG,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;IASlC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAmD5D,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,SAAS,IAAI,aAAa;IAI1B,8EAA8E;IACxE,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B"}

package/dist/adapter.js

@@ -0,0 +1,259 @@
+import { SandboxNotFoundError, ProviderError } from '@douglas-agent/sandbank-core';
+import { createBoxLiteRestClient } from './client.js';
+import { createBoxLiteLocalClient } from './local-client.js';
+/** Map BoxLite box status to Sandbank SandboxState */
+function mapState(status) {
+    switch (status) {
+        case 'configured':
+            return 'creating';
+        case 'running':
+            return 'running';
+        case 'stopping':
+        case 'stopped':
+        case 'paused':
+            return 'stopped';
+        default:
+            return 'error';
+    }
+}
+/** Resolve the host used for port exposure and terminal URLs */
+function resolveHost(config) {
+    if (config.mode === 'local')
+        return '127.0.0.1';
+    try {
+        return new URL(config.apiUrl).hostname;
+    }
+    catch {
+        return config.apiUrl;
+    }
+}
+/** Wrap a BoxLite box into an AdapterSandbox */
+function wrapBox(box, client, host, portMappings) {
+    return {
+        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.id, {
+                cmd: ['bash', '-c', command],
+                working_dir: options?.cwd,
+                timeout_seconds: options?.timeout ? Math.ceil(options.timeout / 1000) : undefined,
+            });
+            return {
+                exitCode: result.exitCode,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            };
+        },
+        async execStream(command, options) {
+            return client.execStream(box.id, {
+                cmd: ['bash', '-c', command],
+                working_dir: options?.cwd,
+                timeout_seconds: options?.timeout ? Math.ceil(options.timeout / 1000) : undefined,
+            });
+        },
+        async uploadArchive(archive, destDir) {
+            let data;
+            if (archive instanceof Uint8Array) {
+                data = archive;
+            }
+            else {
+                const reader = archive.getReader();
+                const chunks = [];
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    chunks.push(value);
+                }
+                const totalLength = chunks.reduce((sum, c) => sum + c.length, 0);
+                data = new Uint8Array(totalLength);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    data.set(chunk, offset);
+                    offset += chunk.length;
+                }
+            }
+            await client.uploadFiles(box.id, destDir ?? '/', data);
+        },
+        async downloadArchive(srcDir) {
+            return client.downloadFiles(box.id, srcDir ?? '/');
+        },
+        async sleep() {
+            await client.stopBox(box.id);
+        },
+        async wake() {
+            await client.startBox(box.id);
+        },
+        async createSnapshot(name) {
+            const snapshotName = name ?? `snap-${Date.now()}`;
+            await client.createSnapshot(box.id, snapshotName);
+            return { snapshotId: snapshotName };
+        },
+        async restoreSnapshot(snapshotId) {
+            await client.restoreSnapshot(box.id, snapshotId);
+        },
+        async exposePort(port) {
+            const hostPort = portMappings.get(port) ?? port;
+            return { url: `http://${host}:${hostPort}` };
+        },
+        async startTerminal(options) {
+            const port = 7681;
+            const shell = options?.shell ?? '/bin/bash';
+            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.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.id, {
+                    cmd: ['chmod', '+x', '/usr/local/bin/ttyd'],
+                });
+            }
+            await client.exec(box.id, {
+                cmd: ['bash', '-c', `nohup ttyd -W -p ${port} '${shell.replace(/'/g, "'\\''")}' > /dev/null 2>&1 &`],
+            });
+            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;
+            return {
+                url: `ws://${host}:${hostPort}/ws`,
+                port,
+            };
+        },
+    };
+}
+/** Check if an error is a 404 "not found" */
+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;
+    client;
+    config;
+    host;
+    portMaps = new Map();
+    constructor(config) {
+        this.config = config;
+        this.host = resolveHost(config);
+        this.client = createClient(config);
+        const caps = ['exec.stream', 'terminal', 'sleep', 'port.expose', 'snapshot'];
+        this.capabilities = new Set(caps);
+    }
+    async createSandbox(config) {
+        try {
+            // If image looks like an absolute path, treat it as a local OCI rootfs
+            const image = config.image ?? 'ubuntu:24.04';
+            const isLocalPath = image.startsWith('/');
+            const user = typeof config.user === 'string' ? config.user : config.user?.name;
+            const box = await this.client.createBox({
+                ...(isLocalPath ? { rootfs_path: image } : { image }),
+                cpu: config.resources?.cpu,
+                memory_mb: config.resources?.memory,
+                disk_size_gb: config.resources?.disk,
+                env: config.env,
+                auto_remove: false,
+                ports: config.ports,
+                ...(user ? { user } : {}),
+            });
+            const portMap = new Map();
+            if (config.ports) {
+                for (const [hostPort, guestPort] of config.ports) {
+                    portMap.set(guestPort, hostPort);
+                }
+            }
+            this.portMaps.set(box.id, portMap);
+            if (box.status === 'configured' || box.status === 'stopped') {
+                await this.client.startBox(box.id);
+            }
+            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.id);
+                if (current.status === 'running')
+                    break;
+                await new Promise(r => setTimeout(r, 1000));
+            }
+            if (current.status !== 'running') {
+                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.host, portMap);
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError('boxlite', err);
+        }
+    }
+    async getSandbox(id) {
+        try {
+            const box = await this.client.getBox(id);
+            const portMap = this.portMaps.get(id) ?? new Map();
+            return wrapBox(box, this.client, this.host, portMap);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                throw new SandboxNotFoundError('boxlite', id);
+            throw new ProviderError('boxlite', err, id);
+        }
+    }
+    async listSandboxes(filter) {
+        try {
+            const boxes = await this.client.listBoxes();
+            let infos = boxes.map((b) => ({
+                id: b.id,
+                state: mapState(b.status),
+                createdAt: b.created_at,
+                image: b.image,
+            }));
+            if (filter?.state) {
+                const states = Array.isArray(filter.state) ? filter.state : [filter.state];
+                infos = infos.filter(s => states.includes(s.state));
+            }
+            if (filter?.limit) {
+                infos = infos.slice(0, filter.limit);
+            }
+            return infos;
+        }
+        catch (err) {
+            throw new ProviderError('boxlite', err);
+        }
+    }
+    async destroySandbox(id) {
+        try {
+            await this.client.deleteBox(id, true);
+            this.portMaps.delete(id);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return;
+            throw new ProviderError('boxlite', err, id);
+        }
+    }
+    getClient() {
+        return this.client;
+    }
+    /** Dispose the adapter and clean up resources (e.g. Python bridge process) */
+    async dispose() {
+        await this.client.dispose?.();
+    }
+}

package/dist/client.d.ts

@@ -0,0 +1,7 @@
+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

@@ -0,0 +1 @@
+{"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,CA4VlF"}