@volter/browser-sandboxes 0.1.3

package/dist/manager.d.ts

@@ -0,0 +1,90 @@
+import { RemoteRuntime, type RemoteHealth } from "./client.js";
+export interface SandboxLimits {
+    cpus?: number;
+    memoryBytes?: number;
+    pids?: number;
+}
+/** A template is an image plus an optional workspace archive in the kernel's portable format. */
+export interface SandboxTemplate {
+    image?: string;
+    workspace?: Uint8Array;
+}
+export interface ProviderStartSpec {
+    id: string;
+    token: string;
+    image?: string;
+    limits?: SandboxLimits;
+    volume?: string;
+}
+/** What a provider returns for a started sandbox; `name` is the provider's own handle. */
+export interface ProviderStarted {
+    name: string;
+    url: string;
+}
+/** The four calls every backend implements, plus optional volume and shutdown hooks. */
+export interface SandboxProvider {
+    start(spec: ProviderStartSpec): Promise<ProviderStarted> | ProviderStarted;
+    pause(started: ProviderStarted): Promise<void> | void;
+    /** May return a new address when the backend brings the sandbox back elsewhere. */
+    resume(started: ProviderStarted): Promise<{
+        url?: string;
+    } | void> | {
+        url?: string;
+    } | void;
+    stop(started: ProviderStarted): Promise<void> | void;
+    running(): Promise<Set<string>> | Set<string>;
+    removeVolume?(volume: string): Promise<void> | void;
+    close?(): void;
+}
+export interface Sandbox {
+    readonly id: string;
+    readonly token: string;
+    readonly url: string;
+    readonly runtime: RemoteRuntime;
+    readonly idleTimeoutMs: number;
+    readonly createdAt: number;
+    readonly template: SandboxTemplate;
+    readonly limits: SandboxLimits | undefined;
+    readonly volume: string | undefined;
+    state: "running" | "paused" | "killed";
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    kill(): Promise<void>;
+    health(): Promise<RemoteHealth>;
+}
+export interface SandboxManagerOptions {
+    provider: SandboxProvider;
+    idleTimeoutMs?: number;
+    reapEveryMs?: number;
+    /** How long a new or resumed sandbox may take to answer; a loaded host needs more. */
+    healthTimeoutMs?: number;
+}
+export interface CreateSandboxOptions {
+    idleTimeoutMs?: number;
+    template?: SandboxTemplate;
+    limits?: SandboxLimits;
+    volume?: string;
+}
+/** One agent is one sandbox; the manager creates them through a provider and reaps idle ones. */
+export declare class SandboxManager {
+    readonly idleTimeoutMs: number;
+    readonly healthTimeoutMs: number;
+    private readonly provider;
+    private readonly sandboxes;
+    private readonly reaper;
+    constructor({ provider, idleTimeoutMs, reapEveryMs, healthTimeoutMs }: SandboxManagerOptions);
+    create({ idleTimeoutMs, template, limits, volume }?: CreateSandboxOptions): Promise<Sandbox>;
+    /** A new sandbox seeded with a running sandbox's workspace: "fork this artifact". */
+    fork(id: string, options?: Omit<CreateSandboxOptions, "template">): Promise<Sandbox>;
+    get(id: string): Sandbox | undefined;
+    list(): Array<{
+        id: string;
+        state: Sandbox["state"];
+        createdAt: number;
+        url: string;
+    }>;
+    /** Kills running sandboxes whose agent reports no activity within their idle timeout. */
+    reap(): Promise<void>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=manager.d.ts.map

package/dist/manager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.d.ts","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"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"}

package/dist/manager.js

