withruntime 0.5.0 → 0.6.0

package/dist/products/mcp.d.ts

@@ -0,0 +1,79 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+export type McpCatalogEntry = {
+    id: string;
+    title: string;
+    description: string;
+    license: string;
+    source: string;
+    version: string;
+    env: {
+        name: string;
+        description: string;
+        required: boolean;
+        secret: boolean;
+        hosts?: string[];
+    }[];
+    options: {
+        name: string;
+        description: string;
+        required: boolean;
+    }[];
+    egress: string[];
+    checked: string;
+};
+export type McpServerRequest = {
+    /** A catalog id, e.g. "github". */
+    id: string;
+    name?: string;
+    /** A secret setting to the Runtime secret that fills it. */
+    secrets?: Record<string, string>;
+    env?: Record<string, string>;
+    options?: Record<string, string>;
+} | {
+    name: string;
+    command: string[];
+    env?: Record<string, string>;
+};
+export type McpGateway = {
+    running: boolean;
+    port: number | null;
+    /** Send it as `Authorization: Bearer <token>`. */
+    token?: string | null;
+    headers?: Record<string, string>;
+    urlExpiresAt?: string | null;
+    servers: {
+        name: string;
+        status: "installing" | "ready" | "failed";
+        message?: string | null;
+        /** Its Streamable HTTP endpoint. */
+        url: string | null;
+    }[];
+    warnings: string[];
+};
+/** `runtime.mcp`: the catalog of MCP servers a sandbox can run. */
+export declare function mcp(t: Transport): {
+    catalog: (options?: RequestOptions) => Promise<McpCatalogEntry[]>;
+};
+/** `sbx.mcp`: catalog MCP servers running inside the sandbox, at URLs an
+ * agent connects to.
+ *
+ *   const gw = await sbx.mcp.start([{ id: "github", secrets: { GITHUB_PERSONAL_ACCESS_TOKEN: "GITHUB_TOKEN" } }]);
+ *   // gw.servers[0].url with gw.headers, in any MCP client
+ */
+export declare function sandboxMcp(t: Transport, sandbox: Sandbox): {
+    start: (servers: McpServerRequest[], input?: {
+        port?: number;
+        replace?: boolean;
+    }, options?: RequestOptions) => Promise<McpGateway>;
+    /** Their state, and fresh URLs. */
+    get: (options?: RequestOptions) => Promise<McpGateway>;
+    /** Wait until every server is ready (or one failed). */
+    ready(input?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<McpGateway>;
+    stop: (options?: RequestOptions) => Promise<{
+        stopped: boolean;
+    }>;
+};

package/dist/products/mcp.js

@@ -0,0 +1,37 @@
+/** `runtime.mcp`: the catalog of MCP servers a sandbox can run. */
+export function mcp(t) {
+    return {
+        catalog: async (options) => (await t.json({
+            method: "GET",
+            path: "/v1/mcp/catalog",
+            ...options,
+        })).data,
+    };
+}
+/** `sbx.mcp`: catalog MCP servers running inside the sandbox, at URLs an
+ * agent connects to.
+ *
+ *   const gw = await sbx.mcp.start([{ id: "github", secrets: { GITHUB_PERSONAL_ACCESS_TOKEN: "GITHUB_TOKEN" } }]);
+ *   // gw.servers[0].url with gw.headers, in any MCP client
+ */
+export function sandboxMcp(t, sandbox) {
+    const path = () => `/v1/sandboxes/${encodeURIComponent(sandbox.id)}/mcp`;
+    return {
+        start: (servers, input = {}, options) => t.json({ method: "POST", path: path(), body: { servers, ...input }, ...options }),
+        /** Their state, and fresh URLs. */
+        get: (options) => t.json({ method: "GET", path: path(), ...options }),
+        /** Wait until every server is ready (or one failed). */
+        async ready(input = {}) {
+            const deadline = Date.now() + (input.timeoutMs ?? 600_000);
+            for (;;) {
+                const state = await t.json({ method: "GET", path: path() });
+                if (!state.running || state.servers.every((server) => server.status !== "installing"))
+                    return state;
+                if (Date.now() > deadline)
+                    return state;
+                await new Promise((resolve) => setTimeout(resolve, input.intervalMs ?? 2_000));
+            }
+        },
+        stop: (options) => t.json({ method: "DELETE", path: path(), ...options }),
+    };
+}

package/dist/products/mounts.d.ts

@@ -0,0 +1,49 @@
+import type { Sandbox } from "../sandbox.js";
+import type { RequestOptions, Transport } from "../transport.js";
+/** A bucket mounted in a sandbox. */
+export type Mount = {
+    path: string;
+    provider: "s3" | "r2" | "gcs";
+    bucket: string;
+    prefix: string | null;
+    /** The endpoint host the sandbox reaches the bucket at. */
+    endpoint: string;
+    /** The secret whose key the egress proxy signs with; null for a public bucket. */
+    secret: string | null;
+    readOnly: boolean;
+    /** Whether it is mounted right now. */
+    mounted: boolean;
+    mountedAt?: string;
+};
+export type MountBucket = {
+    /** s3 for Amazon S3, or any S3-compatible store with `endpoint`; r2 for
+     * Cloudflare R2 (with `accountId`); gcs for Google Cloud Storage (HMAC keys). */
+    provider: "s3" | "r2" | "gcs";
+    bucket: string;
+    /** Where it appears in the sandbox, such as /data. */
+    path: string;
+    prefix?: string;
+    region?: string;
+    endpoint?: string;
+    accountId?: string;
+    /** A secret stored with header `Authorization`, format
+     * `AWS4-HMAC-SHA256 {value}` and value `ACCESS_KEY_ID:SECRET_KEY`, naming
+     * the endpoint host. The sandbox never sees the key. Omit for a public bucket. */
+    secret?: string;
+    readOnly?: boolean;
+};
+/** `sbx.mounts`: your own S3, R2 or Google Cloud Storage bucket as a
+ * directory in this sandbox.
+ *
+ *   await sbx.mounts.add({ provider: "s3", bucket: "data", region: "eu-west-1",
+ *                          path: "/data", secret: "DATA_BUCKET" });
+ *
+ * A mount lasts through a pause and a wake, and ends when the sandbox stops. */
+export declare function sandboxMounts(t: Transport, sandbox: Sandbox): {
+    add: (input: MountBucket, options?: RequestOptions) => Promise<Mount>;
+    list: (options?: RequestOptions) => Promise<Mount[]>;
+    remove: (path: string, options?: RequestOptions) => Promise<{
+        path: string;
+        mounted: false;
+    }>;
+};

package/dist/products/mounts.js

@@ -0,0 +1,21 @@
+const enc = encodeURIComponent;
+/** `sbx.mounts`: your own S3, R2 or Google Cloud Storage bucket as a
+ * directory in this sandbox.
+ *
+ *   await sbx.mounts.add({ provider: "s3", bucket: "data", region: "eu-west-1",
+ *                          path: "/data", secret: "DATA_BUCKET" });
+ *
+ * A mount lasts through a pause and a wake, and ends when the sandbox stops. */
+export function sandboxMounts(t, sandbox) {
+    const base = () => `/v1/sandboxes/${enc(sandbox.id)}/mounts`;
+    return {
+        add: (input, options) => t.json({ method: "POST", path: base(), body: input, ...options }),
+        list: async (options) => (await t.json({ method: "GET", path: base(), ...options })).data,
+        remove: (path, options) => t.json({
+            method: "POST",
+            path: `${base()}:unmount`,
+            body: { path },
+            ...options,
+        }),
+    };
+}

package/dist/products/network-products.d.ts

@@ -0,0 +1,167 @@
+import type { RequestOptions, Transport } from "../transport.js";
+export type DnsRecord = {
+    type: string;
+    name: string;
+    value: string;
+    purpose: string;
+};
+export type Domain = {
+    id: string;
+    hostname: string;
+    sandboxId: string;
+    port: number;
+    /** pending until the TXT record proves the name is yours, then active. */
+    state: "pending" | "active" | "released";
+    url: string;
+    /** Turned off by Runtime after a report. */
+    disabled: boolean;
+    /** The TXT record that proves the name, and the CNAME (or A) that sends visitors here. */
+    records: DnsRecord[];
+    verifiedAt: string | null;
+    checkedAt: string | null;
+    checkError: string | null;
+    createdAt: string;
+};
+export type CheckedDomain = Domain & {
+    /** The name resolves to Runtime's edge now. */
+    pointed: boolean | null;
+    hint: string;
+};
+export type TcpPort = {
+    id: string;
+    sandboxId: string;
+    /** The port inside the sandbox. */
+    port: number;
+    address: string;
+    publicPort: number;
+    /** address:publicPort, for a client's host and port. */
+    connect: string;
+    protocol: "tcp";
+    disabled: boolean;
+    createdAt: string;
+};
+export type NetworkFunding = {
+    /** False disables traffic; the reservation remains until explicitly released. */
+    funded: boolean;
+    /** Last funded-through ISO timestamp, possibly past. Null means no meter exists. */
+    fundedUntil: string | null;
+    /** Immutable monthly quote in millionths of a US dollar. */
+    rateMicros: number;
+    rateUnit: "unit_month";
+};
+export type EgressAddress = NetworkFunding & {
+    id: string;
+    address: string;
+    family: 4 | 6;
+    createdAt: string;
+};
+export type TunnelPeer = {
+    id: string;
+    name: string;
+    publicKey: string;
+    /** The peer's address inside the tunnel's subnet. */
+    address: string;
+    /** Your own ranges behind the peer that sandboxes may reach through it. */
+    routes: string[];
+    createdAt: string;
+    rotatedAt: string | null;
+};
+export type Tunnel = NetworkFunding & {
+    id: string;
+    subnet: string;
+    gatewayAddress: string;
+    /** Where peers send WireGuard: address:udpPort. */
+    endpoint: string;
+    /** Null for a few seconds after creation. */
+    gatewayPublicKey: string | null;
+    disabled: boolean;
+    peers: TunnelPeer[];
+    /** Each sandbox's address in the tunnel. */
+    sandboxes: {
+        sandboxId: string;
+        name: string | null;
+        address: string;
+        state: string;
+    }[];
+    createdAt: string;
+};
+export type TunnelPeerCreated = {
+    tunnel: Tunnel;
+    peer: TunnelPeer;
+    /** A wg-quick file. It holds the private key only when Runtime generated it. */
+    config: string | null;
+    /** False means config is a draft preserving the private key; fill its gateway PublicKey before use. */
+    configReady: boolean;
+    hint: string;
+};
+/** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
+export declare function domains(t: Transport): {
+    /** Claims the hostname and answers the DNS records to set. Calling it again
+     * with another sandbox or port points the name there. */
+    add: (input: {
+        hostname: string;
+        sandboxId: string;
+        port: number;
+    }, options?: RequestOptions) => Promise<CheckedDomain>;
+    /** Checks the TXT record now; the name goes live when it matches. */
+    verify: (hostname: string, options?: RequestOptions) => Promise<CheckedDomain>;
+    get: (hostname: string, options?: RequestOptions) => Promise<Domain>;
+    list: (options?: RequestOptions) => Promise<Domain[]>;
+    remove: (hostname: string, options?: RequestOptions) => Promise<{
+        hostname: string;
+        deleted: true;
+    }>;
+};
+/** `runtime.ports`: a public TCP port to a port of a sandbox. */
+export declare function ports(t: Transport): {
+    /** Returns the same public port when called again for the same sandbox and port. */
+    open: (input: {
+        sandboxId: string;
+        port: number;
+    }, options?: RequestOptions) => Promise<TcpPort & {
+        hint: string;
+    }>;
+    list: (filter?: {
+        sandboxId?: string;
+    }, options?: RequestOptions) => Promise<TcpPort[]>;
+    close: (portId: string, options?: RequestOptions) => Promise<{
+        id: string;
+        deleted: true;
+    }>;
+};
+/** `runtime.addresses`: a dedicated outbound address every sandbox of the
+ * account sends from, for allow-lists. */
+export declare function addresses(t: Transport): {
+    reserve: (input?: {
+        family?: 4 | 6;
+    }, options?: RequestOptions) => Promise<EgressAddress>;
+    list: (options?: RequestOptions) => Promise<EgressAddress[]>;
+    release: (addressId: string, options?: RequestOptions) => Promise<{
+        id: string;
+        address: string;
+        deleted: true;
+    }>;
+};
+/** `runtime.tunnel`: a WireGuard tunnel from your own network into your sandboxes. */
+export declare function tunnel(t: Transport): {
+    get: (options?: RequestOptions) => Promise<Tunnel>;
+    /** Idempotent: returns the tunnel you have. */
+    create: (input?: {
+        subnet?: string;
+    }, options?: RequestOptions) => Promise<Tunnel>;
+    delete: (options?: RequestOptions) => Promise<{
+        id: string;
+        deleted: true;
+    }>;
+    /** Leave publicKey out and Runtime generates the pair; the private key is
+     * then in `config`, shown once. */
+    addPeer: (input: {
+        name: string;
+        publicKey?: string;
+        routes?: string[];
+    }, options?: RequestOptions) => Promise<TunnelPeerCreated>;
+    rotatePeer: (peerId: string, input?: {
+        publicKey?: string;
+    }, options?: RequestOptions) => Promise<TunnelPeerCreated>;
+    removePeer: (peerId: string, options?: RequestOptions) => Promise<Tunnel>;
+};

