@sandboxrouter/sdk 0.0.0-stage → 0.2.0

package/dist/providers/docker.js

@@ -0,0 +1,148 @@
+import { spawn, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { DEFAULT_MEMORY_GB, DEFAULT_VCPU } from "../catalog.js";
+import { ProviderError } from "../types.js";
+import { dirname, shq, toBytes } from "../util.js";
+/**
+ * Local sandboxes in Docker containers, through the `docker` CLI. Free and needs no account, so it
+ * is good for development and tests. A container shares your machine's kernel: it is weaker
+ * isolation than a cloud micro-VM, so don't point untrusted code at it with secrets mounted.
+ * Never chosen automatically; route to it with { provider: "docker" }.
+ */
+export class DockerProvider {
+    bin;
+    id = "docker";
+    available;
+    constructor(bin = process.env.SANDBOXROUTER_DOCKER_BIN ?? "docker") {
+        this.bin = bin;
+    }
+    /** The docker CLI exists and its daemon answers. Cached for the life of the process. */
+    configured() {
+        if (this.available === undefined) {
+            const r = spawnSync(this.bin, ["info", "--format", "{{.ServerVersion}}"], { timeout: 4000, encoding: "utf8" });
+            this.available = r.status === 0 && !!r.stdout.trim();
+        }
+        return this.available;
+    }
+    async create(spec) {
+        const name = `sbr-${randomUUID().slice(0, 12)}`;
+        const lifetime = Math.max(60, Math.round((spec.timeoutMinutes ?? 30) * 60));
+        const args = [
+            "run",
+            "-d",
+            "--rm",
+            "--name",
+            name,
+            "--label",
+            "sandboxrouter=1",
+            "--cpus",
+            String(spec.vcpu ?? DEFAULT_VCPU),
+            "--memory",
+            `${Math.round((spec.memoryGb ?? DEFAULT_MEMORY_GB) * 1024)}m`,
+        ];
+        for (const [k, v] of Object.entries(spec.env ?? {}))
+            args.push("-e", `${k}=${v}`);
+        for (const [k, v] of Object.entries(spec.metadata ?? {}))
+            args.push("--label", `${k}=${v}`);
+        // The container's main process is a timer: it exits at the lifetime and --rm removes it.
+        args.push(spec.image?.docker ?? "python:3.12-slim", "sleep", String(lifetime));
+        const r = await run(this.bin, args);
+        if (r.code !== 0)
+            throw new ProviderError("docker", `docker run failed: ${r.stderr.trim().slice(0, 300)}`);
+        return new DockerBox(this.bin, name);
+    }
+    async connect(nativeId) {
+        const r = await run(this.bin, ["inspect", "-f", "{{.State.Status}}", nativeId]);
+        if (r.code !== 0)
+            throw new ProviderError("docker", `no container ${nativeId}`, 404);
+        if (r.stdout.trim() === "paused")
+            await run(this.bin, ["unpause", nativeId]);
+        return new DockerBox(this.bin, nativeId);
+    }
+}
+class DockerBox {
+    bin;
+    nativeId;
+    constructor(bin, nativeId) {
+        this.bin = bin;
+        this.nativeId = nativeId;
+    }
+    exec(cmd, opts = {}) {
+        const args = ["exec", "-i"];
+        if (opts.cwd)
+            args.push("-w", opts.cwd);
+        for (const [k, v] of Object.entries(opts.env ?? {}))
+            args.push("-e", `${k}=${v}`);
+        args.push(this.nativeId, "sh", "-c", cmd);
+        return run(this.bin, args, { timeoutMs: (opts.timeoutSeconds ?? 60) * 1000, onStdout: opts.onStdout, onStderr: opts.onStderr }).then((r) => {
+            if (r.timedOut)
+                throw new ProviderError("docker", `command timed out after ${opts.timeoutSeconds ?? 60}s`);
+            return { exitCode: r.code ?? -1, stdout: r.stdout, stderr: r.stderr, durationMs: r.ms };
+        });
+    }
+    async writeFile(path, content) {
+        const r = await run(this.bin, ["exec", "-i", this.nativeId, "sh", "-c", `mkdir -p ${shq(dirname(path))} && cat > ${shq(path)}`], {
+            stdin: toBytes(content),
+        });
+        if (r.code !== 0)
+            throw new ProviderError("docker", `write ${path} failed: ${r.stderr.trim().slice(0, 300)}`);
+    }
+    async readFile(path) {
+        const r = await run(this.bin, ["exec", this.nativeId, "cat", path], { binary: true });
+        if (r.code !== 0)
+            throw new ProviderError("docker", `read ${path} failed: ${r.stderr.trim().slice(0, 300)}`, 404);
+        return r.bytes;
+    }
+    async pause() {
+        const r = await run(this.bin, ["pause", this.nativeId]);
+        if (r.code !== 0)
+            throw new ProviderError("docker", `pause failed: ${r.stderr.trim()}`);
+    }
+    async kill() {
+        await run(this.bin, ["rm", "-f", this.nativeId]);
+    }
+}
+function run(bin, args, opts = {}) {
+    const t0 = Date.now();
+    return new Promise((resolve, reject) => {
+        const child = spawn(bin, args, { stdio: ["pipe", "pipe", "pipe"] });
+        const out = [];
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        const dec = new TextDecoder();
+        const decErr = new TextDecoder();
+        child.stdout.on("data", (b) => {
+            if (opts.binary)
+                return void out.push(b);
+            const c = dec.decode(b, { stream: true });
+            stdout += c;
+            if (c)
+                opts.onStdout?.(c);
+        });
+        child.stderr.on("data", (b) => {
+            const c = decErr.decode(b, { stream: true });
+            stderr += c;
+            if (c)
+                opts.onStderr?.(c);
+        });
+        const timer = opts.timeoutMs
+            ? setTimeout(() => {
+                timedOut = true;
+                child.kill("SIGKILL");
+            }, opts.timeoutMs)
+            : undefined;
+        child.on("error", (e) => {
+            clearTimeout(timer);
+            reject(new ProviderError("docker", `could not run ${bin}: ${e.message}`));
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            resolve({ code, stdout, stderr, bytes: opts.binary ? new Uint8Array(Buffer.concat(out)) : undefined, ms: Date.now() - t0, timedOut });
+        });
+        if (opts.stdin)
+            child.stdin.end(Buffer.from(opts.stdin));
+        else
+            child.stdin.end();
+    });
+}

package/dist/providers/e2b.d.ts

@@ -0,0 +1,10 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/** E2B via the official `e2b` SDK. vCPU and memory come from the template, not the create call. */
+export declare class E2BProvider implements Provider {
+    private apiKey;
+    readonly id: "e2b";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/e2b.js

@@ -0,0 +1,69 @@
+import { ProviderError } from "../types.js";
+import { optionalImport, toBytes } from "../util.js";
+/** E2B via the official `e2b` SDK. vCPU and memory come from the template, not the create call. */
+export class E2BProvider {
+    apiKey;
+    id = "e2b";
+    constructor(apiKey = process.env.E2B_API_KEY) {
+        this.apiKey = apiKey;
+    }
+    configured() {
+        return !!this.apiKey;
+    }
+    async create(spec) {
+        const { Sandbox } = await optionalImport("e2b", "e2b");
+        const opts = {
+            apiKey: this.apiKey,
+            timeoutMs: (spec.timeoutMinutes ?? 30) * 60_000,
+            envs: spec.env,
+            metadata: spec.metadata,
+        };
+        const sbx = spec.image?.e2b ? await Sandbox.create(spec.image.e2b, opts) : await Sandbox.create(opts);
+        return new E2BBox(sbx);
+    }
+    async connect(nativeId) {
+        const { Sandbox } = await optionalImport("e2b", "e2b");
+        return new E2BBox(await Sandbox.connect(nativeId, { apiKey: this.apiKey }));
+    }
+}
+class E2BBox {
+    sbx;
+    nativeId;
+    constructor(sbx) {
+        this.sbx = sbx;
+        this.nativeId = sbx.sandboxId;
+    }
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        try {
+            const r = await this.sbx.commands.run(cmd, {
+                cwd: opts.cwd,
+                envs: opts.env,
+                timeoutMs: (opts.timeoutSeconds ?? 60) * 1000,
+                onStdout: opts.onStdout,
+                onStderr: opts.onStderr,
+            });
+            return { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr, durationMs: Date.now() - t0 };
+        }
+        catch (err) {
+            // The SDK throws CommandExitError for a nonzero exit; that's a result, not a failure.
+            if (err?.name === "CommandExitError" || typeof err?.exitCode === "number") {
+                return { exitCode: err.exitCode, stdout: err.stdout ?? "", stderr: err.stderr ?? "", durationMs: Date.now() - t0 };
+            }
+            throw new ProviderError("e2b", err?.message ?? String(err));
+        }
+    }
+    async writeFile(path, content) {
+        await this.sbx.files.write(path, toBytes(content));
+    }
+    async readFile(path) {
+        return await this.sbx.files.read(path, { format: "bytes" });
+    }
+    /** Snapshot memory and disk. Sandbox.connect (router.get) resumes it. */
+    async pause() {
+        await this.sbx.pause();
+    }
+    async kill() {
+        await this.sbx.kill();
+    }
+}

package/dist/providers/exedev.d.ts

@@ -0,0 +1,23 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+export declare class ExeDevProvider implements Provider {
+    private token;
+    private baseUrl;
+    readonly id: "exedev";
+    constructor(token?: string | undefined, baseUrl?: string);
+    configured(): boolean;
+    /** @internal POST /exec with a command line. */
+    request(command: string, accept?: string): Promise<Response>;
+    /** @internal Lobby command with JSON output. */
+    lobby<T>(command: string): Promise<T>;
+    /**
+     * @internal Run a shell script on the VM. The script is base64-encoded so it survives both quoting
+     * layers (the lobby's shell lexer, then the VM's shell) untouched.
+     */
+    ssh(vm: string, script: string): Promise<{
+        exitCode: number;
+        stdout: Uint8Array;
+        stderr: Uint8Array;
+    }>;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}

package/dist/providers/exedev.js

@@ -0,0 +1,278 @@
+import { randomBytes } from "node:crypto";
+import { ProviderError } from "../types.js";
+import { dirname, shq, toBytes, wrapCommand } from "../util.js";
+/**
+ * exe.dev standalone VMs over the HTTPS API (no SDK needed).
+ * Everything is one endpoint: POST https://exe.dev/exec, Authorization: Bearer exe1..., body = the
+ * command you would type at `ssh exe.dev`. Lifecycle commands answer JSON; `ssh <vm> <cmd>` runs a
+ * command in the VM and, with Accept: application/x-ndjson, answers {"stdout":b64} / {"stderr":b64}
+ * lines then {"exit_code":N} (or {"error":...}).
+ *   new --standalone --name=N --cpu=C --memory=MGB [--image=I] --json   create (metered per second)
+ *   ls --json                                                           list ({vms:[{vm_name,status,...}]})
+ *   ssh <vm> '<cmd>'                                                    run a command
+ *   rm <vm>                                                             delete; billing stops
+ * Limits of /exec: 30 s per request (504), 64 KB request body, no stdin, no pty. So exec runs the
+ * command detached on the VM (setsid nohup, as the docs suggest) and polls its output files, and
+ * files move as base64 inside commands, in chunks.
+ * The token must allow `new`, `ls`, `ssh` and `rm` (`ssh` and `rm` are not in the default cmds):
+ *   ssh exe.dev ssh-key generate-api-key --cmds=new,ls,ssh,rm --exp=30d
+ * Docs: https://exe.dev/docs/https-api.md, https://exe.dev/docs/https-api-run-on-vm.md,
+ *       https://exe.dev/docs/standalone-vms.md, https://exe.dev/docs/api.md
+ */
+const ID = "exedev";
+/** Leave headroom under the 64 KB body cap. */
+const MAX_BODY = 60_000;
+/** Raw bytes per writeFile chunk: base64 twice (4/3 * 4/3) plus the script stays under MAX_BODY. */
+const WRITE_CHUNK = 30_000;
+const VM_NAME = /^[a-z0-9][a-z0-9-]{0,62}$/;
+export class ExeDevProvider {
+    token;
+    baseUrl;
+    id = ID;
+    constructor(token = process.env.EXE_TOKEN, baseUrl = process.env.EXE_API_URL ?? "https://exe.dev") {
+        this.token = token;
+        this.baseUrl = baseUrl;
+    }
+    configured() {
+        return !!this.token;
+    }
+    /** @internal POST /exec with a command line. */
+    async request(command, accept = "application/json") {
+        if (!this.token)
+            throw new ProviderError(ID, "EXE_TOKEN is not set");
+        if (Buffer.byteLength(command) > MAX_BODY)
+            throw new ProviderError(ID, `request body over the 64 KB /exec limit (${Buffer.byteLength(command)} bytes)`);
+        const res = await fetch(`${this.baseUrl}/exec`, {
+            method: "POST",
+            headers: { Authorization: `Bearer ${this.token}`, "Content-Type": "text/plain", Accept: accept },
+            body: command,
+        });
+        // A VM command with a nonzero exit still streams its NDJSON result.
+        if (!res.ok && !(accept.includes("ndjson") && res.headers.get("content-type")?.includes("ndjson"))) {
+            const text = await res.text();
+            let detail = text.slice(0, 300);
+            try {
+                const j = JSON.parse(text);
+                if (typeof j?.error === "string")
+                    detail = j.error;
+            }
+            catch {
+                /* plain-text body */
+            }
+            const verb = command.split(" ", 1)[0];
+            throw new ProviderError(ID, `/exec ${verb} -> ${res.status} ${detail}`, res.status);
+        }
+        return res;
+    }
+    /** @internal Lobby command with JSON output. */
+    async lobby(command) {
+        const text = await (await this.request(`${command} --json`)).text();
+        const j = (text ? JSON.parse(text) : {});
+        if (typeof j.error === "string")
+            throw new ProviderError(ID, `${command.split(" ", 1)[0]}: ${j.error}`);
+        return j;
+    }
+    /**
+     * @internal Run a shell script on the VM. The script is base64-encoded so it survives both quoting
+     * layers (the lobby's shell lexer, then the VM's shell) untouched.
+     */
+    async ssh(vm, script) {
+        const b64 = Buffer.from(script).toString("base64");
+        const res = await this.request(`ssh ${vm} 'bash -c "$(echo ${b64} | base64 -d)"'`, "application/x-ndjson");
+        const out = [];
+        const err = [];
+        let exitCode;
+        for await (const line of readLines(res)) {
+            const j = JSON.parse(line);
+            if (j.stdout !== undefined)
+                out.push(Buffer.from(j.stdout, "base64"));
+            if (j.stderr !== undefined)
+                err.push(Buffer.from(j.stderr, "base64"));
+            if (j.exit_code !== undefined)
+                exitCode = j.exit_code;
+            if (j.error !== undefined)
+                throw new ProviderError(ID, `ssh ${vm}: ${j.error}`);
+        }
+        if (exitCode === undefined)
+            throw new ProviderError(ID, `ssh ${vm}: response ended without an exit code`);
+        return { exitCode, stdout: Buffer.concat(out), stderr: Buffer.concat(err) };
+    }
+    async create(spec) {
+        // Standalone VMs take up to 2 GiB per vCPU, so raise the vCPUs when the memory asks for more.
+        const memoryGb = Math.max(1, Math.ceil(spec.memoryGb ?? 4));
+        const cpu = Math.max(1, Math.ceil(spec.vcpu ?? 2), Math.ceil(memoryGb / 2));
+        const name = `sbr-${randomBytes(6).toString("hex")}`;
+        const flags = [`--standalone`, `--name=${name}`, `--cpu=${cpu}`, `--memory=${memoryGb}GB`];
+        const image = spec.image?.exedev;
+        if (image) {
+            if (!/^[A-Za-z0-9._/:@-]+$/.test(image))
+                throw new ProviderError(ID, `invalid image reference: ${image}`);
+            flags.push(`--image=${image}`);
+        }
+        const vm = await this.lobby(`new ${flags.join(" ")}`);
+        const box = new ExeDevSandbox(this, vm.vm_name ?? name, spec.env);
+        try {
+            await box.waitForSsh();
+        }
+        catch (err) {
+            await box.kill().catch(() => { });
+            throw err;
+        }
+        return box;
+    }
+    async connect(nativeId) {
+        if (!VM_NAME.test(nativeId))
+            throw new ProviderError(ID, `invalid VM name: ${nativeId}`);
+        const { vms = [] } = await this.lobby("ls");
+        if (!vms.some((v) => v.vm_name === nativeId))
+            throw new ProviderError(ID, `VM ${nativeId} not found`, 404);
+        return new ExeDevSandbox(this, nativeId);
+    }
+}
+class ExeDevSandbox {
+    p;
+    nativeId;
+    env;
+    constructor(p, nativeId, env) {
+        this.p = p;
+        this.nativeId = nativeId;
+        this.env = env;
+    }
+    /** `new` returns once the VM exists; retry a no-op until sshd answers. */
+    async waitForSsh(timeoutMs = 120_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            try {
+                if ((await this.p.ssh(this.nativeId, "true")).exitCode === 0)
+                    return;
+            }
+            catch (err) {
+                if (err instanceof ProviderError && (err.status === 401 || err.status === 403))
+                    throw err;
+                if (Date.now() > deadline)
+                    throw err;
+            }
+            if (Date.now() > deadline)
+                throw new ProviderError(ID, `VM ${this.nativeId} did not accept commands within ${timeoutMs / 1000}s`);
+            await sleep(1000);
+        }
+    }
+    /**
+     * One /exec request lasts at most 30 s, so the command runs detached on the VM, writing to
+     * /tmp/.sbr-<id>/{out,err,exit}. Each request waits up to `wait` for it to finish, sends the output
+     * written since the last request, and either exits with the command's code (done) or ends stderr
+     * with a random marker (still running).
+     */
+    async exec(cmd, opts = {}) {
+        const t0 = Date.now();
+        const timeout = Math.max(1, Math.round(opts.timeoutSeconds ?? 60));
+        const job = randomBytes(8).toString("hex");
+        const dir = `/tmp/.sbr-${job}`;
+        const marker = `__sandboxrouter_running_${job}__`;
+        const streaming = !!(opts.onStdout || opts.onStderr);
+        const waitTenths = streaming ? 10 : 200; // 1 s or 20 s per request
+        const full = wrapCommand(cmd, { cwd: opts.cwd, env: { ...this.env, ...opts.env } });
+        const cmdB64 = Buffer.from(full).toString("base64");
+        const report = (outOff, errOff) => [
+            `d=${dir}; i=0`,
+            `while [ ! -f "$d/exit" ] && [ $i -lt ${waitTenths} ]; do sleep 0.1; i=$((i+1)); done`,
+            `f=0; [ -f "$d/exit" ] && f=1`,
+            `tail -c +${outOff + 1} "$d/out" 2>/dev/null`,
+            `tail -c +${errOff + 1} "$d/err" >&2 2>/dev/null`,
+            `if [ $f = 1 ]; then c=$(cat "$d/exit"); rm -rf "$d"; exit "$c"; fi`,
+            `printf %s ${marker} >&2`,
+        ].join("\n");
+        const start = [
+            `d=${dir}; mkdir -p "$d" && echo ${cmdB64} | base64 -d > "$d/cmd" || exit 1`,
+            `setsid nohup bash -c 'timeout -k 5 ${timeout} bash "$0/cmd" > "$0/out" 2> "$0/err" < /dev/null; echo $? > "$0/exit.tmp"; mv "$0/exit.tmp" "$0/exit"' "$d" > /dev/null 2>&1 < /dev/null &`,
+            report(0, 0),
+        ].join("\n");
+        const outDec = new TextDecoder();
+        const errDec = new TextDecoder();
+        let stdout = "";
+        let stderr = "";
+        let outOff = 0;
+        let errOff = 0;
+        const deadline = Date.now() + (timeout + 60) * 1000;
+        let script = start;
+        for (;;) {
+            const r = await this.p.ssh(this.nativeId, script);
+            let errBytes = r.stderr;
+            const m = Buffer.from(marker);
+            const running = errBytes.length >= m.length && Buffer.from(errBytes.subarray(errBytes.length - m.length)).equals(m);
+            if (running)
+                errBytes = errBytes.subarray(0, errBytes.length - m.length);
+            outOff += r.stdout.length;
+            errOff += errBytes.length;
+            const o = outDec.decode(r.stdout, { stream: running });
+            const e = errDec.decode(errBytes, { stream: running });
+            if (o) {
+                stdout += o;
+                opts.onStdout?.(o);
+            }
+            if (e) {
+                stderr += e;
+                opts.onStderr?.(e);
+            }
+            if (!running)
+                return { exitCode: r.exitCode, stdout, stderr, durationMs: Date.now() - t0 };
+            if (Date.now() > deadline) {
+                await this.p.ssh(this.nativeId, `pkill -f ${shq(`${dir}/cmd`)}; rm -rf ${dir}`).catch(() => { });
+                throw new ProviderError(ID, `command still running ${timeout + 60}s after it started`);
+            }
+            script = report(outOff, errOff);
+        }
+    }
+    async writeFile(path, content) {
+        const bytes = toBytes(content);
+        const tmp = `${path}.sbr-${randomBytes(4).toString("hex")}`;
+        let first = true;
+        for (let i = 0; first || i < bytes.length; i += WRITE_CHUNK) {
+            const b64 = Buffer.from(bytes.subarray(i, i + WRITE_CHUNK)).toString("base64");
+            const prefix = first ? `mkdir -p ${shq(dirname(path))} && ` : "";
+            const r = await this.p.ssh(this.nativeId, `${prefix}echo ${b64 || "''"} | base64 -d ${first ? ">" : ">>"} ${shq(tmp)}`);
+            if (r.exitCode !== 0)
+                throw new ProviderError(ID, `writeFile ${path}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`);
+            first = false;
+        }
+        const r = await this.p.ssh(this.nativeId, `mv -f ${shq(tmp)} ${shq(path)}`);
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `writeFile ${path}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`);
+    }
+    async readFile(path) {
+        const r = await this.p.ssh(this.nativeId, `base64 -w0 ${shq(path)}`);
+        if (r.exitCode !== 0)
+            throw new ProviderError(ID, `readFile ${path}: ${r.stderr.toString().trim() || `exit ${r.exitCode}`}`);
+        return new Uint8Array(Buffer.from(r.stdout.toString(), "base64"));
+    }
+    async kill() {
+        await this.p.lobby(`rm ${this.nativeId}`);
+    }
+}
+/** Newline-delimited JSON reader for a fetch Response. */
+async function* readLines(res) {
+    if (!res.body)
+        return;
+    const reader = res.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = "";
+    for (;;) {
+        const { done, value } = await reader.read();
+        buffer += done ? decoder.decode() : decoder.decode(value, { stream: true });
+        let nl;
+        while ((nl = buffer.indexOf("\n")) !== -1) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (line)
+                yield line;
+        }
+        if (done) {
+            if (buffer.trim())
+                yield buffer.trim();
+            return;
+        }
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}

package/dist/providers/hopx.d.ts

@@ -0,0 +1,15 @@
+import { type Provider, type ProviderSandbox, type SandboxSpec } from "../types.js";
+/**
+ * HOPX via `@hopx-ai/sdk`. Auth: HOPX_API_KEY. vCPU and memory come from the template, not the
+ * create call (HOPX does not take custom resources at create). Set image.hopx to a template name
+ * (or a numeric template id) to start from your own; default is the public "code-interpreter".
+ */
+export declare class HopxProvider implements Provider {
+    private apiKey;
+    readonly id: "hopx";
+    constructor(apiKey?: string | undefined);
+    configured(): boolean;
+    create(spec: SandboxSpec): Promise<ProviderSandbox>;
+    /** Reattach; the SDK resumes a paused sandbox. */
+    connect(nativeId: string): Promise<ProviderSandbox>;
+}