@sandbank.dev/boxlite 0.2.0 → 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;AAwKlE,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,40 +74,37 @@ 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 ttydBase = 'https://github.com/tsl0922/ttyd/releases/download/1.7.7/ttyd';
-            // 1. Ensure ttyd is available
-            const check = await client.exec(box.box_id, { command: 'which', args: ['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',
+                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`
@@ -116,23 +112,17 @@ function wrapBox(box, client, config, portMappings) {
                             + ` || { 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,
@@ -145,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)
@@ -205,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))
@@ -217,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,
@@ -246,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;sBA0HpC,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"}

package/dist/client.js

@@ -1,4 +1,8 @@
-export function createBoxLiteClient(config) {
+/**
+ * Create a BoxLite REST client for communicating with a BoxRun REST API.
+ * Used in remote mode.
+ */
+export function createBoxLiteRestClient(config) {
     const { apiUrl } = config;
     const prefix = config.prefix ?? '';
     const baseUrl = apiUrl.replace(/\/$/, '') + '/v1';
@@ -6,13 +10,10 @@ export function createBoxLiteClient(config) {
     let token = config.apiToken ?? '';
     let tokenExpiresAt = 0;
     async function ensureToken() {
-        // If a static token was provided, always use it
         if (config.apiToken)
             return config.apiToken;
-        // No auth configured — run without authentication
         if (!config.clientId || !config.clientSecret)
             return '';
-        // If we have a valid cached token, use it
         if (token && Date.now() < tokenExpiresAt)
             return token;
         const response = await fetch(`${baseUrl}/oauth/tokens`, {
@@ -30,7 +31,6 @@ export function createBoxLiteClient(config) {
         }
         const data = await response.json();
         token = data.access_token;
-        // Refresh 60s before expiry
         tokenExpiresAt = Date.now() + (data.expires_in - 60) * 1000;
         return token;
     }
@@ -56,57 +56,7 @@ export function createBoxLiteClient(config) {
             return {};
         return JSON.parse(text);
     }
-    /**
-     * Parse SSE data field — may be JSON `{"data":"<base64>"}` or raw base64.
-     */
-    function decodeSSEData(raw) {
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed.data)
-                return atob(parsed.data);
-        }
-        catch {
-            // Fall through to raw base64
-        }
-        return atob(raw);
-    }
-    /**
-     * Consume an SSE stream from BoxLite exec output.
-     * SSE events: stdout/stderr data is base64-encoded, exit event has exit_code.
-     */
-    function parseSSE(text) {
-        let stdout = '';
-        let stderr = '';
-        let exitCode = 0;
-        const lines = text.split('\n');
-        let currentEvent = '';
-        for (const line of lines) {
-            if (line.startsWith('event:')) {
-                currentEvent = line.slice(6).trim();
-            }
-            else if (line.startsWith('data:')) {
-                const data = line.slice(5).trim();
-                if (currentEvent === 'stdout') {
-                    stdout += decodeSSEData(data);
-                }
-                else if (currentEvent === 'stderr') {
-                    stderr += decodeSSEData(data);
-                }
-                else if (currentEvent === 'exit') {
-                    try {
-                        const parsed = JSON.parse(data);
-                        exitCode = parsed.exit_code;
-                    }
-                    catch {
-                        exitCode = parseInt(data, 10) || 0;
-                    }
-                }
-            }
-        }
-        return { stdout, stderr, exitCode };
-    }
     return {
-        // --- Box lifecycle ---
         async createBox(params) {
             return request('/boxes', {
                 method: 'POST',
@@ -124,6 +74,8 @@ export function createBoxLiteClient(config) {
                 params.set('page_size', String(pageSize));
             const qs = params.toString();
             const data = await request(`/boxes${qs ? `?${qs}` : ''}`);
+            if (Array.isArray(data))
+                return data;
             return data.boxes ?? [];
         },
         async deleteBox(boxId, force = false) {
@@ -137,81 +89,78 @@ export function createBoxLiteClient(config) {
         async stopBox(boxId) {
             await request(`/boxes/${boxId}/stop`, { method: 'POST' });
         },
-        // --- Exec ---
         async exec(boxId, req) {
-            // 1. POST /exec to start execution
             const execution = await request(`/boxes/${boxId}/exec`, {
                 method: 'POST',
                 body: JSON.stringify(req),
             });
-            // 2. GET /executions/{id}/output — SSE stream
-            const response = await request(`/boxes/${boxId}/executions/${execution.execution_id}/output`, { headers: { 'Accept': 'text/event-stream' } }, true);
-            if (!response.ok) {
-                const body = await response.text();
-                throw new Error(`BoxLite API error ${response.status}: ${body}`);
+            if (execution.exit_code !== null && execution.exit_code !== undefined) {
+                return {
+                    stdout: execution.stdout ?? '',
+                    stderr: execution.stderr ?? '',
+                    exitCode: execution.exit_code,
+                };
             }
-            const sseText = await response.text();
-            return parseSSE(sseText);
+            const timeoutMs = (req.timeout_seconds ?? 300) * 1000;
+            const startTime = Date.now();
+            let pollInterval = 100;
+            while (Date.now() - startTime < timeoutMs) {
+                await new Promise(r => setTimeout(r, pollInterval));
+                pollInterval = Math.min(pollInterval * 2, 2000);
+                const result = await request(`/boxes/${boxId}/executions/${execution.id}`);
+                if (result.exit_code !== null && result.exit_code !== undefined) {
+                    return {
+                        stdout: result.stdout ?? '',
+                        stderr: result.stderr ?? '',
+                        exitCode: result.exit_code,
+                    };
+                }
+            }
+            throw new Error('BoxLite exec timed out waiting for completion');
         },
         async execStream(boxId, req) {
-            // 1. POST /exec to start execution
             const execution = await request(`/boxes/${boxId}/exec`, {
                 method: 'POST',
                 body: JSON.stringify(req),
             });
-            // 2. GET /executions/{id}/output — return raw SSE stream
-            const response = await request(`/boxes/${boxId}/executions/${execution.execution_id}/output`, { headers: { 'Accept': 'text/event-stream' } }, true);
-            if (!response.ok) {
-                const body = await response.text();
-                throw new Error(`BoxLite API error ${response.status}: ${body}`);
-            }
-            if (!response.body) {
-                throw new Error('BoxLite exec stream: no response body');
-            }
-            // Transform SSE events into decoded data chunks
-            const decoder = new TextDecoder();
-            let buffer = '';
-            return response.body.pipeThrough(new TransformStream({
-                transform(chunk, controller) {
-                    buffer += decoder.decode(chunk, { stream: true });
-                    const lines = buffer.split('\n');
-                    buffer = lines.pop() ?? '';
-                    let currentEvent = '';
-                    for (const line of lines) {
-                        if (line.startsWith('event:')) {
-                            currentEvent = line.slice(6).trim();
-                        }
-                        else if (line.startsWith('data:')) {
-                            const data = line.slice(5).trim();
-                            if (currentEvent === 'stdout' || currentEvent === 'stderr') {
-                                const decoded = decodeSSEData(data);
-                                controller.enqueue(new TextEncoder().encode(decoded));
-                            }
-                        }
+            const encoder = new TextEncoder();
+            const self = { request };
+            return new ReadableStream({
+                async start(controller) {
+                    if (execution.exit_code !== null && execution.exit_code !== undefined) {
+                        if (execution.stdout)
+                            controller.enqueue(encoder.encode(execution.stdout));
+                        if (execution.stderr)
+                            controller.enqueue(encoder.encode(execution.stderr));
+                        controller.close();
+                        return;
                     }
-                },
-                flush(controller) {
-                    if (buffer) {
-                        const lines = buffer.split('\n');
-                        let currentEvent = '';
-                        for (const line of lines) {
-                            if (line.startsWith('event:')) {
-                                currentEvent = line.slice(6).trim();
-                            }
-                            else if (line.startsWith('data:')) {
-                                const data = line.slice(5).trim();
-                                if (currentEvent === 'stdout' || currentEvent === 'stderr') {
-                                    const decoded = decodeSSEData(data);
-                                    controller.enqueue(new TextEncoder().encode(decoded));
-                                }
+                    const timeoutMs = (req.timeout_seconds ?? 300) * 1000;
+                    const startTime = Date.now();
+                    let pollInterval = 100;
+                    while (Date.now() - startTime < timeoutMs) {
+                        await new Promise(r => setTimeout(r, pollInterval));
+                        pollInterval = Math.min(pollInterval * 2, 2000);
+                        try {
+                            const result = await self.request(`/boxes/${boxId}/executions/${execution.id}`);
+                            if (result.exit_code !== null && result.exit_code !== undefined) {
+                                if (result.stdout)
+                                    controller.enqueue(encoder.encode(result.stdout));
+                                if (result.stderr)
+                                    controller.enqueue(encoder.encode(result.stderr));
+                                controller.close();
+                                return;
                             }
                         }
+                        catch (err) {
+                            controller.error(err);
+                            return;
+                        }
                     }
-                    controller.terminate();
+                    controller.error(new Error('BoxLite exec stream timed out'));
                 },
-            }));
+            });
         },
-        // --- Files (native tar API) ---
         async uploadFiles(boxId, path, tarData) {
             const bearerToken = await ensureToken();
             const url = `${baseUrl}${prefix ? `/${prefix}` : ''}/boxes/${boxId}/files?path=${encodeURIComponent(path)}`;
@@ -246,7 +195,6 @@ export function createBoxLiteClient(config) {
             }
             return response.body;
         },
-        // --- Snapshots ---
         async createSnapshot(boxId, name) {
             return request(`/boxes/${boxId}/snapshots`, {
                 method: 'POST',