@@ -0,0 +1,113 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { RemoteRuntime } from "./client.js";
+/** One agent is one sandbox; the manager creates them through a provider and reaps idle ones. */
+export class SandboxManager {
+    idleTimeoutMs;
+    healthTimeoutMs;
+    provider;
+    sandboxes = new Map();
+    reaper;
+    constructor({ provider, idleTimeoutMs = 10 * 60_000, reapEveryMs = 500, healthTimeoutMs = 30_000 }) {
+        this.provider = provider;
+        this.idleTimeoutMs = idleTimeoutMs;
+        this.healthTimeoutMs = healthTimeoutMs;
+        this.reaper = setInterval(() => { void this.reap(); }, reapEveryMs);
+        this.reaper.unref();
+    }
+    async create({ idleTimeoutMs = this.idleTimeoutMs, template = {}, limits, volume } = {}) {
+        const id = randomUUID();
+        const token = randomBytes(24).toString("hex");
+        const started = await this.provider.start({
+            id, token,
+            ...(template.image ? { image: template.image } : {}),
+            ...(limits ? { limits } : {}),
+            ...(volume ? { volume } : {}),
+        });
+        const connect = async (url) => {
+            const candidate = new RemoteRuntime(url, token);
+            const deadline = Date.now() + this.healthTimeoutMs;
+            while (Date.now() < deadline) {
+                try {
+                    await candidate.connect();
+                    return candidate;
+                }
+                catch {
+                    await new Promise((r) => setTimeout(r, 250));
+                }
+            }
+            candidate.close();
+            return undefined;
+        };
+        let runtime = await connect(started.url);
+        if (!runtime) {
+            await this.provider.stop(started);
+            throw new Error(`Sandbox ${id} did not become healthy.`);
+        }
+        if (template.workspace)
+            await runtime.files.import(template.workspace, { root: "/workspace", replace: true });
+        let url = started.url;
+        const manager = this;
+        const sandbox = {
+            id, token, idleTimeoutMs, createdAt: Date.now(), state: "running",
+            template, limits, volume,
+            get url() { return url; },
+            get runtime() { return runtime; },
+            async pause() { await manager.provider.pause(started); sandbox.state = "paused"; },
+            // A provider may bring the sandbox back at a new address; the client follows it.
+            async resume() {
+                const next = await manager.provider.resume(started);
+                if (next && next.url && next.url !== url) {
+                    runtime?.close();
+                    url = next.url;
+                    runtime = await connect(url);
+                    if (!runtime)
+                        throw new Error(`Sandbox ${id} did not come back after resume.`);
+                }
+                sandbox.state = "running";
+            },
+            async kill() { runtime?.close(); await manager.provider.stop(started); sandbox.state = "killed"; manager.sandboxes.delete(id); },
+            async health() {
+                if (!runtime)
+                    throw new Error(`Sandbox ${id} has no client.`);
+                return runtime.health();
+            },
+        };
+        this.sandboxes.set(id, sandbox);
+        return sandbox;
+    }
+    /** A new sandbox seeded with a running sandbox's workspace: "fork this artifact". */
+    async fork(id, options = {}) {
+        const source = this.sandboxes.get(id);
+        if (!source)
+            throw new Error(`Unknown sandbox ${id}.`);
+        const archive = await source.runtime.files.export("/workspace", "zip");
+        return this.create({ ...options, template: { ...source.template, workspace: archive.bytes } });
+    }
+    get(id) { return this.sandboxes.get(id); }
+    list() {
+        return [...this.sandboxes.values()].map(({ id, state, createdAt, url }) => ({ id, state, createdAt, url }));
+    }
+    /** Kills running sandboxes whose agent reports no activity within their idle timeout. */
+    async reap() {
+        for (const sandbox of [...this.sandboxes.values()]) {
+            if (sandbox.state !== "running")
+                continue;
+            let health;
+            try {
+                health = await sandbox.health();
+            }
+            catch {
+                continue;
+            }
+            if (health.liveProcesses === 0 && Date.now() - health.lastActivityAt > sandbox.idleTimeoutMs)
+                await sandbox.kill();
+        }
+    }
+    async close() {
+        clearInterval(this.reaper);
+        for (const sandbox of [...this.sandboxes.values()])
+            await sandbox.kill();
+        this.provider.close?.();
+    }
+}
+//# sourceMappingURL=manager.js.map

