@sandbank.dev/cloud 0.1.0

package/README.md

@@ -0,0 +1,73 @@
+# @sandbank.dev/cloud
+
+> Sandbank Cloud adapter for [Sandbank](../../README.md) with built-in x402 payment support.
+
+Connect to [Sandbank Cloud](https://sandbank.dev/cloud) — managed bare-metal KVM sandboxes with sub-second start times. Pay per sandbox with USDC via the x402 payment protocol, or use an API token for authenticated access.
+
+## Install
+
+```bash
+pnpm add @sandbank.dev/core @sandbank.dev/cloud
+```
+
+## Usage
+
+### x402 Payment (pay-per-use)
+
+```typescript
+import { createProvider } from '@sandbank.dev/core'
+import { SandbankCloudAdapter } from '@sandbank.dev/cloud'
+
+const provider = createProvider(
+  new SandbankCloudAdapter({
+    walletPrivateKey: process.env.WALLET_PRIVATE_KEY,
+  })
+)
+
+const sandbox = await provider.create({
+  image: 'codebox',
+  resources: { cpu: 2, memory: 1024 },
+  ports: [[0, 7681], [0, 8080]],
+})
+
+const { stdout } = await sandbox.exec('node -e "console.log(42)"')
+console.log(stdout) // 42
+
+await provider.destroy(sandbox.id)
+```
+
+### API Token (authenticated access)
+
+```typescript
+const provider = createProvider(
+  new SandbankCloudAdapter({
+    apiToken: process.env.SANDBANK_API_TOKEN,
+  })
+)
+```
+
+## Configuration
+
+| Option | Description |
+|--------|-------------|
+| `url` | Sandbank Cloud API URL (default: `https://cloud.sandbank.dev`) |
+| `walletPrivateKey` | EVM wallet private key (hex, `0x` prefix) for x402 USDC payments |
+| `apiToken` | Bearer token for authenticated (internal) access — bypasses x402 |
+
+## Capabilities
+
+| Capability | Supported |
+|------------|:---------:|
+| `exec.stream` | ✅ |
+| `port.expose` | ✅ |
+
+## How x402 Payment Works
+
+1. `POST /v1/boxes` returns HTTP 402 with payment requirements
+2. The adapter signs a USDC payment on Base (eip155:8453) using your wallet
+3. The request is retried with the payment signature header
+4. The sandbox is created — $0.02 per sandbox (includes 10 min)
+
+## License
+
+MIT

package/dist/adapter.d.ts

@@ -0,0 +1,13 @@
+import type { AdapterSandbox, Capability, CreateConfig, ListFilter, SandboxAdapter, SandboxInfo } from '@sandbank.dev/core';
+import type { SandbankCloudConfig } from './types.js';
+export declare class SandbankCloudAdapter implements SandboxAdapter {
+    readonly name = "sandbank-cloud";
+    readonly capabilities: ReadonlySet<Capability>;
+    private readonly api;
+    constructor(config?: SandbankCloudConfig);
+    createSandbox(config: CreateConfig): Promise<AdapterSandbox>;
+    getSandbox(id: string): Promise<AdapterSandbox>;
+    listSandboxes(filter?: ListFilter): Promise<SandboxInfo[]>;
+    destroySandbox(id: string): 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,EAEZ,MAAM,oBAAoB,CAAA;AAG3B,OAAO,KAAK,EAAE,mBAAmB,EAA6B,MAAM,YAAY,CAAA;AAmIhF,qBAAa,oBAAqB,YAAW,cAAc;IACzD,QAAQ,CAAC,IAAI,oBAAmB;IAChC,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC,UAAU,CAAC,CAG5C;IAEF,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAoC;gBAE5C,MAAM,GAAE,mBAAwB;IAItC,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC;IAuB5D,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAU/C,aAAa,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAqB1D,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAQhD"}

package/dist/adapter.js

@@ -0,0 +1,196 @@
+import { SandboxNotFoundError, ProviderError } from '@sandbank.dev/core';
+import { createX402Fetch } from './x402-fetch.js';
+function mapState(status) {
+    switch (status) {
+        case 'running':
+            return 'running';
+        case 'stopped':
+        case 'terminated':
+            return 'stopped';
+        default:
+            return 'error';
+    }
+}
+function isNotFound(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.includes('404') || msg.includes('Not found');
+}
+function wrapBox(box, api) {
+    const portMap = new Map();
+    if (box.ports) {
+        for (const [guest, host] of Object.entries(box.ports)) {
+            portMap.set(parseInt(guest), host);
+        }
+    }
+    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 api.x402Fetch(`/boxes/${box.id}/exec`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    cmd: ['bash', '-c', command],
+                    working_dir: options?.cwd,
+                    timeout_seconds: options?.timeout ? Math.ceil(options.timeout / 1000) : undefined,
+                }),
+            });
+            return {
+                exitCode: result.exit_code,
+                stdout: result.stdout ?? '',
+                stderr: result.stderr ?? '',
+            };
+        },
+        async execStream(command, options) {
+            const result = await api.x402Fetch(`/boxes/${box.id}/exec`, {
+                method: 'POST',
+                body: JSON.stringify({
+                    cmd: ['bash', '-c', command],
+                    working_dir: options?.cwd,
+                    timeout_seconds: options?.timeout ? Math.ceil(options.timeout / 1000) : undefined,
+                }),
+            });
+            const encoder = new TextEncoder();
+            return new ReadableStream({
+                start(controller) {
+                    if (result.stdout)
+                        controller.enqueue(encoder.encode(result.stdout));
+                    if (result.stderr)
+                        controller.enqueue(encoder.encode(result.stderr));
+                    controller.close();
+                },
+            });
+        },
+        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;
+                }
+            }
+            const path = destDir ?? '/';
+            const resp = await api.x402FetchRaw(`/boxes/${box.id}/files?path=${encodeURIComponent(path)}`, {
+                method: 'PUT',
+                headers: { 'Content-Type': 'application/x-tar' },
+                body: data.buffer.slice(data.byteOffset, data.byteOffset + data.byteLength),
+            });
+            if (!resp.ok) {
+                const body = await resp.text();
+                throw new Error(`Upload failed ${resp.status}: ${body}`);
+            }
+        },
+        async downloadArchive(srcDir) {
+            const path = srcDir ?? '/';
+            const resp = await api.x402FetchRaw(`/boxes/${box.id}/files?path=${encodeURIComponent(path)}`, {
+                headers: { 'Accept': 'application/x-tar' },
+            });
+            if (!resp.ok) {
+                const body = await resp.text();
+                throw new Error(`Download failed ${resp.status}: ${body}`);
+            }
+            if (!resp.body)
+                throw new Error('No response body');
+            return resp.body;
+        },
+        async exposePort(port) {
+            const hostPort = portMap.get(port);
+            if (hostPort) {
+                try {
+                    const host = new URL(api.baseUrl).hostname;
+                    return { url: `http://${host}:${hostPort}` };
+                }
+                catch { }
+            }
+            // Fallback to proxy URL
+            return { url: `${api.baseUrl}/v1/boxes/${box.id}/proxy/${port}/` };
+        },
+    };
+}
+export class SandbankCloudAdapter {
+    name = 'sandbank-cloud';
+    capabilities = new Set([
+        'exec.stream',
+        'port.expose',
+    ]);
+    api;
+    constructor(config = {}) {
+        this.api = createX402Fetch(config);
+    }
+    async createSandbox(config) {
+        try {
+            const body = {
+                image: config.image ?? 'codebox',
+                cpu: config.resources?.cpu,
+                memory_mb: config.resources?.memory,
+            };
+            if (config.ports) {
+                body.ports = config.ports;
+            }
+            const box = await this.api.x402Fetch('/boxes', {
+                method: 'POST',
+                body: JSON.stringify(body),
+            });
+            return wrapBox(box, this.api);
+        }
+        catch (err) {
+            if (err instanceof ProviderError)
+                throw err;
+            throw new ProviderError('sandbank-cloud', err);
+        }
+    }
+    async getSandbox(id) {
+        try {
+            const box = await this.api.x402Fetch(`/boxes/${id}`);
+            return wrapBox(box, this.api);
+        }
+        catch (err) {
+            if (isNotFound(err))
+                throw new SandboxNotFoundError('sandbank-cloud', id);
+            throw new ProviderError('sandbank-cloud', err, id);
+        }
+    }
+    async listSandboxes(filter) {
+        try {
+            const qs = filter?.state ? `?status=${filter.state}` : '';
+            const boxes = await this.api.x402Fetch(`/boxes${qs}`);
+            let infos = boxes.map((b) => ({
+                id: b.id,
+                state: mapState(b.status),
+                createdAt: b.created_at,
+                image: b.image,
+            }));
+            if (filter?.limit) {
+                infos = infos.slice(0, filter.limit);
+            }
+            return infos;
+        }
+        catch (err) {
+            throw new ProviderError('sandbank-cloud', err);
+        }
+    }
+    async destroySandbox(id) {
+        try {
+            await this.api.x402Fetch(`/boxes/${id}`, { method: 'DELETE' });
+        }
+        catch (err) {
+            if (isNotFound(err))
+                return;
+            throw new ProviderError('sandbank-cloud', err, id);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { SandbankCloudAdapter } from './adapter.js';
+export type { SandbankCloudConfig, CloudBox, CloudExecResult } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAA;AACnD,YAAY,EAAE,mBAAmB,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,2 @@
+// @sandbank.dev/cloud — Sandbank Cloud adapter with x402 payment support
+export { SandbankCloudAdapter } from './adapter.js';

package/dist/types.d.ts

@@ -0,0 +1,38 @@
+/** Configuration for SandbankCloudAdapter */
+export interface SandbankCloudConfig {
+    /** Sandbank Cloud API URL (default: 'https://cloud.sandbank.dev') */
+    url?: string;
+    /**
+     * EVM wallet private key for x402 payments (hex string with 0x prefix).
+     * Required for x402 payment — if omitted, paid endpoints will fail with 402.
+     */
+    walletPrivateKey?: string;
+    /**
+     * Bearer API token for authenticated (internal) access.
+     * When set, x402 payment is bypassed.
+     */
+    apiToken?: string;
+}
+/** Sandbank Cloud box response */
+export interface CloudBox {
+    id: string;
+    name: string | null;
+    status: string;
+    created_at: string;
+    image: string;
+    cpu: number;
+    memory_mb: number;
+    disk_size_gb?: number;
+    ports?: Record<string, number>;
+}
+/** Exec response */
+export interface CloudExecResult {
+    id: string;
+    box_id: string;
+    cmd: string[];
+    status: string;
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,6CAA6C;AAC7C,MAAM,WAAW,mBAAmB;IAClC,qEAAqE;IACrE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,kCAAkC;AAClC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC/B;AAED,oBAAoB;AACpB,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,EAAE,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;CACf"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/x402-fetch.d.ts

@@ -0,0 +1,12 @@
+import type { SandbankCloudConfig } from './types.js';
+/**
+ * Create a fetch wrapper that handles x402 payment automatically.
+ * On HTTP 402 responses, it parses payment requirements, signs with the wallet,
+ * and retries the request with the payment header.
+ */
+export declare function createX402Fetch(config: SandbankCloudConfig): {
+    x402Fetch: <T>(path: string, options?: RequestInit) => Promise<T>;
+    x402FetchRaw: (path: string, options?: RequestInit) => Promise<Response>;
+    baseUrl: string;
+};
+//# sourceMappingURL=x402-fetch.d.ts.map

package/dist/x402-fetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-fetch.d.ts","sourceRoot":"","sources":["../src/x402-fetch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,mBAAmB;gBAgBhC,CAAC,QAClB,MAAM,YACH,WAAW,KACnB,OAAO,CAAC,CAAC,CAAC;yBAkEL,MAAM,YACH,WAAW,KACnB,OAAO,CAAC,QAAQ,CAAC;;EAYrB"}

package/dist/x402-fetch.js

@@ -0,0 +1,85 @@
+import { x402Client, x402HTTPClient } from '@x402/core/client';
+import { registerExactEvmScheme } from '@x402/evm/exact/client';
+import { toClientEvmSigner } from '@x402/evm';
+import { createPublicClient, http } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { base } from 'viem/chains';
+/**
+ * Create a fetch wrapper that handles x402 payment automatically.
+ * On HTTP 402 responses, it parses payment requirements, signs with the wallet,
+ * and retries the request with the payment header.
+ */
+export function createX402Fetch(config) {
+    const baseUrl = (config.url || 'https://cloud.sandbank.dev').replace(/\/$/, '');
+    const apiToken = config.apiToken;
+    // Setup x402 HTTP client if wallet is provided
+    let httpClient = null;
+    if (config.walletPrivateKey) {
+        const account = privateKeyToAccount(config.walletPrivateKey);
+        const publicClient = createPublicClient({ chain: base, transport: http() });
+        const signer = toClientEvmSigner(account, publicClient);
+        const client = new x402Client();
+        registerExactEvmScheme(client, { signer });
+        httpClient = new x402HTTPClient(client);
+    }
+    async function x402Fetch(path, options = {}) {
+        const url = `${baseUrl}/v1${path}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            ...options.headers,
+        };
+        if (apiToken) {
+            headers['Authorization'] = `Bearer ${apiToken}`;
+        }
+        const response = await fetch(url, { ...options, headers });
+        // Handle x402 payment
+        if (response.status === 402 && httpClient) {
+            const paymentRequired = httpClient.getPaymentRequiredResponse((name) => response.headers.get(name), await response.clone().json().catch(() => undefined));
+            // Try hooks first (e.g., cached tokens)
+            const hookHeaders = await httpClient.handlePaymentRequired(paymentRequired);
+            if (hookHeaders) {
+                const retryResp = await fetch(url, {
+                    ...options,
+                    headers: { ...headers, ...hookHeaders },
+                });
+                if (retryResp.ok) {
+                    const text = await retryResp.text();
+                    return text ? JSON.parse(text) : {};
+                }
+            }
+            // Create payment payload and retry
+            const paymentPayload = await httpClient.createPaymentPayload(paymentRequired);
+            const paymentHeaders = httpClient.encodePaymentSignatureHeader(paymentPayload);
+            const paidResponse = await fetch(url, {
+                ...options,
+                headers: { ...headers, ...paymentHeaders },
+            });
+            if (!paidResponse.ok) {
+                const body = await paidResponse.text();
+                throw new Error(`Sandbank Cloud API error ${paidResponse.status}: ${body}`);
+            }
+            const text = await paidResponse.text();
+            return text ? JSON.parse(text) : {};
+        }
+        if (response.status === 402) {
+            throw new Error('Sandbank Cloud: HTTP 402 Payment Required — provide walletPrivateKey for x402 payment or apiToken for authenticated access');
+        }
+        if (!response.ok) {
+            const body = await response.text();
+            throw new Error(`Sandbank Cloud API error ${response.status}: ${body}`);
+        }
+        const text = await response.text();
+        return text ? JSON.parse(text) : {};
+    }
+    async function x402FetchRaw(path, options = {}) {
+        const url = `${baseUrl}/v1${path}`;
+        const headers = {
+            ...options.headers,
+        };
+        if (apiToken) {
+            headers['Authorization'] = `Bearer ${apiToken}`;
+        }
+        return fetch(url, { ...options, headers });
+    }
+    return { x402Fetch, x402FetchRaw, baseUrl };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@sandbank.dev/cloud",
+  "version": "0.1.0",
+  "description": "Sandbank Cloud adapter with x402 payment support",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://sandbank.dev/cloud",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/chekusu/sandbank.git",
+    "directory": "packages/cloud"
+  },
+  "keywords": [
+    "sandbox",
+    "ai-agent",
+    "sandbank-cloud",
+    "bare-metal",
+    "kvm",
+    "x402",
+    "usdc"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  },
+  "dependencies": {
+    "@sandbank.dev/core": "workspace:*",
+    "@x402/core": "^2.6.0",
+    "@x402/evm": "^2.6.0",
+    "viem": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.7.3"
+  }
+}