withruntime 0.8.4 → 0.10.0

package/dist/openai-agents/index.js

@@ -18,6 +18,7 @@
  * RUNTIME_API_KEY or this machine's `runtime login`. Plain function tools for
  * an ordinary `Agent` are `runtimeFunctionTools(sandbox)`. */
 import { applyDiff, tool, UserError, } from "@openai/agents-core";
+import { OPENAI_AGENTS_EXEC_TIMEOUT_MS } from "../api-defaults.js";
 import { SandboxProviderError, SandboxUnsupportedFeatureError, normalizeSandboxClientCreateArgs, } from "@openai/agents-core/sandbox";
 import { deserializeManifest, elapsedSeconds, formatExecResponse, imageOutputFromBytes, materializeEnvironment, mergeManifestDelta, mergeManifestEntryDelta, serializeManifestRecord, shellQuote, truncateOutput, } from "@openai/agents-core/sandbox/internal";
 import { Runtime } from "../client.js";
@@ -477,31 +478,11 @@ export class RuntimeCloudSandboxSession {
                 await this.#writeBytes(path, await readFile(entry.src));
                 return;
             }
-            case "local_dir": {
-                // One gzipped tar, staged inside /workspace where uploads of any size are accepted.
-                const { packDirectory } = await import("../tar.js");
-                const staging = `${STAGING}/${crypto.randomUUID()}.tar.gz`;
-                const archive = await packDirectory(entry.src);
-                try {
-                    await this.#call((sbx) => sbx.files.write(staging, archive));
-                    const unpacked = await this.#call((sbx) => sbx.exec([
-                        "sh",
-                        "-c",
-                        'mkdir -p -- "$1" && tar -xzf "$2" -C "$1"',
-                        "sh",
-                        path,
-                        staging,
-                    ]));
-                    if (unpacked.exitCode !== 0)
-                        throw new SandboxProviderError(`${PROVIDER} could not place ${entry.src}.`, {
-                            stderr: unpacked.stderr,
-                        });
-                }
-                finally {
-                    await this.#call((sbx) => sbx.files.remove(staging)).catch(() => undefined);
-                }
+            case "local_dir":
+                // One archive through the API's folder routes, unpacked by the
+                // sandbox's own tar as it arrives.
+                await this.#call((sbx) => sbx.files.upload(entry.src, path));
                 return;