package/dist/products/network-products.js

@@ -0,0 +1,82 @@
+const enc = encodeURIComponent;
+/** `runtime.domains`: serve a sandbox's port at your own hostname, with HTTPS. */
+export function domains(t) {
+    return {
+        /** Claims the hostname and answers the DNS records to set. Calling it again
+         * with another sandbox or port points the name there. */
+        add: (input, options) => t.json({ method: "POST", path: "/v1/domains", body: input, ...options }),
+        /** Checks the TXT record now; the name goes live when it matches. */
+        verify: (hostname, options) => t.json({
+            method: "POST",
+            path: `/v1/domains/${enc(hostname)}:verify`,
+            ...options,
+        }),
+        get: (hostname, options) => t.json({ method: "GET", path: `/v1/domains/${enc(hostname)}`, ...options }),
+        list: async (options) => (await t.json({ method: "GET", path: "/v1/domains", ...options })).data,
+        remove: (hostname, options) => t.json({
+            method: "DELETE",
+            path: `/v1/domains/${enc(hostname)}`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.ports`: a public TCP port to a port of a sandbox. */
+export function ports(t) {
+    return {
+        /** Returns the same public port when called again for the same sandbox and port. */
+        open: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/ports",
+            body: input,
+            ...options,
+        }),
+        list: async (filter = {}, options) => (await t.json({
+            method: "GET",
+            path: `/v1/ports${filter.sandboxId ? `?sandboxId=${enc(filter.sandboxId)}` : ""}`,
+            ...options,
+        })).data,
+        close: (portId, options) => t.json({
+            method: "DELETE",
+            path: `/v1/ports/${enc(portId)}`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.addresses`: a dedicated outbound address every sandbox of the
+ * account sends from, for allow-lists. */
+export function addresses(t) {
+    return {
+        reserve: (input = {}, options) => t.json({ method: "POST", path: "/v1/addresses", body: input, ...options }),
+        list: async (options) => (await t.json({ method: "GET", path: "/v1/addresses", ...options }))
+            .data,
+        release: (addressId, options) => t.json({
+            method: "DELETE",
+            path: `/v1/addresses/${enc(addressId)}`,
+            ...options,
+        }),
+    };
+}
+/** `runtime.tunnel`: a WireGuard tunnel from your own network into your sandboxes. */
+export function tunnel(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/tunnel", ...options }),
+        /** Idempotent: returns the tunnel you have. */
+        create: (input = {}, options) => t.json({ method: "POST", path: "/v1/tunnel", body: input, ...options }),
+        delete: (options) => t.json({ method: "DELETE", path: "/v1/tunnel", ...options }),
+        /** Leave publicKey out and Runtime generates the pair; the private key is
+         * then in `config`, shown once. */
+        addPeer: (input, options) => t.json({
+            method: "POST",
+            path: "/v1/tunnel/peers",
+            body: input,
+            ...options,
+        }),
+        rotatePeer: (peerId, input = {}, options) => t.json({
+            method: "POST",
+            path: `/v1/tunnel/peers/${enc(peerId)}:rotate`,
+            body: input,
+            ...options,
+        }),
+        removePeer: (peerId, options) => t.json({ method: "DELETE", path: `/v1/tunnel/peers/${enc(peerId)}`, ...options }),
+    };
+}

package/dist/products/network.d.ts

@@ -24,7 +24,7 @@ export type NetworkPolicy = Required<NetworkRules> & {
     /** Ports reachable without a connect entry. */
     ports: number[];
     connectAllowed: boolean;
-    /** paid, granted, not_paid, revoked or suspended. */
+    /** paid, granted, not_paid, revoked, suspended, or trial (a trial sandbox reaches ports 80 and 443 only). */
     connectReason: string;
     forbiddenPorts: number[];
     updatedAt: string | null;

package/dist/products/sso.d.ts

@@ -0,0 +1,44 @@
+import type { RequestOptions, Transport } from "../transport.js";
+/** One identity provider of the account. */
+export type SsoConnection = {
+    id: string;
+    /** Names the connection in its sign-in URLs. */
+    providerId: string;
+    protocol: "oidc" | "saml";
+    provider: "okta" | "entra" | "google" | "other";
+    /** The email domain it answers for. */
+    domain: string;
+    /** When DNS proved the domain; null until then, and nobody signs in until then. */
+    domainVerifiedAt: string | null;
+    /** The TXT record that proves the domain. */
+    verification: {
+        type: "TXT";
+        name: string;
+        value: string;
+    };
+    defaultRole: "admin" | "developer" | "billing";
+    /** Members other than owners sign in only through it. API keys are unaffected. */
+    requireSso: boolean;
+    createdAt: string;
+};
+export type SsoStatus = {
+    connections: SsoConnection[];
+    scim: {
+        tokens: number;
+        users: number;
+        activeUsers: number;
+        groups: {
+            id: string;
+            displayName: string;
+            role: string | null;
+        }[];
+    };
+    /** Where an owner changes single sign-on. */
+    manage: string;
+};
+/** `runtime.sso.get()`: the account's single sign-on and SCIM directory sync.
+ * Read only; an owner changes it on the website. Needs a key made by an owner
+ * or admin. */
+export declare function sso(t: Transport): {
+    get: (options?: RequestOptions) => Promise<SsoStatus>;
+};

package/dist/products/sso.js

@@ -0,0 +1,8 @@
+/** `runtime.sso.get()`: the account's single sign-on and SCIM directory sync.
+ * Read only; an owner changes it on the website. Needs a key made by an owner
+ * or admin. */
+export function sso(t) {
+    return {
+        get: (options) => t.json({ method: "GET", path: "/v1/sso", ...options }),
+    };
+}

package/dist/products/switching.d.ts

@@ -52,7 +52,14 @@ export type UsageComparison = {
         runSeconds: number;
         activeCpuSeconds: number;
         unpricedSandboxes: number;
+        /** Of `sandboxes`, how many the free trial paid for, and their running
+         * time. The trial charged nothing for them; `runtimeMicros` prices them at
+         * Runtime's standard rates, what the same work costs on paid credit. */
+        trialSandboxes: number;
+        trialRunSeconds: number;
     };
+    /** What the usage costs on Runtime on paid credit: each paid sandbox at the
+     * rates it was quoted, a trial sandbox at the standard rates. */
     runtimeMicros: string;
     rivalMicros: string;
     /** Rival less Runtime: negative when the rival would cost less. */

package/dist/products/volumes.d.ts

@@ -13,8 +13,16 @@ export type Volume = {
     filesystem: "ext4";
     usedMiB: number | null;
     measuredAt: string | null;
-    /** Always false: a volume lives on one host and is not copied off it. */
-    backedUp: false;
+    /** True once a backup of it has been copied off its host and checked. */
+    backedUp: boolean;
+    /** Daily backups, how long each is kept, and when the newest was taken. */
+    backups: {
+        daily: boolean;
+        retentionDays: number;
+        lastReadyAt: string | null;
+    };
+    /** The backup this volume was restored from, if any. */
+    restoredFrom: string | null;
     attachments: {
         sandboxId: string;
         mode: "rw" | "snapshot";
@@ -26,15 +34,42 @@ export type Volume = {
     readyAt: string | null;
 };
 export type CreateVolume = {
-    sizeMiB: number;
+    /** Required unless restoring: a restore is the backup's size. */
+    sizeMiB?: number;
+    /** A ready backup to restore into the new volume, on any host in its region. */
+    fromBackup?: string;
     name?: string;
     labels?: Record<string, string>;
     region?: string;
 };
+export type VolumeBackupState = "pending" | "ready" | "failed" | "deleting" | "deleted";
+/** A point-in-time copy of a volume, kept off its host. */
+export type VolumeBackup = {
+    id: string;
+    kind: "volume-backup";
+    status: string;
+    state: VolumeBackupState;
+    name: string | null;
+    labels: Record<string, string>;
+    region: string;
+    volumeId: string;
+    sizeMiB: number;
+    trigger: "manual" | "daily";
+    retentionDays: number;
+    logicalBytes: number | null;
+    storedBytes: number | null;
+    meteredBytes: number | null;
+    error: string | null;
+    createdAt: string;
+    readyAt: string | null;
+    expiresAt: string;
+};
 /** Persistent disks: create once, attach when creating a sandbox with
- * `volumes: [{ volumeId: v.id, path: "/data" }]`. Not backed up off its host. */
+ * `volumes: [{ volumeId: v.id, path: "/data" }]`. Backed up off their host
+ * daily unless that is turned off; restore one with `create({ fromBackup })`. */
 export declare function volumes(t: Transport): {
-    /** Create and wait (up to 10 s) until it is ready. */
+    /** Create and wait (up to 10 s) until it is ready. With `fromBackup`, a
+     * restore; it is ready once the backup is downloaded and checked. */
     create: (input: CreateVolume, options?: RequestOptions) => Promise<Volume>;
     get: (id: string, options?: RequestOptions) => Promise<Volume>;
     list: (query?: {
@@ -44,4 +79,32 @@ export declare function volumes(t: Transport): {
         cursor?: string;
     }, options?: RequestOptions) => Promise<Page<Volume>>;
     delete: (id: string, options?: RequestOptions) => Promise<Volume>;
+    /** Back a volume up now, off its host, and wait (up to a minute, or
+     * `wait` seconds) for it to be ready. */
+    backup: (id: string, input?: {
+        name?: string;
+        labels?: Record<string, string>;
+        retentionDays?: number;
+    }, options?: RequestOptions & {
+        wait?: number;
+    }) => Promise<VolumeBackup>;
+    /** Daily backups on or off, and how many days each is kept. */
+    setBackupPolicy: (id: string, input: {
+        daily?: boolean;
+        retentionDays?: number;
+    }, options?: RequestOptions) => Promise<Volume>;
+    /** Backups, newest first; `{ volumeId }` for one volume's. */
+    backups: (query?: {
+        volumeId?: string;
+        state?: Exclude<VolumeBackupState, "deleted">;
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions) => Promise<Page<VolumeBackup>>;
+    getBackup: (id: string, options?: RequestOptions) => Promise<VolumeBackup>;
+    deleteBackup: (id: string, options?: RequestOptions) => Promise<VolumeBackup>;
+    /** A new volume from a backup: `create({ fromBackup: id })`. */
+    restore: (backupId: string, input?: {
+        name?: string;
+        labels?: Record<string, string>;
+    }, options?: RequestOptions) => Promise<Volume>;
 };