ai-sdk-sandbox-sbx 1.0.0

package/dist/sbx-network-sandbox-session.js

@@ -0,0 +1,133 @@
+import { HarnessCapabilityUnsupportedError } from '@ai-sdk/harness';
+import { headerBroker, placeholderBroker, SBX_SANDBOX_PROVIDER_ID } from './credential-broker.js';
+import { cloudPorts, endpointUrl, loopbackPorts } from './port-publisher.js';
+import { KILL_ALL } from './sandbox-scripts.js';
+import { SbxSandboxSession } from './sbx-sandbox-session.js';
+export { SBX_SANDBOX_PROVIDER_ID } from './credential-broker.js';
+/**
+ * The whole of a Docker Sandbox, as `HarnessAgent.createSession({ sandboxSession })` expects it:
+ * files and processes, plus the ports a harness bridge listens on and the credentials the sandbox
+ * must never see.
+ *
+ * - **Ports** are published the first time the harness asks for them: on this host's loopback for
+ *   a local sandbox, at the public URL the control plane assigns for a cloud one.
+ * - **Credentials** stay out of the sandbox. Each request transformation the harness asks for
+ *   becomes a custom secret of the Docker Sandboxes proxy, scoped to this sandbox: the value only
+ *   exists on the host and in the proxy.
+ *
+ * Obtain one from `createSbxNetworkSandboxSession()` or `resumeSbxNetworkSandboxSession()`.
+ */
+export class SbxNetworkSandboxSession extends SbxSandboxSession {
+    id;
+    defaultWorkingDirectory;
+    /** Absent when brokering is off: the harness then forwards the real credential instead. */
+    addRequestTransformations;
+    /** Absent when brokering is off, like {@link addRequestTransformations}. */
+    setRequestTransformations;
+    /** Whether the sandbox runs in Docker Sandboxes Cloud rather than on this host. */
+    cloud;
+    exposed;
+    broker;
+    publisher;
+    /** Sandbox port → where it is published. */
+    published = new Map();
+    constructor(handle, ports, brokerCredentials) {
+        super(handle);
+        this.id = handle.name;
+        this.defaultWorkingDirectory = handle.workingDirectory;
+        this.cloud = handle.cli.cloud;
+        this.exposed = [...ports];
+        this.broker = this.cloud
+            ? headerBroker(handle.cli, handle.name)
+            : placeholderBroker(handle.cli, handle.name);
+        this.publisher = this.cloud
+            ? cloudPorts(handle.cli, handle.name)
+            : loopbackPorts(handle.cli, handle.name);
+        if (brokerCredentials) {
+            this.addRequestTransformations = (transformations) => this.broker.add(transformations);
+            this.setRequestTransformations = async (transformations) => {
+                await this.broker.clear();
+                await this.broker.add(transformations);
+            };
+        }
+    }
+    /** Ports the sandbox exposes, resolvable with {@link getPortEndpoint}. */
+    get ports() {
+        return this.exposed;
+    }
+    restricted = () => new SbxSandboxSession(this.handle);
+    getPortEndpoint = async ({ port, protocol = 'http', }) => {
+        if (!this.exposed.includes(port)) {
+            throw new HarnessCapabilityUnsupportedError({
+                harnessId: SBX_SANDBOX_PROVIDER_ID,
+                message: `Port ${port} is not exposed by sandbox "${this.id}". Exposed ports: [${this.exposed.join(', ')}].`,
+            });
+        }
+        let published = this.published.get(port);
+        if (published === undefined) {
+            published = this.publisher.publish(port);
+            this.published.set(port, published);
+            published.catch(() => this.published.delete(port));
+        }
+        return { url: endpointUrl((await published).url, protocol) };
+    };
+    /** @deprecated Use {@link getPortEndpoint}. */
+    getPortUrl = async (options) => (await this.getPortEndpoint(options)).url;
+    /** Replaces the exposed ports; a port left out is unpublished. */
+    setPorts = async (ports) => {
+        const removed = [...this.published.keys()].filter((port) => !ports.includes(port));
+        await Promise.all(removed.map((port) => this.unpublish(port)));
+        this.exposed = [...ports];
+    };
+    /**
+     * Hands the sandbox back without stopping it: the processes this session started are stopped,
+     * its ports unpublished and its secrets withdrawn from the proxy. What an application that
+     * keeps one sandbox across harness sessions calls between them.
+     */
+    release = async () => {
+        await this.killAll();
+        await Promise.all([...this.published.keys()].map((port) => this.unpublish(port)));
+        await this.broker.release();
+    };
+    /**
+     * Stops every process any session started in this sandbox, including those a previous run of the
+     * application left behind, such as a harness bridge still holding its port. Call it right after
+     * resuming a sandbox no other process uses.
+     */
+    killAllProcesses = async () => {
+        await this.handle.cli.check([...this.execArgs({}), 'sh', '-c', KILL_ALL]);
+        this.handle.processes.clear();
+    };
+    /**
+     * Extends the time-to-live of a cloud sandbox by `duration` (`30m`, `2h`), within the 24 hours
+     * after its creation the platform allows. Local sandboxes have no time-to-live.
+     */
+    extendTtl = async (duration) => {
+        if (!this.cloud)
+            throw new Error('Only a cloud sandbox has a time-to-live to extend.');
+        await this.handle.cli.check(['ttl', `+${duration}`, this.handle.name]);
+    };
+    /**
+     * Stops the sandbox, keeping it for the next `sbx exec`: a local microVM keeps its filesystem, a
+     * cloud one is suspended with its memory. Idempotent.
+     */
+    stop = async () => {
+        await this.release();
+        await this.handle.cli.run(['stop', this.handle.name]);
+    };
+    /** Removes the sandbox, with its filesystem and the secrets scoped to it. Idempotent. */
+    destroy = async () => {
+        await this.killAll();
+        this.published.clear();
+        await this.handle.cli.run(['rm', '--force', this.handle.name]);
+        // A local sandbox takes its secrets with it; a cloud secret is the account's, until removed.
+        if (this.cloud)
+            await this.broker.release();
+    };
+    async unpublish(port) {
+        const published = await this.published.get(port)?.catch(() => undefined);
+        this.published.delete(port);
+        if (published !== undefined)
+            await this.publisher.unpublish(published);
+    }
+}