-            }
             case "git_repo": {
                 const url = /^[a-z]+:\/\//.test(entry.repo)
                     ? entry.repo
@@ -550,29 +531,11 @@ export class RuntimeCloudSandboxSession {
     // Workspace archives.
     async persistWorkspace() {
         const root = this.state.manifest.root;
-        const staging = `${STAGING}/${crypto.randomUUID()}.tar`;
-        const skip = root === FILES_HOME ? ["--exclude=./.openai-agents-staging"] : [];
-        try {
-            const packed = await this.#call((sbx) => sbx.exec([
-                "sh",
-                "-c",
-                `mkdir -p -- ${STAGING} && tar ${skip.join(" ")} -C "$1" -cf - . > "$2"`,
-                "sh",
-                root,
-                staging,
-            ], {
-                cwd: "/",
-                timeoutMs: this.state.execTimeoutMs,
-            }));
-            if (packed.exitCode !== 0)
-                throw new SandboxProviderError(`${PROVIDER} could not archive the workspace.`, {
-                    stderr: packed.stderr,
-                });
-            return await this.#call((sbx) => sbx.files.read(staging));
-        }
-        finally {
-            await this.#call((sbx) => sbx.files.remove(staging)).catch(() => undefined);
-        }
+        return this.#call((sbx) => sbx.files.archive(root, {
+            gzip: false,
+            ...(root === FILES_HOME ? { exclude: [".openai-agents-staging"] } : {}),
+            timeoutMs: this.state.execTimeoutMs,
+        }));
     }
     async hydrateWorkspace(data) {
         const bytes = typeof data === "string"
@@ -580,28 +543,10 @@ export class RuntimeCloudSandboxSession {
             : data instanceof Uint8Array
                 ? data
                 : new Uint8Array(data);
-        const staging = `${STAGING}/${crypto.randomUUID()}.tar`;
-        try {
-            await this.#call((sbx) => sbx.files.write(staging, bytes));
-            const unpacked = await this.#call((sbx) => sbx.exec([
-                "sh",
-                "-c",
-                'mkdir -p -- "$1" && tar -C "$1" -xf "$2"',
-                "sh",
-                this.state.manifest.root,
-                staging,
-            ], {
-                cwd: "/",
-                timeoutMs: this.state.execTimeoutMs,
-            }));
-            if (unpacked.exitCode !== 0)
-                throw new SandboxProviderError(`${PROVIDER} could not restore the workspace.`, {
-                    stderr: unpacked.stderr,
-                });
-        }
-        finally {
-            await this.#call((sbx) => sbx.files.remove(staging)).catch(() => undefined);
-        }
+        await this.#call((sbx) => sbx.files.unarchive(this.state.manifest.root, bytes, {
+            gzip: false,
+            timeoutMs: this.state.execTimeoutMs,
+        }));
     }
     // Lifecycle.
     async running() {
@@ -674,7 +619,7 @@ export class RuntimeCloudSandboxClient {
             ...(options.exposedPorts ? { configuredExposedPorts: options.exposedPorts } : {}),
             previewVisibility: options.previewVisibility ?? "private",
             pauseOnExit: options.pauseOnExit ?? false,
-            execTimeoutMs: Math.min(MAX_EXEC_MS, options.execTimeoutMs ?? 3_600_000),
+            execTimeoutMs: Math.min(MAX_EXEC_MS, options.execTimeoutMs ?? OPENAI_AGENTS_EXEC_TIMEOUT_MS),
         };
         const session = new RuntimeCloudSandboxSession({ state, runtime: this.runtime });
         await session.sandbox();
@@ -764,7 +709,9 @@ export class RuntimeCloudSandboxClient {
                 : {}),
             previewVisibility: record.previewVisibility === "public" ? "public" : "private",
             pauseOnExit: record.pauseOnExit === true,
-            execTimeoutMs: typeof record.execTimeoutMs === "number" ? record.execTimeoutMs : 3_600_000,
+            execTimeoutMs: typeof record.execTimeoutMs === "number"
+                ? record.execTimeoutMs
+                : OPENAI_AGENTS_EXEC_TIMEOUT_MS,
         };
     }
 }

package/dist/page.d.ts