package/dist/manager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manager.js","sourceRoot":"","sources":["../src/manager.ts"],"names":[],"mappings":"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"}

package/dist/mcp.d.ts

@@ -0,0 +1,12 @@
+import type { Readable, Writable } from "node:stream";
+import type { SandboxManager } from "./manager.js";
+export interface McpOptions {
+    manager: SandboxManager;
+    input?: Readable;
+    output?: Writable;
+    serverName?: string;
+    serverVersion?: string;
+}
+/** Serves MCP over the given streams (stdio by default) until the input closes. Resolves when closed. */
+export declare function serveMcp({ manager, input, output, serverName, serverVersion }: McpOptions): Promise<void>;
+//# sourceMappingURL=mcp.d.ts.map

package/dist/mcp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,cAAc,CAAC;IACxB,KAAK,CAAC,EAAE,QAAQ,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAWD,yGAAyG;AACzG,wBAAgB,QAAQ,CAAC,EAAE,OAAO,EAAE,KAAqB,EAAE,MAAuB,EAAE,UAA0C,EAAE,aAAuB,EAAE,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAmHpL"}

package/dist/mcp.js

@@ -0,0 +1,142 @@
+// An MCP server over the sandbox manager: any agent tool that speaks the
+// Model Context Protocol over stdio can open a sandbox, run commands, read and
+// write files, and reach guest ports. Newline-delimited JSON-RPC 2.0; no SDK.
+import { createInterface } from "node:readline";
+const text = (value) => ({ content: [{ type: "text", text: typeof value === "string" ? value : JSON.stringify(value, null, 2) }] });
+const withTimeout = (promise, ms) => Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new Error(`timeout after ${ms}ms`)), ms))]);
+const str = (value, fallback) => (typeof value === "string" ? value : fallback);
+const num = (value, fallback) => (typeof value === "number" ? value : fallback);
+/** Serves MCP over the given streams (stdio by default) until the input closes. Resolves when closed. */
+export function serveMcp({ manager, input = process.stdin, output = process.stdout, serverName = "browser-substrate-sandboxes", serverVersion = "0.1.2" }) {
+    const processes = new Map();
+    const sandbox = (id) => {
+        const found = manager.get(String(id));
+        if (!found)
+            throw new Error(`Unknown sandbox ${String(id)}.`);
+        return found;
+    };
+    const tools = {
+        sandbox_create: {
+            description: "Create a sandbox: an isolated Linux guest with the substrate kernel and agent. Returns its id.",
+            inputSchema: { type: "object", properties: { volume: { type: "string", description: "Named volume mounted at /workspace that outlives the sandbox" }, idleTimeoutMs: { type: "number" } } },
+            run: async ({ volume, idleTimeoutMs }) => {
+                const created = await manager.create({ ...(typeof volume === "string" ? { volume } : {}), ...(typeof idleTimeoutMs === "number" ? { idleTimeoutMs } : {}) });
+                return text({ id: created.id, url: created.url, state: created.state });
+            },
+        },
+        sandbox_list: { description: "List sandboxes with their state.", inputSchema: { type: "object", properties: {} }, run: async () => text(manager.list()) },
+        sandbox_kill: {
+            description: "Destroy a sandbox.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" } }, required: ["sandbox"] },
+            run: async ({ sandbox: id }) => { await sandbox(id).kill(); return text({ killed: String(id) }); },
+        },
+        run_command: {
+            description: "Run a shell command in a sandbox and wait for it. Returns stdout, stderr, and the exit code.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, command: { type: "string" }, cwd: { type: "string", default: "/workspace" }, stdin: { type: "string" }, timeoutMs: { type: "number", default: 120000 } }, required: ["sandbox", "command"] },
+            run: async ({ sandbox: id, command, cwd, stdin, timeoutMs }) => {
+                const result = await withTimeout(sandbox(id).runtime.spawn(str(command, ""), { cwd: str(cwd, "/workspace"), ...(typeof stdin === "string" ? { stdin } : {}) }), num(timeoutMs, 120_000));
+                return { ...text({ stdout: result.stdout, stderr: result.stderr, exitCode: result.exitCode }), isError: result.exitCode !== 0 };
+            },
+        },
+        start_process: {
+            description: "Start a long-running command in a sandbox, such as a dev server, and return its pid.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, command: { type: "string" }, cwd: { type: "string", default: "/workspace" } }, required: ["sandbox", "command"] },
+            run: async ({ sandbox: id, command, cwd }) => {
+                const handle = await sandbox(id).runtime.start(str(command, ""), { cwd: str(cwd, "/workspace") });
+                processes.set(`${String(id)}:${handle.pid}`, handle);
+                handle.result.catch(() => undefined);
+                return text({ pid: handle.pid });
+            },
+        },
+        kill_process: {
+            description: "Kill a process started with start_process.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, pid: { type: "number" } }, required: ["sandbox", "pid"] },
+            run: async ({ sandbox: id, pid }) => {
+                const handle = processes.get(`${String(id)}:${String(pid)}`);
+                if (!handle)
+                    throw new Error(`Unknown process ${String(pid)} in sandbox ${String(id)}.`);
+                handle.kill();
+                const result = await withTimeout(handle.result, 15_000);
+                processes.delete(`${String(id)}:${String(pid)}`);
+                return text({ exitCode: result.exitCode });
+            },
+        },
+        read_file: {
+            description: "Read a file from a sandbox as text.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, path: { type: "string" } }, required: ["sandbox", "path"] },
+            run: async ({ sandbox: id, path }) => text(await sandbox(id).runtime.files.readText(str(path, "/"))),
+        },
+        write_file: {
+            description: "Write text to a file in a sandbox, creating parent directories.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, path: { type: "string" }, content: { type: "string" } }, required: ["sandbox", "path", "content"] },
+            run: async ({ sandbox: id, path, content }) => {
+                const body = str(content, "");
+                await sandbox(id).runtime.files.write(str(path, "/"), body);
+                return text({ wrote: str(path, "/"), bytes: new TextEncoder().encode(body).byteLength });
+            },
+        },
+        list_files: {
+            description: "List a directory in a sandbox.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, path: { type: "string", default: "/workspace" } }, required: ["sandbox"] },
+            run: async ({ sandbox: id, path }) => text(await sandbox(id).runtime.files.list(str(path, "/workspace"))),
+        },
+        list_ports: {
+            description: "List ports that processes in a sandbox are listening on.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" } }, required: ["sandbox"] },
+            run: async ({ sandbox: id }) => text(await sandbox(id).runtime.ports()),
+        },
+        http_request: {
+            description: "Send an HTTP request to a port a sandbox process is listening on.",
+            inputSchema: { type: "object", properties: { sandbox: { type: "string" }, port: { type: "number" }, path: { type: "string", default: "/" }, method: { type: "string", default: "GET" }, body: { type: "string" } }, required: ["sandbox", "port"] },
+            run: async ({ sandbox: id, port, path, method, body }) => {
+                const response = await sandbox(id).runtime.request(num(port, 0), str(path, "/"), { method: str(method, "GET"), ...(typeof body === "string" ? { body } : {}) });
+                return text({ status: response.status, contentType: response.headers.get("content-type"), body: await response.text() });
+            },
+        },
+    };
+    const send = (message) => { output.write(`${JSON.stringify(message)}\n`); };
+    const respond = (id, result) => send({ jsonrpc: "2.0", id, result });
+    const fail = (id, code, message) => send({ jsonrpc: "2.0", id, error: { code, message } });
+    const handle = async (message) => {
+        const { id, method, params } = message;
+        if (method === "initialize")
+            return respond(id, { protocolVersion: "2025-06-18", capabilities: { tools: {} }, serverInfo: { name: serverName, version: serverVersion } });
+        if (method === "notifications/initialized" || method === "notifications/cancelled")
+            return;
+        if (method === "ping")
+            return respond(id, {});
+        if (method === "tools/list")
+            return respond(id, { tools: Object.entries(tools).map(([name, tool]) => ({ name, description: tool.description, inputSchema: tool.inputSchema })) });
+        if (method === "tools/call") {
+            const tool = params?.name ? tools[params.name] : undefined;
+            if (!tool)
+                return fail(id, -32602, `Unknown tool ${String(params?.name)}`);
+            try {
+                return respond(id, await tool.run(params?.arguments ?? {}));
+            }
+            catch (cause) {
+                return respond(id, { content: [{ type: "text", text: cause instanceof Error ? cause.message : String(cause) }], isError: true });
+            }
+        }
+        if (id !== undefined)
+            fail(id, -32601, `Method not found: ${String(method)}`);
+    };
+    return new Promise((resolve) => {
+        const lines = createInterface({ input });
+        lines.on("line", (line) => {
+            if (!line.trim())
+                return;
+            let message;
+            try {
+                message = JSON.parse(line);
+            }
+            catch {
+                fail(null, -32700, "Parse error");
+                return;
+            }
+            void handle(message);
+        });
+        lines.on("close", () => resolve());
+    });
+}
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":"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"}