package/dist/sbx-network-sandbox.d.ts

@@ -0,0 +1,26 @@
+import type { SbxNetworkSandboxSession } from './sbx-network-sandbox-session.js';
+import type { SbxNetworkSandboxSessionCreateOptions, SbxNetworkSandboxSessionResumeOptions } from './sbx-settings.js';
+/**
+ * Creates a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), a microVM run by the `sbx`
+ * CLI on this host, or in Docker Sandboxes Cloud with `cloud: true`, and returns a network sandbox
+ * session on it, to hand to `HarnessAgent.createSession({ sandboxSession })`.
+ *
+ * Creation never resumes: a sandbox already named `sandboxId` is a conflict. Persist the returned
+ * session's `id` and reattach with {@link resumeSbxNetworkSandboxSession}.
+ *
+ * Pass `template: await agent.getSandboxTemplate()` to install the harness once: the first call
+ * bakes a prepared sandbox into an image (`sbx template save`), in the local image store or in the
+ * cloud registry, and every later sandbox starts from it.
+ *
+ * The caller owns the sandbox: `stop()` keeps its filesystem for later, `destroy()` removes it.
+ */
+export declare function createSbxNetworkSandboxSession(options?: SbxNetworkSandboxSessionCreateOptions): Promise<SbxNetworkSandboxSession>;
+/**
+ * Reattaches to a Docker Sandbox made by {@link createSbxNetworkSandboxSession}, from this
+ * process or another one, starting it again if it was stopped. Never creates one: throws
+ * `SbxSandboxNotFoundError` when no sandbox is named `sandboxId`.
+ *
+ * Ports are not stored by `sbx` until published: pass the same `ports` the sandbox was created
+ * with.
+ */
+export declare function resumeSbxNetworkSandboxSession(options: SbxNetworkSandboxSessionResumeOptions): Promise<SbxNetworkSandboxSession>;

package/dist/sbx-network-sandbox.js

