@claxedo/sandbox-manager 0.9.0 → 0.10.1

package/dist/driver-billing.d.ts

@@ -0,0 +1,29 @@
+import type { SandboxMachineClass } from "@claxedo/sandbox-contract";
+/** One size a provider sells, as its own catalog names and prices it. */
+export type SandboxMachineRate = {
+    /** The provider's own name for the size. */
+    size: string;
+    vcpu: number;
+    memoryGb: number;
+    usdPerHour: number;
+};
+/**
+ * How a provider bills the machine a sandbox runs on, read from its published
+ * pricing. `rates.default` is also the one size of a driver that offers no
+ * choice. `excludes` names a component the hourly rate leaves out because the
+ * provider meters it on use rather than on time.
+ */
+export type SandboxDriverBilling = {
+    source: {
+        url: string;
+        readOn: string;
+    };
+    meter: string;
+    rates: Partial<Record<SandboxMachineClass, SandboxMachineRate>>;
+    excludes?: string;
+};
+export declare const boatBilling: SandboxDriverBilling;
+export declare const cloudflareBilling: SandboxDriverBilling;
+/** The rate a sandbox of this class runs at; a driver with one size answers it for the class it was not asked for. */
+export declare function sandboxMachineRate(billing: SandboxDriverBilling | undefined, machineClass: SandboxMachineClass | null): SandboxMachineRate | undefined;
+export declare function sandboxMachineCostUsd(rate: SandboxMachineRate, activeMs: number): number;

package/dist/driver-catalog.d.ts