@@ -5,7 +5,7 @@ export declare class Page<T> implements AsyncIterable<T> {
     private readonly fetchPage;
     constructor(data: T[], nextCursor: string | null, fetchPage: (cursor: string) => Promise<Page<T>>);
     get hasMore(): boolean;
-    next(): Promise<Page<T> | null>;
+    next(cursor?: string | null): Promise<Page<T> | null>;
     /** Every page, fetched as you go. */
     pages(): AsyncGenerator<Page<T>>;
     [Symbol.asyncIterator](): AsyncGenerator<T>;

package/dist/page.js

@@ -11,8 +11,8 @@ export class Page {
     get hasMore() {
         return this.nextCursor !== null;
     }
-    async next() {
-        return this.nextCursor === null ? null : this.fetchPage(this.nextCursor);
+    async next(cursor = this.nextCursor) {
+        return cursor === null ? null : this.fetchPage(cursor);
     }
     /** Every page, fetched as you go. */
     async *pages() {

package/dist/products/audit.d.ts

@@ -26,6 +26,9 @@ export type AuditEvent = {
     ip: string | null;
     requestId: string | null;
     via: "web" | "api" | "mcp" | "runtime";
+    /** The sandbox the request came from, when code in it called the API at
+     * http://runtime.internal. */
+    sandbox: string | null;
 };
 export type AuditPage = {
     events: AuditEvent[];

package/dist/products/index.d.ts

@@ -15,6 +15,7 @@ import { limits } from "./limits.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
+import { sandboxTailscale } from "./tailscale.js";
 import { secrets } from "./secrets.js";
 import { mcp, sandboxMcp } from "./mcp.js";
 import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
@@ -39,17 +40,30 @@ export declare const clientExtensions: {
     tunnel: typeof tunnel;
     network: typeof network;
 };
+/** Canonical CLI product names share the existing factory instance. Account
+ * commands such as secrets, events and billing retain their current names. */
+export declare const clientProductAliases: {
+    readonly image: "images";
+    readonly volume: "volumes";
+    readonly job: "jobs";
+    readonly domain: "domains";
+    readonly port: "ports";
+    readonly address: "addresses";
+};
 export declare const sandboxExtensions: {
     interpreter: typeof sandboxInterpreter;
     previews: typeof sandboxPreviews;
     network: typeof sandboxNetwork;
     desktop: typeof sandboxDesktop;
     mounts: typeof sandboxMounts;
+    tailscale: typeof sandboxTailscale;
     metrics: typeof sandboxMetrics;
     mcp: typeof sandboxMcp;
 };
 export type ClientExtensions = {
     readonly [K in keyof typeof clientExtensions]: ReturnType<(typeof clientExtensions)[K]>;
+} & {
+    readonly [K in keyof typeof clientProductAliases]: ReturnType<(typeof clientExtensions)[(typeof clientProductAliases)[K]]>;
 };
 export type SandboxExtensions = {
     readonly [K in keyof typeof sandboxExtensions]: ReturnType<(typeof sandboxExtensions)[K]>;

package/dist/products/index.js

@@ -13,6 +13,7 @@ import { limits } from "./limits.js";
 import { volumes } from "./volumes.js";
 import { jobs } from "./jobs.js";
 import { sandboxMounts } from "./mounts.js";
+import { sandboxTailscale } from "./tailscale.js";
 import { secrets } from "./secrets.js";
 import { mcp, sandboxMcp } from "./mcp.js";
 import { events, otel, sandboxMetrics, webhooks } from "./observability.js";
@@ -52,12 +53,23 @@ export const clientExtensions = {
     tunnel,
     network,
 };
+/** Canonical CLI product names share the existing factory instance. Account
+ * commands such as secrets, events and billing retain their current names. */
+export const clientProductAliases = {
+    image: "images",
+    volume: "volumes",
+    job: "jobs",
+    domain: "domains",
+    port: "ports",
+    address: "addresses",
+};
 export const sandboxExtensions = {
     interpreter: sandboxInterpreter,
     previews: sandboxPreviews,
     network: sandboxNetwork,
     desktop: sandboxDesktop,
     mounts: sandboxMounts,
+    tailscale: sandboxTailscale,
     metrics: sandboxMetrics,
     mcp: sandboxMcp,
 };

package/dist/products/interpreter.d.ts

@@ -50,15 +50,22 @@ export type RunOptions = RequestOptions & {
     /** A context id; each language's own name ("python", "typescript", "r"...) is
      * its default context, started on first use. */
     context?: string;
+    /** Cell deadline. 0 runs until completion, cancellation or the sandbox's lease ends. */
     timeoutMs?: number;
-    onStdout?: (text: string) => void;
-    onStderr?: (text: string) => void;
-    onResult?: (result: ExecutionResult) => void;
+    /** Separate HTTP deadline, including retries. 0 disables it. */
+    requestTimeoutMs?: number;
+    /** false lets the cell continue if this reader disconnects. Default true. */
+    interruptOnDisconnect?: boolean;
+    /** @internal Compatibility protocols with separate header/body deadlines. */
+    onResponse?: (response: Response) => void;
+    onStdout?: (text: string) => unknown;
+    onStderr?: (text: string) => unknown;
+    onResult?: (result: ExecutionResult) => unknown;
     onError?: (error: {
         name: string;
         value: string;
         traceback: string;
-    }) => void;
+    }) => unknown;
 };
 /** A stateful interpreter in the sandbox, in Python, JavaScript, TypeScript,
  * R, Java, Bash or Go:

package/dist/products/interpreter.js

@@ -1,3 +1,4 @@
+import { RuntimeError } from "../errors.js";
 /** A stateful interpreter in the sandbox, in Python, JavaScript, TypeScript,
  * R, Java, Bash or Go:
  * `await sbx.interpreter.run("import pandas as pd; pd.DataFrame({'a': [1]})")`.
@@ -7,33 +8,56 @@ export function sandboxInterpreter(t, sandbox) {
     return {
         /** Run a cell. With any of the on* callbacks, output streams as it happens. */
         async run(code, options = {}) {
-            const { language, context, timeoutMs, onStdout, onStderr, onResult, onError, ...request } = options;
+            const { language, context, timeoutMs, requestTimeoutMs, interruptOnDisconnect, onStdout, onStderr, onResult, onError, ...request } = options;
+            const transportOptions = {
+                ...request,
+                ...(requestTimeoutMs !== undefined
+                    ? { timeoutMs: requestTimeoutMs }
+                    : timeoutMs !== undefined
+                        ? { timeoutMs: timeoutMs === 0 ? 0 : timeoutMs + 60_000 }
+                        : {}),
+            };
             const body = {
                 code,
                 ...(language ? { language } : {}),
                 ...(context ? { context } : {}),
-                ...(timeoutMs ? { timeoutMs } : {}),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                ...(interruptOnDisconnect !== undefined ? { interruptOnDisconnect } : {}),
             };
             if (!onStdout && !onStderr && !onResult && !onError)
-                return t.json({ method: "POST", path: `${base()}:run`, body, ...request });
+                return t.json({
+                    method: "POST",
+                    path: `${base()}:run`,
+                    body,
+                    ...transportOptions,
+                });
             for await (const event of t.events({
                 method: "POST",
                 path: `${base()}:run`,
                 body: { ...body, stream: true },
-                ...request,
+                ...transportOptions,
             })) {
                 if (event.k === "stdout")
-                    onStdout?.(event.text);
+                    await onStdout?.(event.text);
                 else if (event.k === "stderr")
-                    onStderr?.(event.text);
+                    await onStderr?.(event.text);
                 else if (event.k === "result")
-                    onResult?.({ main: event.main, data: event.data, refs: event.refs });
+                    await onResult?.({ main: event.main, data: event.data, refs: event.refs });
                 else if (event.k === "error")
-                    onError?.(event);
+                    await onError?.(event);
                 else if (event.k === "execution")
                     return event.execution;
                 else if (event.k === "failure")
-                    throw new Error(`${event.code}: ${event.message}`);
+                    // As every other refusal: its code, words, hint and request id,
+                    // printed by the CLI as it prints the rest (28 September 2026:
+                    // "Error: forbidden: cloud forbidden", with no hint and no id).
+                    throw new RuntimeError({
+                        code: event.code,
+                        status: event.status ?? 0,
+                        message: event.message,
+                        ...(event.hint ? { hint: event.hint } : {}),
+                        ...(event.requestId ? { requestId: event.requestId } : {}),
+                    });
             }
             throw new Error("The interpreter stream ended without a result");
         },

package/dist/products/jobs.js

@@ -1,3 +1,4 @@
+import { JOB_START_SECONDS, JOB_TIMEOUT_SECONDS } from "../api-defaults.js";
 import { Page } from "../page.js";
 import { RuntimeError, ServiceUnavailableError } from "../errors.js";
 /** The size a run gets when `compute` leaves a field out: the sandbox
@@ -9,9 +10,9 @@ export const JOB_DEFAULTS = {
     cpuFloorMillis: 50,
     memoryMiB: 4096,
     diskMiB: 4096,
-    timeoutSeconds: 1800,
+    timeoutSeconds: JOB_TIMEOUT_SECONDS,
     /** Added to the timeout for the sandbox to start, within the hour. */
-    startSeconds: 60,
+    startSeconds: JOB_START_SECONDS,
 };
 /** A run is one sandbox: at most 16 vCPU and 64 GiB, a disk no smaller than
  * the system image, and paid for at most an hour. */

package/dist/products/limits.d.ts

@@ -14,6 +14,16 @@ export type KeyLimits = {
         remainingMicros: string | null;
         window: "24h";
     };
+    /** The account's free trial time in milliseconds, the same figures as
+     * `usage.get()`, or null when the account has no trial. A trial sandbox
+     * that has not ended holds its whole lease in `reservedMs`;
+     * `availableMs = totalMs - usedMs - reservedMs`. */
+    trial: {
+        totalMs: number;
+        usedMs: number;
+        reservedMs: number;
+        availableMs: number;
+    } | null;
 };
 /** `runtime.limits.get()`: whether this key is read-only, and what its agent
  * may still spend today. An owner sets the limit at

package/dist/products/observability.d.ts

@@ -10,6 +10,11 @@ export type MetricPoint = {
     cpuCores: number | null;
     /** The busiest interval between two readings in the bucket. */
     cpuPeakPercent: number | null;
+    /** Measured wall-time percentage ready to run while waiting for CPU; null
+     * without two complete readings of the same run. Older servers omit it. */
+    cpuWaitPercent?: number | null;
+    /** Measured wall-time percentage with a thread waiting for memory. */
+    memoryStallPercent?: number | null;
     /** Average resident memory, bytes. */
     memoryBytes: number;
     memoryPeakBytes: number;
@@ -96,6 +101,45 @@ type List<T> = {
     data: T[];
     nextCursor: string | null;
 };
+export type UsageExportQuery = {
+    since: string;
+    until: string;
+    cursor?: string;
+    limit?: number;
+};
+export type UsageExportRow = {
+    intervalId: string;
+    resourceId: string;
+    name: string | null;
+    kind: string;
+    meter: string;
+    fundedBy: "credit" | "trial";
+    startsAt: string;
+    endsAt: string;
+    settledAt: string;
+    billedMilliseconds: string | null;
+    chargedMicros: string;
+    quotedRates: Array<{
+        component: string;
+        unit: string;
+        rateMicros: string;
+    }>;
+    /** Exact JSON text, preserving integers beyond JavaScript's number range. */
+    measurementsJson: string | null;
+    evidence: "measured" | "partial" | "missing" | null;
+};
+export type UsageExportPage = {
+    since: string;
+    until: string;
+    data: UsageExportRow[];
+    nextCursor: string | null;
+    /** Concatenate pages in order; only the first page includes the header. */
+    csv: string;
+};
+/** Top-level cross-product settled usage, selected by UTC settlement timestamps
+ * in [since, until). Pending holds are excluded. Follow nextCursor using the
+ * same range; each page checks current permissions. Pages are live reads. */
+export declare function usageExport(t: Transport): (query: UsageExportQuery, options?: RequestOptions) => Promise<UsageExportPage>;
 /** `sbx.metrics()`: this sandbox's measured CPU and memory. */
 export declare function sandboxMetrics(t: Transport, sandbox: Sandbox): (options?: {
     range?: MetricRange;

package/dist/products/observability.js

@@ -1,3 +1,9 @@
+/** Top-level cross-product settled usage, selected by UTC settlement timestamps
+ * in [since, until). Pending holds are excluded. Follow nextCursor using the
+ * same range; each page checks current permissions. Pages are live reads. */
+export function usageExport(t) {
+    return (query, options = {}) => t.json({ method: "GET", path: "/v1/usage/export", query, ...options });
+}
 /** `sbx.metrics()`: this sandbox's measured CPU and memory. */
 export function sandboxMetrics(t, sandbox) {
     return (options = {}) => {

package/dist/products/previews.d.ts

@@ -17,6 +17,8 @@ export type Preview = {
     urlWithToken: string | null;
     /** Turned off by Runtime after a report. */
     disabled: boolean;
+    /** The sites that may show it in an iframe; null for any site. */
+    embedOrigins: string[] | null;
     createdAt: string;
     /** On create only: how to share the address, in one line. */
     hint?: string;
@@ -27,6 +29,14 @@ export type CreatePreview = {
     visibility?: "private" | "public";
     /** How long the returned token lasts, 60 s to 7 days (default 1 day). */
     ttlSeconds?: number;
+    /** An absolute ISO private-token deadline, a minute to a week ahead.
+     * Used exactly without TTL; with TTL, the earlier expiry wins. */
+    expiresAt?: string;
+    /** The sites that may show it in an iframe, as origins
+     * (`https://app.example.com`, `https://*.example.com`, `http://localhost:3000`),
+     * up to 16. Any other site's iframe is refused. Omitted: a shared port keeps
+     * its list; `[]` or null: any site, the default. */
+    embedOrigins?: string[] | null;
 };
 /** `sbx.previews`: share ports of this sandbox at public HTTPS addresses.
  *
@@ -35,15 +45,19 @@ export type CreatePreview = {
  *
  * WebSockets work. The server must listen on 0.0.0.0 or localhost. */
 export declare function sandboxPreviews(t: Transport, sandbox: Sandbox): {
-    /** Shares `port`, or changes its visibility if it is shared already. */
+    /** Shares `port`, or changes its visibility and embedOrigins if it is
+     * shared already. */
     create: (port: number, input?: CreatePreview, options?: RequestOptions) => Promise<Preview>;
     /** Every shared port, each private one with a fresh token. */
     list: (options?: RequestOptions) => Promise<Preview[]>;
-    /** One preview, with a fresh token of `ttlSeconds` if it is private. */
-    get: (port: number, ttlSeconds?: number, options?: RequestOptions) => Promise<Preview>;
+    /** One preview, with a fresh private token. `expiresAt` bounds its expiry
+     * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */
+    get: (port: number, ttlSeconds?: number, { expiresAt, ...options }?: RequestOptions & {
+        expiresAt?: string;
+    }) => Promise<Preview>;
     /** Refuses every token issued for this port so far and returns a new one. */
     rotate: (port: number, options?: RequestOptions) => Promise<Preview>;
-    /** Stops sharing `port`. Open connections close within seconds. */
+    /** Stops sharing `port`. Its open connections are closed before this returns. */
     delete: (port: number, options?: RequestOptions) => Promise<{
         id: string;
         sandboxId: string;

package/dist/products/previews.js

@@ -7,20 +7,29 @@
 export function sandboxPreviews(t, sandbox) {
     const base = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/previews`;
     return {
-        /** Shares `port`, or changes its visibility if it is shared already. */
+        /** Shares `port`, or changes its visibility and embedOrigins if it is
+         * shared already. */
         create: (port, input = {}, options) => t.json({ method: "POST", path: base(), body: { port, ...input }, ...options }),
         /** Every shared port, each private one with a fresh token. */
         list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
-        /** One preview, with a fresh token of `ttlSeconds` if it is private. */
-        get: (port, ttlSeconds, options) => t.json({
+        /** One preview, with a fresh private token. `expiresAt` bounds its expiry
+         * to an absolute ISO deadline; with no TTL, that deadline is used exactly. */
+        get: (port, ttlSeconds, { expiresAt, ...options } = {}) => t.json({
             method: "GET",
             path: `${base()}/${port}`,
-            ...(ttlSeconds ? { query: { ttlSeconds } } : {}),
+            ...(ttlSeconds !== undefined || expiresAt !== undefined
+                ? {
+                    query: {
+                        ...(ttlSeconds === undefined ? {} : { ttlSeconds }),
+                        ...(expiresAt === undefined ? {} : { expiresAt }),
+                    },
+                }
+                : {}),
             ...options,
         }),
         /** Refuses every token issued for this port so far and returns a new one. */
         rotate: (port, options) => t.json({ method: "POST", path: `${base()}/${port}:rotate`, ...options }),
-        /** Stops sharing `port`. Open connections close within seconds. */
+        /** Stops sharing `port`. Its open connections are closed before this returns. */
         delete: (port, options) => t.json({
             method: "DELETE",
             path: `${base()}/${port}`,

package/dist/products/tailscale.d.ts

@@ -0,0 +1,57 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** Joining a sandbox to your tailnet. */
+export type TailscaleJoin = {
+    /** The name of a secret stored for jobs (`runtime secrets set NAME --jobs`)
+     * that holds a Tailscale auth key. Use an ephemeral, tagged key. */
+    authKeySecret: string;
+    /** The machine's name on the tailnet, a DNS label. Default: the sandbox's
+     * name, or runtime- and the first part of its id. */
+    hostname?: string;
+    /** Tags to advertise, such as `tag:agents`; the key must be allowed them. */
+    tags?: string[];
+};
+/** A sandbox's machine on your tailnet, as the sandbox reports it. */
+export type TailscaleNode = {
+    /** Logged in and running now. */
+    running: boolean;
+    /** Tailscale's own word: Running, NeedsLogin, Starting, Stopped. */
+    state: string | null;
+    /** kernel: a tailscale0 interface reaches 100.x directly. userspace: the
+     * tailnet reaches the sandbox's ports, and programs in it reach the tailnet
+     * through `proxy`. */
+    mode: "kernel" | "userspace" | null;
+    /** Its MagicDNS name, such as agent-1.tail1234.ts.net. */
+    dnsName: string | null;
+    /** Its tailnet addresses, 100.x and fd7a:… */
+    addresses: string[];
+    /** SOCKS5 and HTTP proxy to the tailnet in userspace mode. */
+    proxy: string | null;
+};
+/** What a join answers: the node, and what Runtime recorded. */
+export type TailscaleJoined = TailscaleNode & {
+    hostname: string;
+    tags: string[];
+    /** The secret the key was read from; never the key. */
+    authKeySecret: string | null;
+    joinedAt: number;
+};
+/** What `status()` answers: the node, and the join, or null on none. */
+export type TailscaleStatus = TailscaleNode & {
+    tailnet: Pick<TailscaleJoined, "hostname" | "tags" | "authKeySecret" | "joinedAt"> | null;
+};
+/** `sbx.tailscale`: this sandbox on your own Tailscale network. Paid
+ * sandboxes only.
+ *
+ *   const node = await sbx.tailscale.up({ authKeySecret: "TS_AUTHKEY", tags: ["tag:agents"] });
+ *   console.log(node.addresses);
+ *
+ * The auth key stays in the sandbox's memory. `down()` takes the machine off
+ * the tailnet at once; after a stop or a delete, Tailscale removes it. */
+export declare function sandboxTailscale(t: Transport, sandbox: Sandbox): {
+    up: (input: TailscaleJoin, options?: RequestOptions) => Promise<TailscaleJoined>;
+    status: (options?: RequestOptions) => Promise<TailscaleStatus>;
+    down: (options?: RequestOptions) => Promise<{
+        left: boolean;
+    }>;
+};

package/dist/products/tailscale.js

@@ -0,0 +1,17 @@
+const enc = encodeURIComponent;
+/** `sbx.tailscale`: this sandbox on your own Tailscale network. Paid
+ * sandboxes only.
+ *
+ *   const node = await sbx.tailscale.up({ authKeySecret: "TS_AUTHKEY", tags: ["tag:agents"] });
+ *   console.log(node.addresses);
+ *
+ * The auth key stays in the sandbox's memory. `down()` takes the machine off
+ * the tailnet at once; after a stop or a delete, Tailscale removes it. */
+export function sandboxTailscale(t, sandbox) {
+    const path = () => `/v1/sandboxes/${enc(sandbox.id)}/tailscale`;
+    return {
+        up: (input, options) => t.json({ method: "POST", path: path(), body: input, ...options }),
+        status: (options) => t.json({ method: "GET", path: path(), ...options }),
+        down: (options) => t.json({ method: "DELETE", path: path(), ...options }),
+    };
+}