@@ -0,0 +1,68 @@
+import { randomBytes } from 'node:crypto';
+import { assertSandboxName, assertSettingsFit, createArgs } from './create-args.js';
+import { assertSandboxExists, listSandboxes, openSandbox, runSetup } from './open-sandbox.js';
+import { ensureTemplateImage } from './sandbox-template.js';
+import { SbxCli } from './sbx-cli.js';
+/** Fails, before anything is created, when `name` is taken. */
+async function assertNameFree(cli, name, abortSignal) {
+    if ((await listSandboxes(cli, abortSignal)).has(name)) {
+        throw new Error(`A Docker Sandbox named "${name}" already exists. Reattach to it with ` +
+            'resumeSbxNetworkSandboxSession({ sandboxId }), or remove it with `sbx rm`.');
+    }
+}
+/**
+ * Creates a [Docker Sandbox](https://docs.docker.com/ai/sandboxes/), a microVM run by the `sbx`
+ * CLI on this host, or in Docker Sandboxes Cloud with `cloud: true`, and returns a network sandbox
+ * session on it, to hand to `HarnessAgent.createSession({ sandboxSession })`.
+ *
+ * Creation never resumes: a sandbox already named `sandboxId` is a conflict. Persist the returned
+ * session's `id` and reattach with {@link resumeSbxNetworkSandboxSession}.
+ *
+ * Pass `template: await agent.getSandboxTemplate()` to install the harness once: the first call
+ * bakes a prepared sandbox into an image (`sbx template save`), in the local image store or in the
+ * cloud registry, and every later sandbox starts from it.
+ *
+ * The caller owns the sandbox: `stop()` keeps its filesystem for later, `destroy()` removes it.
+ */
+export async function createSbxNetworkSandboxSession(options = {}) {
+    const { abortSignal, template, setup = [] } = options;
+    abortSignal?.throwIfAborted();
+    const cloud = options.cloud ?? false;
+    const name = options.sandboxId ?? `ai-sdk-${randomBytes(4).toString('hex')}`;
+    assertSandboxName(name, cloud);
+    assertSettingsFit(options, cloud);
+    const cli = new SbxCli(options.binary, cloud);
+    await assertNameFree(cli, name, abortSignal);
+    const agent = options.agent ?? 'shell';
+    const image = template
+        ? await ensureTemplateImage(cli, { template, agent, image: options.image, setup }, abortSignal)
+        : options.image;
+    await cli.check(createArgs({ name, image, fromTemplate: template !== undefined, settings: options }), {
+        abortSignal,
+    });
+    try {
+        // A template already ran them, before it was saved.
+        if (!template)
+            await runSetup(cli, name, { setup, abortSignal });
+        return await openSandbox(cli, name, options);
+    }
+    catch (error) {
+        // Half-made, the sandbox would block a retry under the same id.
+        await cli.run(['rm', '--force', name]);
+        throw error;
+    }
+}
+/**
+ * Reattaches to a Docker Sandbox made by {@link createSbxNetworkSandboxSession}, from this
+ * process or another one, starting it again if it was stopped. Never creates one: throws
+ * `SbxSandboxNotFoundError` when no sandbox is named `sandboxId`.
+ *
+ * Ports are not stored by `sbx` until published: pass the same `ports` the sandbox was created
+ * with.
+ */
+export async function resumeSbxNetworkSandboxSession(options) {
+    options.abortSignal?.throwIfAborted();
+    const cli = new SbxCli(options.binary, options.cloud ?? false);
+    await assertSandboxExists(cli, options.sandboxId, options.abortSignal);
+    return openSandbox(cli, options.sandboxId, options);
+}

package/dist/sbx-sandbox-not-found-error.d.ts

@@ -0,0 +1,5 @@
+/** No sandbox of that name exists on this host: it was never created, or `sbx rm` removed it. */
+export declare class SbxSandboxNotFoundError extends Error {
+    readonly sandboxId: string;
+    constructor(sandboxId: string);
+}

package/dist/sbx-sandbox-not-found-error.js