@@ -1,8 +1,10 @@
-import { validateSandboxPersistenceCapabilities, type SandboxDriverMetadata } from "./index";
-import { defaultSandboxDriverID, listSandboxDrivers, sandboxDriverId, type SandboxDriverAuth, type SandboxDriverConfig, type SandboxDriverEnv, type SandboxDriverID } from "@claxedo/sandbox-contract";
-export { defaultSandboxDriverID, listSandboxDrivers, sandboxDriverId };
-export type SandboxDriverCatalogEntry = {
-    id: SandboxDriverID;
+import { validateSandboxPersistenceCapabilities, type SandboxDriverMetadata } from "./contract";
+import { type SandboxDriverBilling } from "./driver-billing";
+import { sandboxDriverId, type SandboxDriverEnv, type SandboxDriverID } from "@claxedo/sandbox-contract";
+export { sandboxDriverId };
+export { sandboxMachineCostUsd, sandboxMachineRate, type SandboxDriverBilling, type SandboxMachineRate } from "./driver-billing";
+export type SandboxDriverCatalogEntry<ID extends string = SandboxDriverID> = {
+    id: ID;
     label: string;
     metadata: SandboxDriverMetadata;
     credentialFields: ReadonlyArray<{
@@ -10,9 +12,42 @@ export type SandboxDriverCatalogEntry = {
         label: string;
         secret?: boolean;
     }>;
+    runtimeNetwork: {
+        controlPlane: "docker-host" | "direct";
+        relay: "configured" | "local";
+    };
+    runtimeEnv: "ensure" | "callback";
+    preparedImage: boolean;
+    /** Absent where no published rate for the machines this driver places on has been established. */
+    billing?: SandboxDriverBilling;
 };
 export { validateSandboxPersistenceCapabilities };
+export declare const localBrokeringTestDriverCatalogEntry: {
+    readonly id: "local-brokering-test";
+    readonly label: "Local brokering test driver";
+    readonly credentialFields: readonly [];
+    readonly runtimeNetwork: {
+        readonly controlPlane: "direct";
+        readonly relay: "local";
+    };
+    readonly runtimeEnv: "ensure";
+    readonly preparedImage: false;
+    readonly metadata: {
+        readonly driverRunsIn: ["local"];
+        readonly hostStopBehavior: "terminates-host";
+        readonly hostResumeBehavior: "same-host";
+        readonly targetAccess: "loopback";
+        readonly secretBrokering: "native";
+        readonly egressControl: "hosts";
+        readonly persistence: {
+            readonly resume: "same-sandbox";
+            readonly capture: "none";
+            readonly clone: false;
+            readonly captureSource: "not-applicable";
+            readonly retention: "provider-managed";
+            readonly restoreMount: "same-resource";
+        };
+    };
+};
 export declare const sandboxDriverCatalog: Record<SandboxDriverID, SandboxDriverCatalogEntry>;
-export declare function sandboxDriverAuth<T extends SandboxDriverID>(cfg: SandboxDriverConfig | undefined, id: T, env?: SandboxDriverEnv): SandboxDriverAuth[T] | undefined;
-export declare function hasSandboxDriverAuth(cfg: SandboxDriverConfig | undefined, id: SandboxDriverID, env?: SandboxDriverEnv): boolean;
 export declare function dockerSandboxDriverEnabled(env?: SandboxDriverEnv): boolean;

package/dist/driver-catalog.mjs

@@ -1,30 +1,4 @@
-// src/hosted-network-policy.ts
-var SANDBOX_MODEL_PROVIDER_HOSTS = [
-  "api.anthropic.com",
-  "api.openai.com",
-  "generativelanguage.googleapis.com",
-  "openrouter.ai",
-  // Model catalog + engine config, fetched on runner startup.
-  "models.dev",
-  "opencode.ai"
-];
-var SANDBOX_PACKAGE_REGISTRY_HOSTS = [
-  "registry.npmjs.org",
-  "nodejs.org",
-  "pypi.org",
-  "files.pythonhosted.org",
-  "crates.io",
-  "static.crates.io",
-  "index.crates.io",
-  "proxy.golang.org",
-  "sum.golang.org"
-];
-var SANDBOX_BASELINE_EGRESS_HOSTS = [
-  ...SANDBOX_MODEL_PROVIDER_HOSTS,
-  ...SANDBOX_PACKAGE_REGISTRY_HOSTS
-];
-
-// src/index.ts
+// src/contract.ts
 function validateSandboxPersistenceCapabilities(input) {
   if (input.resume === "replacement-restore" && input.capture === "none") {
     return { valid: false, reason: "replacement restore requires a capture source" };
@@ -38,34 +12,43 @@ function validateSandboxPersistenceCapabilities(input) {
   if (input.capture === "same-resource" && input.restoreMount !== "same-resource") {
     return { valid: false, reason: "same-resource capture requires same-resource restore" };
   }
-  if (input.restoreMount === "copy-on-write" && input.capture !== "directories") {
-    return { valid: false, reason: "copy-on-write restore requires directory capture" };
-  }
   return { valid: true };
 }
 
-// src/runtime-version.ts
-var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
-function workspaceRuntimeVersion() {
-  return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
-}
-
-// src/image-name.ts
-var SNAPSHOT_SCHEMA_VERSION = 8;
-var DEFAULT_SANDBOX_IMAGE_REPOSITORY = "ghcr.io/kyashrathore/claxedo-sandbox";
-function snapshotVersion(value) {
-  return value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
-}
-function sandboxImageRepository(env = process.env) {
-  const repository = env.CLAXEDO_SANDBOX_IMAGE_REPOSITORY?.trim();
-  return repository ? repository : DEFAULT_SANDBOX_IMAGE_REPOSITORY;
-}
-function buildIdSuffix(buildId, env) {
-  const id = (buildId ?? env.CLAXEDO_SANDBOX_BUILD_ID)?.trim();
-  return id ? `-${snapshotVersion(id)}` : "";
+// src/driver-billing.ts
+var HOUR_SECONDS = 3600;
+var boatBilling = {
+  source: { url: "https://docs.boat.dev/pricing", readOn: "2026-10-12" },
+  meter: "Boat bills machine time per second while a sandbox runs, at an hourly rate per size; a stopped sandbox costs nothing.",
+  rates: {
+    small: { size: "small", vcpu: 2, memoryGb: 4, usdPerHour: 0.018 },
+    default: { size: "default", vcpu: 4, memoryGb: 8, usdPerHour: 0.036 },
+    large: { size: "large", vcpu: 8, memoryGb: 16, usdPerHour: 0.072 }
+  }
+};
+var CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY = 25e-7;
+var CLOUDFLARE_USD_PER_GB_SECOND_DISK = 7e-8;
+var CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE = 2e-5;
+var CLOUDFLARE_STANDARD_1 = { size: "standard-1", vcpu: 0.5, memoryGb: 4, diskGb: 8 };
+var cloudflareBilling = {
+  source: { url: "https://developers.cloudflare.com/containers/pricing/", readOn: "2026-10-12" },
+  meter: "Cloudflare bills a container for every 10 ms it runs: memory at $0.0000025 per GiB-second and disk at $0.00000007 per GB-second for the whole run, plus CPU at $0.00002 per vCPU-second of active use.",
+  rates: {
+    default: {
+      size: CLOUDFLARE_STANDARD_1.size,
+      vcpu: CLOUDFLARE_STANDARD_1.vcpu,
+      memoryGb: CLOUDFLARE_STANDARD_1.memoryGb,
+      usdPerHour: (CLOUDFLARE_STANDARD_1.memoryGb * CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY + CLOUDFLARE_STANDARD_1.diskGb * CLOUDFLARE_USD_PER_GB_SECOND_DISK) * HOUR_SECONDS
+    }
+  },
+  excludes: `active CPU, billed at $${CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE} per vCPU-second and not measured by Claxedo, and the monthly allowance a Workers Paid plan includes`
+};
+function sandboxMachineRate(billing, machineClass) {
+  if (!billing) return void 0;
+  return billing.rates[machineClass ?? "default"] ?? (Object.keys(billing.rates).length === 1 ? billing.rates.default : void 0);
 }
-function defaultSandboxImage(version = workspaceRuntimeVersion(), buildId, env = process.env) {
-  return `${sandboxImageRepository(env)}:workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+function sandboxMachineCostUsd(rate, activeMs) {
+  return rate.usdPerHour * activeMs / (HOUR_SECONDS * 1e3);
 }
 
 // ../sandbox-contract/dist/index.mjs
@@ -78,10 +61,8 @@ function trimToUndefined(value) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
-var sandboxDriverIds = ["exe", "daytona", "modal", "vercel", "cloudflare", "box", "docker"];
+var sandboxDriverIds = ["modal", "vercel", "cloudflare", "boat", "docker"];
 var sandboxDriverCredentialFields = {
-  exe: [{ key: "api_token", label: "API Token", secret: true }],
-  daytona: [{ key: "api_key", label: "API Key", secret: true }],
   modal: [
     { key: "token_id", label: "Token ID", secret: true },
     { key: "token_secret", label: "Token Secret", secret: true }
@@ -95,16 +76,14 @@ var sandboxDriverCredentialFields = {
     { key: "api_token", label: "API Token", secret: true },
     { key: "worker_url", label: "Worker URL" }
   ],
-  box: [{ key: "api_key", label: "API Key", secret: true }],
+  boat: [{ key: "api_key", label: "API Key", secret: true }],
   docker: [{ key: "image", label: "Image" }]
 };
 var sandboxDriverLabels = {
-  exe: "exe.dev",
-  daytona: "Daytona",
   modal: "Modal",
   vercel: "Vercel",
   cloudflare: "Cloudflare",
-  box: "Box",
+  boat: "Boat",
   docker: "Docker"
 };
 function isSandboxDriverID(input) {
@@ -117,14 +96,6 @@ function dockerSandboxDriverEnabled(env = process.env) {
   return enabled(env.CLAXEDO_ENABLE_DOCKER_SANDBOX) || enabled(env.CLAXEDO_DEV_DOCKER_SANDBOX);
 }
 function sandboxDriverAuthValues(cfg, id, env = process.env) {
-  if (id === "daytona") {
-    const api_key = trimToUndefined(cfg?.auth?.daytona?.api_key);
-    return api_key ? { api_key } : void 0;
-  }
-  if (id === "exe") {
-    const api_token = trimToUndefined(cfg?.auth?.exe?.api_token) ?? trimToUndefined(env.EXE_DEV_API_TOKEN);
-    return api_token ? { api_token } : void 0;
-  }
   if (id === "modal") {
     const token_id = trimToUndefined(cfg?.auth?.modal?.token_id) ?? trimToUndefined(env.MODAL_TOKEN_ID);
     const token_secret = trimToUndefined(cfg?.auth?.modal?.token_secret) ?? trimToUndefined(env.MODAL_TOKEN_SECRET);
@@ -138,93 +109,72 @@ function sandboxDriverAuthValues(cfg, id, env = process.env) {
   }
   if (id === "cloudflare") {
     const api_token = trimToUndefined(cfg?.auth?.cloudflare?.api_token) ?? trimToUndefined(env.CLOUDFLARE_API_TOKEN);
-    const worker_url = trimToUndefined(cfg?.auth?.cloudflare?.worker_url) ?? trimToUndefined(env.CLOUDFLARE_SANDBOX_WORKER_URL);
+    const configuredUrl = trimToUndefined(cfg?.auth?.cloudflare?.worker_url) ?? trimToUndefined(env.CLOUDFLARE_SANDBOX_WORKER_URL);
+    const worker_url = configuredUrl ? cloudflareWorkerBaseUrl(configuredUrl) : void 0;
     return api_token && worker_url ? { api_token, worker_url } : void 0;
   }
-  if (id === "box") {
-    const api_key = trimToUndefined(cfg?.auth?.box?.api_key) ?? trimToUndefined(env.BOX_API_KEY);
+  if (id === "boat") {
+    const api_key = trimToUndefined(cfg?.auth?.boat?.api_key) ?? trimToUndefined(env.BOAT_API_KEY);
     return api_key ? { api_key } : void 0;
   }
-  if (!dockerSandboxDriverEnabled(env)) return void 0;
+  if (!dockerSandboxDriverEnabled(env))
+    return;
   const image = trimToUndefined(cfg?.auth?.docker?.image) ?? trimToUndefined(env.CLAXEDO_DOCKER_SANDBOX_IMAGE) ?? trimToUndefined(env.CLAXEDO_SANDBOX_IMAGE);
   return image ? { image } : {};
 }
+function cloudflareWorkerBaseUrl(input) {
+  let url;
+  try {
+    url = new URL(input.trim());
+  } catch {
+    throw new Error("Cloudflare Worker URL must be a valid HTTPS endpoint");
+  }
+  if (url.protocol !== "https:" || url.username || url.password || input.includes("?") || input.includes("#")) {
+    throw new Error("Cloudflare Worker URL requires HTTPS without credentials, query or fragment");
+  }
+  return url.origin + url.pathname.replace(/\/+$/, "");
+}
 function sandboxDriverId(input, cfg, env = process.env) {
-  if (!isSandboxDriverID(input)) return void 0;
-  if (input === "docker" && !sandboxDriverAuthValues(cfg, input, env)) return void 0;
+  if (!isSandboxDriverID(input))
+    return;
+  if (input === "docker" && !sandboxDriverAuthValues(cfg, input, env))
+    return;
   return input;
 }
-function defaultSandboxDriverID(cfg, env = process.env) {
-  return sandboxDriverId(cfg?.default_driver, cfg, env) ?? (enabled(env.CLAXEDO_DOCKER_SANDBOX_DEFAULT) && sandboxDriverAuthValues(cfg, "docker", env) ? "docker" : "daytona");
-}
-function listSandboxDrivers(cfg, env = process.env, managedDriverIds = /* @__PURE__ */ new Set()) {
-  const defaultDriver = defaultSandboxDriverID(cfg, env);
-  return {
-    default_driver: defaultDriver,
-    drivers: sandboxDriverIds.filter((id) => id !== "docker" || !!sandboxDriverAuthValues(cfg, "docker", env)).map((id) => {
-      const configuredFromConfigOrEnv = !!sandboxDriverAuthValues(cfg, id, env);
-      const configured = id === "docker" ? configuredFromConfigOrEnv : configuredFromConfigOrEnv || managedDriverIds.has(id);
-      return {
-        id,
-        label: sandboxDriverLabels[id],
-        fields: sandboxDriverCredentialFields[id],
-        configured,
-        source: configuredFromConfigOrEnv ? "config" : configured ? "managed" : "none",
-        default: id === defaultDriver
-      };
-    })
-  };
-}
 
 // src/driver-catalog.ts
-var sandboxDriverCatalog = {
-  exe: {
-    id: "exe",
-    label: sandboxDriverLabels.exe,
-    credentialFields: sandboxDriverCredentialFields.exe,
-    metadata: {
-      driverRunsIn: ["worker", "node"],
-      hostStopBehavior: "not-supported",
-      hostResumeBehavior: "same-host",
-      targetAccess: "relay",
-      secretBrokering: "none",
-      egressControl: "none",
-      persistence: {
-        resume: "same-sandbox",
-        capture: "none",
-        clone: true,
-        captureSource: "not-applicable",
-        retention: "provider-managed",
-        restoreMount: "same-resource"
-      }
-    }
-  },
-  daytona: {
-    id: "daytona",
-    label: sandboxDriverLabels.daytona,
-    credentialFields: sandboxDriverCredentialFields.daytona,
-    metadata: {
-      driverRunsIn: ["worker", "node"],
-      hostStopBehavior: "suspends-host",
-      hostResumeBehavior: "same-host",
-      targetAccess: "relay",
-      secretBrokering: "native",
-      // The driver translates names to domainAllowList, or addresses to networkAllowList.
-      egressControl: "hosts-and-cidrs",
-      persistence: {
-        resume: "same-sandbox",
-        capture: "filesystem",
-        clone: false,
-        captureSource: "preserved",
-        retention: "provider-managed",
-        restoreMount: "new-resource"
-      }
+var localBrokeringTestDriverCatalogEntry = {
+  id: "local-brokering-test",
+  label: "Local brokering test driver",
+  credentialFields: [],
+  runtimeNetwork: { controlPlane: "direct", relay: "local" },
+  runtimeEnv: "ensure",
+  preparedImage: false,
+  metadata: {
+    driverRunsIn: ["local"],
+    hostStopBehavior: "terminates-host",
+    hostResumeBehavior: "same-host",
+    targetAccess: "loopback",
+    secretBrokering: "native",
+    egressControl: "hosts",
+    persistence: {
+      resume: "same-sandbox",
+      capture: "none",
+      clone: false,
+      captureSource: "not-applicable",
+      retention: "provider-managed",
+      restoreMount: "same-resource"
     }
-  },
+  }
+};
+var sandboxDriverCatalog = {
   modal: {
     id: "modal",
     label: sandboxDriverLabels.modal,
     credentialFields: sandboxDriverCredentialFields.modal,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
@@ -247,6 +197,9 @@ var sandboxDriverCatalog = {
     id: "vercel",
     label: sandboxDriverLabels.vercel,
     credentialFields: sandboxDriverCredentialFields.vercel,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
     metadata: {
       driverRunsIn: ["node"],
       hostStopBehavior: "terminates-host",
@@ -269,30 +222,40 @@ var sandboxDriverCatalog = {
     id: "cloudflare",
     label: sandboxDriverLabels.cloudflare,
     credentialFields: sandboxDriverCredentialFields.cloudflare,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: false,
+    billing: cloudflareBilling,
     metadata: {
       driverRunsIn: ["worker"],
-      hostStopBehavior: "not-supported",
+      hostStopBehavior: "terminates-host",
       hostResumeBehavior: "same-host",
+      hostWatchesIdle: true,
       targetAccess: "relay",
       secretBrokering: "native",
       // Credential handlers do not restrict unrelated destinations.
       egressControl: "none",
+      // A container snapshot holds the whole root filesystem; the platform keeps it 30 days past its last restore and offers no deletion.
       persistence: {
         resume: "replacement-restore",
-        capture: "directories",
+        capture: "filesystem",
         clone: false,
         captureSource: "preserved",
         retention: "provider-managed",
-        restoreMount: "copy-on-write"
+        restoreMount: "new-resource"
       }
     }
   },
-  box: {
-    id: "box",
-    label: sandboxDriverLabels.box,
-    credentialFields: sandboxDriverCredentialFields.box,
+  boat: {
+    id: "boat",
+    label: sandboxDriverLabels.boat,
+    credentialFields: sandboxDriverCredentialFields.boat,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
+    billing: boatBilling,
     metadata: {
-      driverRunsIn: ["node"],
+      driverRunsIn: ["worker", "node"],
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
@@ -305,13 +268,17 @@ var sandboxDriverCatalog = {
         captureSource: "not-applicable",
         retention: "provider-managed",
         restoreMount: "same-resource"
-      }
+      },
+      machineClasses: ["small", "default", "large"]
     }
   },
   docker: {
     id: "docker",
     label: sandboxDriverLabels.docker,
     credentialFields: sandboxDriverCredentialFields.docker,
+    runtimeNetwork: { controlPlane: "docker-host", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
     metadata: {
       driverRunsIn: ["local"],
       hostStopBehavior: "terminates-host",
@@ -330,28 +297,15 @@ var sandboxDriverCatalog = {
     }
   }
 };
-function sandboxDriverAuth(cfg, id, env = process.env) {
-  if (id === "docker") {
-    const configured = sandboxDriverAuthValues(cfg, "docker", env);
-    if (!configured) return void 0;
-    const image = configured.image ?? defaultSandboxImage(workspaceRuntimeVersion(), void 0, env);
-    return { image };
-  }
-  return sandboxDriverAuthValues(cfg, id, env);
-}
-function hasSandboxDriverAuth(cfg, id, env = process.env) {
-  return !!sandboxDriverAuth(cfg, id, env);
-}
 function dockerSandboxDriverEnabled2(env = process.env) {
   return dockerSandboxDriverEnabled(env);
 }
 export {
-  defaultSandboxDriverID,
   dockerSandboxDriverEnabled2 as dockerSandboxDriverEnabled,
-  hasSandboxDriverAuth,
-  listSandboxDrivers,
-  sandboxDriverAuth,
+  localBrokeringTestDriverCatalogEntry,
   sandboxDriverCatalog,
   sandboxDriverId,
+  sandboxMachineCostUsd,
+  sandboxMachineRate,
   validateSandboxPersistenceCapabilities
 };

package/dist/drivers/boat-client.d.ts

@@ -0,0 +1,95 @@
+import type { SandboxMachineClass } from "@claxedo/sandbox-contract";
+import { type SandboxStartLimit, type SandboxStartWindow } from "../lease-failure";
+export type BoatSandboxState = "init" | "provisioning" | "provisioned" | "cloning" | "ready" | "idle" | "running" | "archiving" | "archived" | "error" | "cancelled";
+/** `hydrated`: Boat has downloaded every file of the snapshot the sandbox started from (docs.boat.dev/readiness). */
+export type BoatSandbox = {
+    id: string;
+    state: BoatSandboxState;
+    hydrated: boolean;
+};
+export type BoatCommandResult = {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+};
+export type BoatFetch = (input: string, init?: RequestInit) => Promise<Response>;
+/**
+ * What Boat's 429 `rate_limited` says about the account's start limit: the
+ * window that is used up, its limit, and the starts used of each window. It
+ * names no time the window reopens (2026-10-15), so none is kept.
+ */
+export type BoatStartLimit = {
+    window: SandboxStartWindow;
+    limit: number;
+    starts: Partial<Record<SandboxStartWindow, {
+        limit: number;
+        used: number;
+    }>>;
+};
+export declare class BoatApiError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    /** Boat answers 401 or 403 to the API key itself, never to a sandbox it was asked about. */
+    readonly providerKeyRefused: boolean;
+    /** Create, fork and resume each count as one start (Boat's own refusal, 2026-10-15). */
+    readonly providerRateLimited?: SandboxStartLimit;
+    readonly startLimit?: BoatStartLimit;
+    /** The state Boat's refusal gives the sandbox it refused, e.g. `archived` on a 400 `stop_failed` (2026-10-17). */
+    readonly sandboxState?: BoatSandboxState;
+    constructor(message: string, code: string, status?: number | undefined, refusal?: {
+        startLimit?: BoatStartLimit;
+        sandboxState?: BoatSandboxState;
+    });
+}
+export declare function invalid(): never;
+export declare function requiredText(value: unknown): string;
+export type BoatClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: BoatFetch;
+};
+export type BoatApi = ReturnType<typeof createBoatApi>;
+/** One Boat v1 call: the bearer key, the deadline, the bounded envelope, and the envelope types the call accepts. */
+export declare function createBoatApi(options: BoatClientOptions): (path: string, types: readonly string[], init?: {
+    method?: string;
+    body?: unknown;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}) => Promise<Record<string, unknown>>;
+export declare function createBoatClient(options: BoatClientOptions): {
+    /** `from` is a named snapshot or a share code (`bsh_…`) the sandbox starts from; omitted, Boat's base machine. */
+    create(input: {
+        idempotencyKey: string;
+        ttlSeconds: number | null;
+        type?: SandboxMachineClass;
+        from?: string;
+    }): Promise<BoatSandbox>;
+    get(id: string): Promise<BoatSandbox>;
+    /** `type` resumes the sandbox onto that machine size; omitted, it keeps the size it has (docs.boat.dev/machines/change-size). */
+    resume(id: string, input: {
+        ttlSeconds: number | null;
+        type?: SandboxMachineClass;
+    }): Promise<void>;
+    /**
+     * `ttlSeconds` sets the auto-stop deadline to now plus that many seconds; `null` removes it.
+     * Boat's reference example answers `sandbox.info`; the API answers `sandbox.updated` (2026-10-13).
+     */
+    update(id: string, input: {
+        ttlSeconds: number | null;
+    }): Promise<BoatSandbox>;
+    stop(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    writeFile(id: string, input: {
+        path: string;
+        content: string;
+    }): Promise<void>;
+    /** `ready` once a command runs, which Boat answers the moment the sandbox is ready; `starting` when Boat's hold ended first. */
+    whenReady(id: string): Promise<"ready" | "starting">;
+    command(id: string, input: {
+        command: string;
+        timeoutSeconds?: number;
+    }): Promise<BoatCommandResult>;
+};

package/dist/drivers/boat-named-snapshots.d.ts

@@ -0,0 +1,31 @@
+import { type BoatClientOptions } from "./boat-client";
+export type BoatNamedSnapshotStatus = "saving" | "ready" | "failed";
+export type BoatNamedSnapshot = {
+    name: string;
+    status: BoatNamedSnapshotStatus;
+    createdAt: string;
+};
+export type BoatSnapshotShare = {
+    id: string;
+    status: "active" | "revoked";
+    createdAt: string;
+};
+/** Boat's named snapshots and their share codes (docs.boat.dev/snapshots/templates). */
+export declare function createBoatNamedSnapshotClient(options: BoatClientOptions): {
+    /** A stopped sandbox is saved from its last snapshot; the save settles in the background. */
+    save(input: {
+        sandboxId: string;
+        name: string;
+    }): Promise<BoatNamedSnapshot>;
+    get(name: string): Promise<BoatNamedSnapshot | undefined>;
+    /** Newest first. */
+    list(): Promise<BoatNamedSnapshot[]>;
+    delete(name: string): Promise<void>;
+    /** Boat shows the code only in this answer and keeps a hash of it. */
+    share(name: string): Promise<{
+        shareCode: string;
+        share: BoatSnapshotShare;
+    }>;
+    shares(name: string): Promise<BoatSnapshotShare[]>;
+    revokeShare(name: string, shareId: string): Promise<void>;
+};

package/dist/drivers/boat-template.d.ts

@@ -0,0 +1,49 @@
+import { type BoatRuntimeTemplate, type BoatSandboxDriverOptions } from "./boat";
+import { type BoatClientOptions } from "./boat-client";
+export type BoatRuntimeTemplateOptions = BoatClientOptions & {
+    image: string;
+    /** Template names start with it, and pruning removes only names that do. */
+    prefix?: string;
+    /** How many templates of the prefix pruning keeps, the image's own and the newest others. */
+    keep?: number;
+    log?: (line: string) => void;
+    pollIntervalMs?: number;
+    hydrationTimeoutMs?: number;
+    stopTimeoutMs?: number;
+    saveTimeoutMs?: number;
+    driver?: Pick<BoatSandboxDriverOptions, "statePollMs" | "provisionTimeoutMs" | "healthIntervalMs" | "healthTimeoutMs">;
+};
+/** The image reference is content-addressed (its tag names the build), and the seeded trees are named by it, so it keys the template. */
+export declare function boatRuntimeTemplateName(image: string, prefix?: string): Promise<string>;
+/**
+ * Saves the template once per image: a ready template is reused, one still
+ * saving is waited for, and a missing or failed one is built on a builder
+ * sandbox that is deleted whatever the outcome.
+ */
+export declare function ensureBoatRuntimeTemplate(options: BoatRuntimeTemplateOptions): Promise<{
+    name: string;
+    built: boolean;
+}>;
+/**
+ * A new share code for the image's template, revoking none: until the deploy
+ * that carries it has succeeded, the running Worker creates with the code it
+ * holds. `shareId` names the code without being the secret.
+ */
+export declare function shareBoatRuntimeTemplate(options: BoatRuntimeTemplateOptions): Promise<{
+    template: BoatRuntimeTemplate;
+    shareId: string;
+}>;
+/**
+ * Run once the deploy carrying `deployedShareId` succeeded: every other code of
+ * the deployed image's template is revoked, those of earlier deploys and of
+ * deploys that failed alike.
+ */
+export declare function revokeBoatRuntimeTemplateShares(options: BoatRuntimeTemplateOptions, deployedShareId: string): Promise<string[]>;
+/**
+ * Run once the deploy of `options.image` succeeded, so the template it keeps
+ * is the one the live Worker creates from. Each template past Boat's ten free
+ * named snapshots costs $1.70 a month, and a template serves only the image it
+ * was built for, so templates of the prefix beyond the newest `keep` (the
+ * deployed image's among them) are removed; Boat removes their codes with them.
+ */
+export declare function pruneBoatRuntimeTemplates(options: BoatRuntimeTemplateOptions): Promise<string[]>;