package/dist/providers.d.ts

@@ -0,0 +1,8 @@
+import type { SandboxProvider } from "./manager.js";
+/**
+ * The provider named by the environment: SUBSTRATE_PROVIDER "fly" or "docker"
+ * (default). SUBSTRATE_IMAGE names the guest image; SUBSTRATE_REPO binds a
+ * repository checkout in and runs the agent from its built package.
+ */
+export declare function providerFromEnvironment(env?: NodeJS.ProcessEnv): SandboxProvider;
+//# sourceMappingURL=providers.d.ts.map

package/dist/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAEpD;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,CAM7F"}

package/dist/providers.js

@@ -0,0 +1,17 @@
+import { resolve } from "node:path";
+import { DockerProvider } from "./docker-provider.js";
+import { FlyProvider } from "./fly-provider.js";
+/**
+ * The provider named by the environment: SUBSTRATE_PROVIDER "fly" or "docker"
+ * (default). SUBSTRATE_IMAGE names the guest image; SUBSTRATE_REPO binds a
+ * repository checkout in and runs the agent from its built package.
+ */
+export function providerFromEnvironment(env = process.env) {
+    if (env.SUBSTRATE_PROVIDER === "fly")
+        return new FlyProvider();
+    return new DockerProvider({
+        ...(env.SUBSTRATE_IMAGE ? { image: env.SUBSTRATE_IMAGE } : {}),
+        ...(env.SUBSTRATE_REPO ? { repo: resolve(env.SUBSTRATE_REPO) } : {}),
+    });
+}
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1E,IAAI,GAAG,CAAC,kBAAkB,KAAK,KAAK;QAAE,OAAO,IAAI,WAAW,EAAE,CAAC;IAC/D,OAAO,IAAI,cAAc,CAAC;QACxB,GAAG,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC9D,GAAG,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACrE,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@volter/browser-sandboxes",
+  "version": "0.1.3",
+  "description": "The hosted backend's control-plane side: a remote runtime client with the in-page runtime's method names, a sandbox manager with Docker and Fly Machines providers, a control plane a page can call, and an MCP server",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/browser-substrate.git",
+    "directory": "packages/sandboxes"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client.js": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js"
+    }
+  },
+  "bin": {
+    "browser-substrate-control-plane": "./dist/bin/control-plane.js",
+    "browser-substrate-mcp": "./dist/bin/mcp.js"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@volter/browser-runtime": "^0.1.3"
+  }
+}