@@ -0,0 +1,10 @@
+/** No sandbox of that name exists on this host: it was never created, or `sbx rm` removed it. */
+export class SbxSandboxNotFoundError extends Error {
+    sandboxId;
+    constructor(sandboxId) {
+        super(`No Docker Sandbox named "${sandboxId}" exists on this host. ` +
+            'Create it with createSbxNetworkSandboxSession({ sandboxId }) first.');
+        this.name = 'SbxSandboxNotFoundError';
+        this.sandboxId = sandboxId;
+    }
+}

package/dist/sbx-sandbox-session.d.ts

@@ -0,0 +1,60 @@
+import type { Experimental_SandboxProcess as SandboxProcess, Experimental_SandboxSession as SandboxSession } from '@ai-sdk/provider-utils';
+import type { SbxCli } from './sbx-cli.js';
+type ProcessOptions = Parameters<SandboxSession['spawn']>[0];
+type ReadOptions = Parameters<SandboxSession['readFile']>[0];
+type ReadTextOptions = Parameters<SandboxSession['readTextFile']>[0];
+type WriteOptions = Parameters<SandboxSession['writeFile']>[0];
+type WriteBinaryOptions = Parameters<SandboxSession['writeBinaryFile']>[0];
+type WriteTextOptions = Parameters<SandboxSession['writeTextFile']>[0];
+/** What every view of one sandbox shares: its name, the CLI that reaches it, its processes. */
+export interface SbxSandboxHandle {
+    readonly cli: SbxCli;
+    /** The sandbox's name in `sbx ls`. */
+    readonly name: string;
+    /** The sandbox's own working directory, which relative paths resolve against. */
+    readonly workingDirectory: string;
+    /** Pid files of the processes spawned and not yet exited. */
+    readonly processes: Set<string>;
+    /** Variables of the sandbox's own environment dropped from every command that does not set them. */
+    readonly clearEnv: readonly string[];
+}
+/** Throws unless every key of `env` can be forwarded as a bare `sbx exec -e NAME`. */
+export declare function assertEnvNames(names: Iterable<string>): void;
+/**
+ * The file and process surface of a Docker Sandbox: what a harness hands to its tools. Every call
+ * is an `sbx exec` into the sandbox's microVM: nothing runs on the host, and only the variables a
+ * command names are forwarded, never this process's environment.
+ */
+export declare class SbxSandboxSession implements SandboxSession {
+    protected readonly handle: SbxSandboxHandle;
+    constructor(handle: SbxSandboxHandle);
+    get description(): string;
+    run: (options: ProcessOptions) => Promise<{
+        exitCode: number;
+        stderr: string;
+        stdout: string;
+    }>;
+    spawn: (options: ProcessOptions) => Promise<SandboxProcess>;
+    /** Starts `command` in the sandbox, its pid recorded so it can be stopped from outside. */
+    private start;
+    readBinaryFile: ({ path, abortSignal }: ReadOptions) => Promise<null | Uint8Array>;
+    readFile: (options: ReadOptions) => Promise<null | ReadableStream<Uint8Array>>;
+    readTextFile: ({ encoding, startLine, endLine, ...options }: ReadTextOptions) => Promise<null | string>;
+    writeFile: ({ path, content, abortSignal }: WriteOptions) => Promise<void>;
+    writeBinaryFile: ({ content, ...options }: WriteBinaryOptions) => Promise<void>;
+    writeTextFile: ({ content, encoding, ...options }: WriteTextOptions) => Promise<void>;
+    /** Stops every process this view still runs in the sandbox. */
+    protected killAll(): Promise<void>;
+    private killTree;
+    private resolve;
+    /**
+     * `sbx exec` up to the sandbox name. Variables go as bare `-e NAME`: `sbx` then reads each value
+     * from its own environment, so none of them ever shows on a command line.
+     */
+    protected execArgs({ workingDirectory, env, stdin, }: {
+        env?: Record<string, string>;
+        stdin?: boolean;
+        workingDirectory?: string;
+    }): string[];
+}
+export {};

package/dist/sbx-sandbox-session.js

@@ -0,0 +1,159 @@
+import { randomUUID } from 'node:crypto';
+import { posix } from 'node:path';
+import { Readable } from 'node:stream';
+import { KILL_TREE, PROCESS_DIR, READ, READ_DIRECTORY, READ_MISSING, TRACKED, WRITE, } from './sandbox-scripts.js';
+import { abortReason } from './sbx-cli.js';
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** Throws unless every key of `env` can be forwarded as a bare `sbx exec -e NAME`. */
+export function assertEnvNames(names) {
+    for (const name of names) {
+        if (!ENV_NAME.test(name))
+            throw new Error(`Not an environment variable name: ${name}`);
+    }
+}
+/**
+ * The file and process surface of a Docker Sandbox: what a harness hands to its tools. Every call
+ * is an `sbx exec` into the sandbox's microVM: nothing runs on the host, and only the variables a
+ * command names are forwarded, never this process's environment.
+ */
+export class SbxSandboxSession {
+    handle;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    get description() {
+        return [
+            `Docker Sandbox "${this.handle.name}": a microVM with a filesystem of its own, working directory ${this.handle.workingDirectory}.`,
+            'Outbound traffic goes through the Docker Sandboxes proxy and its network policy.',
+        ].join('\n');
+    }
+    run = async (options) => {
+        const spawned = await this.spawn(options);
+        const [stdout, stderr, { exitCode }] = await Promise.all([
+            new Response(spawned.stdout).text(),
+            new Response(spawned.stderr).text(),
+            spawned.wait(),
+        ]);
+        return { exitCode, stdout, stderr };
+    };
+    spawn = (options) => {
+        try {
+            return Promise.resolve(this.start(options));
+        }
+        catch (error) {
+            return Promise.reject(error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+    /** Starts `command` in the sandbox, its pid recorded so it can be stopped from outside. */
+    start({ command, workingDirectory, env = {}, abortSignal, }) {
+        if (abortSignal?.aborted)
+            throw abortReason(abortSignal);
+        assertEnvNames(Object.keys(env));
+        const pidFile = `${PROCESS_DIR}/${randomUUID()}`;
+        const cleared = this.handle.clearEnv.filter((name) => !(name in env));
+        const script = cleared.length > 0 ? `unset ${cleared.join(' ')}; ${TRACKED}` : TRACKED;
+        const child = this.handle.cli.start([...this.execArgs({ workingDirectory, env }), 'sh', '-c', script, pidFile, command], { env });
+        this.handle.processes.add(pidFile);
+        let killed;
+        const kill = () => {
+            killed ??= this.killTree(pidFile).finally(() => child.kill());
+            return killed;
+        };
+        const onAbort = () => void kill();
+        abortSignal?.addEventListener('abort', onAbort, { once: true });
+        const exited = new Promise((resolve, reject) => {
+            child.once('error', reject);
+            child.once('close', (code) => {
+                this.handle.processes.delete(pidFile);
+                abortSignal?.removeEventListener('abort', onAbort);
+                if (abortSignal?.aborted) {
+                    reject(abortReason(abortSignal));
+                }
+                else {
+                    resolve({ exitCode: code ?? 137 });
+                }
+            });
+        });
+        // `wait()` may never be called; an unobserved rejection must not take the process down.
+        exited.catch(() => undefined);
+        return {
+            stdout: Readable.toWeb(child.stdout),
+            stderr: Readable.toWeb(child.stderr),
+            wait: () => exited,
+            kill,
+        };
+    }
+    readBinaryFile = async ({ path, abortSignal }) => {
+        const target = this.resolve(path);
+        const result = await this.handle.cli.run([...this.execArgs({}), 'sh', '-c', READ, target], {
+            abortSignal,
+        });
+        if (result.exitCode === READ_MISSING)
+            return null;
+        if (result.exitCode === READ_DIRECTORY) {
+            throw Object.assign(new Error(`EISDIR: illegal operation on a directory, read '${target}'`), {
+                code: 'EISDIR',
+            });
+        }
+        if (result.exitCode !== 0) {
+            throw new Error(`Could not read ${target} in the sandbox: ${result.stderr.trim()}`);
+        }
+        return new Uint8Array(result.stdout);
+    };
+    readFile = async (options) => {
+        const bytes = await this.readBinaryFile(options);
+        return bytes === null ? null : new Blob([bytes]).stream();
+    };
+    readTextFile = async ({ encoding = 'utf-8', startLine, endLine, ...options }) => {
+        const bytes = await this.readBinaryFile(options);
+        if (bytes === null)
+            return null;
+        const text = Buffer.from(bytes).toString(encoding);
+        if (startLine === undefined && endLine === undefined)
+            return text;
+        return text
+            .split('\n')
+            .slice((startLine ?? 1) - 1, endLine)
+            .join('\n');
+    };
+    writeFile = async ({ path, content, abortSignal }) => {
+        const target = this.resolve(path);
+        const result = await this.handle.cli.run([...this.execArgs({ stdin: true }), 'sh', '-c', WRITE, target], { stdin: content, abortSignal });
+        if (result.exitCode !== 0) {
+            throw new Error(`Could not write ${target} in the sandbox: ${result.stderr.trim()}`);
+        }
+    };
+    writeBinaryFile = ({ content, ...options }) => this.writeFile({
+        ...options,
+        content: new Blob([content]).stream(),
+    });
+    writeTextFile = ({ content, encoding = 'utf-8', ...options }) => this.writeBinaryFile({
+        ...options,
+        content: new Uint8Array(Buffer.from(content, encoding)),
+    });
+    /** Stops every process this view still runs in the sandbox. */
+    async killAll() {
+        await Promise.all([...this.handle.processes].map((pidFile) => this.killTree(pidFile)));
+        this.handle.processes.clear();
+    }
+    async killTree(pidFile) {
+        await this.handle.cli.run([...this.execArgs({}), 'sh', '-c', KILL_TREE, pidFile]);
+    }
+    resolve(path) {
+        return posix.resolve(this.handle.workingDirectory, path);
+    }
+    /**
+     * `sbx exec` up to the sandbox name. Variables go as bare `-e NAME`: `sbx` then reads each value
+     * from its own environment, so none of them ever shows on a command line.
+     */
+    execArgs({ workingDirectory, env = {}, stdin = false, }) {
+        return [
+            'exec',
+            ...(stdin ? ['-i'] : []),
+            '-w',
+            this.resolve(workingDirectory ?? '.'),
+            ...Object.keys(env).flatMap((name) => ['-e', name]),
+            this.handle.name,
+        ];
+    }
+}

package/dist/sbx-settings.d.ts

@@ -0,0 +1,118 @@
+import type { HarnessV1SandboxSessionCreateOptions, HarnessV1SandboxSessionResumeOptions } from '@ai-sdk/harness';
+/** How this process talks to a sandbox, the same whether the sandbox was just created or resumed. */
+export interface SbxConnectionSettings {
+    /**
+     * Run in [Docker Sandboxes Cloud](https://docs.docker.com/ai/sandboxes/) rather than on this
+     * host: every `sbx` command goes out as `sbx --cloud …`. Needs a Docker Agentic Platform
+     * subscription and `sbx login`. Experimental: it may change in a minor release while it settles.
+     *
+     * @defaultValue `false`
+     */
+    cloud?: boolean;
+    /**
+     * Ports inside the sandbox the harness may reach. Each is published the first time it is asked
+     * for: on this host's loopback for a local sandbox, at a public URL the control plane assigns for
+     * a cloud one. Bridge-backed harnesses (Claude Code, Codex…) listen on the first.
+     *
+     * @defaultValue `[]`
+     */
+    ports?: readonly number[];
+    /**
+     * Keep credentials out of the sandbox: the Docker Sandboxes proxy puts the real value in the
+     * requests on their way out (`sbx secret set-custom`). Turn it off
+     * only for an `sbx` without custom secrets: the harness then forwards the real credential into
+     * the sandbox environment.
+     *
+     * @defaultValue `true`
+     */
+    brokerCredentials?: boolean;
+    /**
+     * Variables of the sandbox's own environment to drop from every command that does not set them
+     * itself, on top of the `proxy-managed` ones (see {@link keepProxyManagedEnv}).
+     *
+     * @defaultValue `[]`
+     */
+    clearEnv?: readonly string[];
+    /**
+     * Docker Sandboxes pre-sets credential variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
+     * `GH_TOKEN`…) to a `proxy-managed` placeholder for its own credential store. Left in place, one
+     * can take precedence over the credential a harness does pass (the `claude` CLI prefers
+     * `ANTHROPIC_API_KEY` to `CLAUDE_CODE_OAUTH_TOKEN`), so every `*_API_KEY` and `*_TOKEN` variable
+     * holding such a placeholder is dropped from the commands that do not set it. Set this to keep
+     * them, when you rely on `sbx secret set` instead.
+     *
+     * @defaultValue `false`
+     */
+    keepProxyManagedEnv?: boolean;
+    /**
+     * The `sbx` binary.
+     *
+     * @defaultValue `'sbx'`, looked up on the `PATH`
+     */
+    binary?: string;
+}
+/** What a new sandbox is made of. Fixed at creation: `sbx` cannot change it afterwards. */
+export interface SbxCreationSettings extends SbxConnectionSettings {
+    /**
+     * The Docker Sandboxes agent kit the sandbox is made from: its image and network rules. `shell`
+     * is a plain Linux userland with Node.js and git; the harness installs its own runtime in it.
+     *
+     * @defaultValue `'shell'`
+     */
+    agent?: string;
+    /** Container image to use instead of the kit's own (`sbx create --template`). */
+    image?: string;
+    /**
+     * A directory of this host the sandbox works in, bind-mounted read-write: the agent edits your
+     * files. Without it the sandbox mounts nothing of the host and works on its own filesystem.
+     * Local sandboxes only.
+     */
+    workspace?: string;
+    /**
+     * With {@link workspace} set to a Git repository: give the sandbox a private clone of it instead
+     * of the directory itself (`sbx create --clone`). The host repository is only mounted read-only,
+     * and the agent's commits come back through the `sandbox-<name>` git remote on the host. Local
+     * sandboxes only.
+     *
+     * @defaultValue `false`
+     */
+    clone?: boolean;
+    /** More directories of this host, mounted read-only: documentation, a shared library… Local only. */
+    readOnlyWorkspaces?: readonly string[];
+    /**
+     * Hosts the sandbox may never reach, on top of the network policy (`sbx create --deny-network`).
+     * A deny can only narrow egress: it holds even if the policy allows the host.
+     */
+    denyNetwork?: readonly string[];
+    /** Hosts a cloud sandbox may reach, on top of the account's policy. Cloud sandboxes only. */
+    allowNetwork?: readonly string[];
+    /**
+     * CPUs given to the microVM. Default: decided by `sbx`. In the cloud, `cpus` and `memory` must
+     * name a billable shape together: 1 / `2g`, 2 / `4g`, 4 / `8g`, 8 / `16g`…
+     */
+    cpus?: number;
+    /** Memory limit of the microVM, in binary units (`4g`, `512m`). Default: decided by `sbx`. */
+    memory?: string;
+    /**
+     * How long a cloud sandbox lives (`30m`, `2h`) before it times out; at most 24 hours. Default:
+     * decided by the platform. Cloud sandboxes only.
+     */
+    ttl?: string;
+    /**
+     * What happens to a cloud sandbox when its `ttl` lapses: `stop` it in place, `restart` it, or
+     * `delete` it. Default: decided by the platform. Cloud sandboxes only.
+     */
+    onTimeout?: 'delete' | 'restart' | 'stop';
+    /** CPU architecture of a cloud sandbox. Default: the template's, or the platform's. Cloud only. */
+    platform?: 'linux/amd64' | 'linux/arm64';
+    /**
+     * Commands run once, right after the sandbox is created, to install a tool the harness needs,
+     * say. They run as the sandbox user, who has passwordless `sudo` in the Docker Sandboxes kits.
+     * With a `template`, they run before it is prepared and are baked into it.
+     */
+    setup?: readonly string[];
+}
+/** Options of `createSbxNetworkSandboxSession()`. */
+export type SbxNetworkSandboxSessionCreateOptions = HarnessV1SandboxSessionCreateOptions<SbxCreationSettings>;
+/** Options of `resumeSbxNetworkSandboxSession()`. */
+export type SbxNetworkSandboxSessionResumeOptions = HarnessV1SandboxSessionResumeOptions<SbxConnectionSettings>;

package/dist/sbx-settings.js

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