@claxedo/sandbox-manager 0.6.0 → 0.7.0

package/dist/drivers/box.mjs

@@ -30,16 +30,8 @@ import { Image, DaytonaNotFoundError } from "@daytona/sdk";
 
 // src/runtime-version.ts
 var DEFAULT_WORKSPACE_RUNTIME_VERSION = "0.5.2";
-var versionCache;
 function workspaceRuntimeVersion() {
-  if (versionCache) return versionCache;
-  const envVersion = process.env.WORKSPACE_RUNTIME_VERSION;
-  if (envVersion) {
-    versionCache = envVersion;
-    return versionCache;
-  }
-  versionCache = DEFAULT_WORKSPACE_RUNTIME_VERSION;
-  return versionCache;
+  return process.env.WORKSPACE_RUNTIME_VERSION || DEFAULT_WORKSPACE_RUNTIME_VERSION;
 }
 
 // src/image-name.ts
@@ -68,6 +60,207 @@ var SANDBOX_IMAGE_REPOSITORY = sandboxImageRepository();
 var SANDBOX_IMAGE = process.env.CLAXEDO_SANDBOX_IMAGE || defaultSandboxImage();
 var SNAPSHOT_NAME = process.env.CLAXEDO_SNAPSHOT_NAME || defaultSnapshotName();
 
+// 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/driver-catalog.ts
+var sandboxDriverCatalog = {
+  exe: {
+    id: "exe",
+    label: "exe.dev",
+    credentialFields: [{ key: "api_token", label: "API Token", secret: true }],
+    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: "Daytona",
+    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // Daytona is the only driver that can filter egress by NAME as well as
+      // by address: `domainAllowList` (names) alongside `networkAllowList`
+      // (CIDRs), with `networkBlockAll` as the deny-all floor.
+      egressControl: "hosts-and-cidrs",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  modal: {
+    id: "modal",
+    label: "Modal",
+    credentialFields: [
+      { key: "token_id", label: "Token ID", secret: true },
+      { key: "token_secret", label: "Token Secret", secret: true }
+    ],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      // Modal can cut the network entirely (`blockNetwork`) but cannot express
+      // an allowlist, and its driver throws on a host policy. A blackout is
+      // not containment for a workspace that has to clone and reach a model.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  vercel: {
+    id: "vercel",
+    label: "Vercel",
+    credentialFields: [
+      { key: "access_token", label: "Access Token", secret: true },
+      { key: "team_id", label: "Team ID" },
+      { key: "project_id", label: "Project ID" }
+    ],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // Vercel's sandbox firewall takes a hostname allow list (or "deny-all"),
+      // never CIDRs.
+      egressControl: "hosts",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "stopped",
+        retention: "explicit",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  cloudflare: {
+    id: "cloudflare",
+    label: "Cloudflare",
+    credentialFields: [
+      { key: "api_token", label: "API Token", secret: true },
+      { key: "worker_url", label: "Worker URL" }
+    ],
+    metadata: {
+      driverRunsIn: ["worker"],
+      hostStopBehavior: "not-supported",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "proxy",
+      // The Cloudflare Sandbox Worker exposes no egress filter: its broker
+      // (drivers/cloudflare-egress.ts) is an OPT-IN proxy the sandbox chooses
+      // to route brokered-credential requests through, not a boundary. The
+      // driver therefore drops `net` entirely — which is exactly why this
+      // must be declared, so the manager refuses instead of provisioning a
+      // sandbox the caller believes is contained.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "directories",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "copy-on-write"
+      }
+    }
+  },
+  box: {
+    id: "box",
+    label: "Box",
+    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: false,
+        captureSource: "not-applicable",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
+  },
+  docker: {
+    id: "docker",
+    label: "Docker",
+    credentialFields: [{ key: "image", label: "Image" }],
+    metadata: {
+      driverRunsIn: ["local"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "loopback",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "same-resource",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
+  }
+};
+
 // src/drivers/box.ts
 var DEFAULT_BASE_URL = "https://ascii.dev/api/box/v1";
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
@@ -288,7 +481,9 @@ function createBoxSandboxDriver(options) {
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "none"
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: sandboxDriverCatalog.box.metadata.persistence
     },
     ensureHost,
     resumeHost,

package/dist/drivers/cloudflare.d.ts

@@ -1,4 +1,4 @@
-import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+import type { SandboxDriver, SandboxDriverEnsureInput, SandboxListingUnsupported } from "..";
 export type CloudflareSandboxDriverOptions = {
     /** Base URL of the deployed Cloudflare Sandbox Worker (e.g. https://sbx.example.com). */
     workerUrl: string;
@@ -34,4 +34,18 @@ export type CloudflareSandboxDriverOptions = {
     /** ensure-runtime/HTTP timeout. */
     timeoutMs?: number;
 };
+/**
+ * Thrown when this driver's sandbox Worker cannot enumerate sandboxes — one
+ * deployed before the `/sandboxes` registry route, or without its R2 binding.
+ *
+ * A typed signal rather than a plain Error because the manager must tell apart
+ * two cases that both "fail to list": a transient listing error (a real sweep
+ * failure, propagate it) and a standing capability gap (report
+ * `listingUnsupported`, same as a driver with no `list()`). Returning `[]` for
+ * the latter would report a clean sweep while seeing nothing.
+ */
+export declare class CloudflareSandboxListingUnsupportedError extends Error implements SandboxListingUnsupported {
+    readonly listingUnsupported: true;
+    constructor(message: string);
+}
 export declare function createCloudflareSandboxDriver(options: CloudflareSandboxDriverOptions): SandboxDriver;

package/dist/drivers/cloudflare.mjs

@@ -1,6 +1,207 @@
 // src/constants.ts
 var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
 
+// 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/driver-catalog.ts
+var sandboxDriverCatalog = {
+  exe: {
+    id: "exe",
+    label: "exe.dev",
+    credentialFields: [{ key: "api_token", label: "API Token", secret: true }],
+    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: "Daytona",
+    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // Daytona is the only driver that can filter egress by NAME as well as
+      // by address: `domainAllowList` (names) alongside `networkAllowList`
+      // (CIDRs), with `networkBlockAll` as the deny-all floor.
+      egressControl: "hosts-and-cidrs",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  modal: {
+    id: "modal",
+    label: "Modal",
+    credentialFields: [
+      { key: "token_id", label: "Token ID", secret: true },
+      { key: "token_secret", label: "Token Secret", secret: true }
+    ],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      // Modal can cut the network entirely (`blockNetwork`) but cannot express
+      // an allowlist, and its driver throws on a host policy. A blackout is
+      // not containment for a workspace that has to clone and reach a model.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  vercel: {
+    id: "vercel",
+    label: "Vercel",
+    credentialFields: [
+      { key: "access_token", label: "Access Token", secret: true },
+      { key: "team_id", label: "Team ID" },
+      { key: "project_id", label: "Project ID" }
+    ],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "replacement-host",
+      targetAccess: "relay",
+      secretBrokering: "native",
+      // Vercel's sandbox firewall takes a hostname allow list (or "deny-all"),
+      // never CIDRs.
+      egressControl: "hosts",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "filesystem",
+        clone: false,
+        captureSource: "stopped",
+        retention: "explicit",
+        restoreMount: "new-resource"
+      }
+    }
+  },
+  cloudflare: {
+    id: "cloudflare",
+    label: "Cloudflare",
+    credentialFields: [
+      { key: "api_token", label: "API Token", secret: true },
+      { key: "worker_url", label: "Worker URL" }
+    ],
+    metadata: {
+      driverRunsIn: ["worker"],
+      hostStopBehavior: "not-supported",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "proxy",
+      // The Cloudflare Sandbox Worker exposes no egress filter: its broker
+      // (drivers/cloudflare-egress.ts) is an OPT-IN proxy the sandbox chooses
+      // to route brokered-credential requests through, not a boundary. The
+      // driver therefore drops `net` entirely — which is exactly why this
+      // must be declared, so the manager refuses instead of provisioning a
+      // sandbox the caller believes is contained.
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "directories",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "copy-on-write"
+      }
+    }
+  },
+  box: {
+    id: "box",
+    label: "Box",
+    credentialFields: [{ key: "api_key", label: "API Key", secret: true }],
+    metadata: {
+      driverRunsIn: ["node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: false,
+        captureSource: "not-applicable",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
+  },
+  docker: {
+    id: "docker",
+    label: "Docker",
+    credentialFields: [{ key: "image", label: "Image" }],
+    metadata: {
+      driverRunsIn: ["local"],
+      hostStopBehavior: "terminates-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "loopback",
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "replacement-restore",
+        capture: "same-resource",
+        clone: false,
+        captureSource: "preserved",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      }
+    }
+  }
+};
+
 // src/runtime-env.ts
 function workspaceRuntimeTargetEnv(input) {
   return {
@@ -24,12 +225,24 @@ function workspaceRuntimeSourceEnv(input) {
 var DEFAULT_WORKSPACE_DIR = "/workspace";
 var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
 var DEFAULT_TIMEOUT_MS = 45e3;
+var WORKSPACE_DIRECTORY_LABEL = "claxedo.workspaceDirectory";
+var RUNTIME_DATA_DIR = "/var/lib/claxedo";
+function captureDirectories(workspaceDirectory) {
+  return [workspaceDirectory, RUNTIME_DATA_DIR];
+}
 function cleanUrl(input) {
   return input.replace(/\/+$/, "");
 }
 function sandboxIdFor(workspaceId) {
   return `claxedo-${workspaceId}`;
 }
+var CloudflareSandboxListingUnsupportedError = class extends Error {
+  listingUnsupported = true;
+  constructor(message) {
+    super(message);
+    this.name = "CloudflareSandboxListingUnsupportedError";
+  }
+};
 function createCloudflareSandboxDriver(options) {
   const doFetch = options.fetch ?? fetch;
   const runtimePort = options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
@@ -65,6 +278,8 @@ function createCloudflareSandboxDriver(options) {
         host: "0.0.0.0"
       }),
       ...workspaceRuntimeSourceEnv({ source: input.source }),
+      // Must match RUNTIME_DATA_DIR's capture set below — see its comment.
+      CLAXEDO_DATA_DIR: RUNTIME_DATA_DIR,
       ...input.env,
       ...await options.env?.(input, { id: hostId })
     };
@@ -99,6 +314,11 @@ function createCloudflareSandboxDriver(options) {
         env: await bootEnv(input, hostId),
         port: runtimePort,
         command: runtimeCommand,
+        // Sent so the Worker can record them in its sandbox registry, which is
+        // what makes this driver's `list()` (and therefore GC) possible at all.
+        // Not container env — labels are control-plane metadata.
+        labels: input.labels,
+        ...input.bootSource?.kind === "driver-snapshot" ? { restore: { backupId: input.bootSource.snapshotId, directories: captureDirectories(workspaceDirectory(input)) } } : {},
         ...egress ? { egress } : {}
       }
     ).catch((error) => {
@@ -121,18 +341,84 @@ function createCloudflareSandboxDriver(options) {
         id: "cloudflare",
         resourceId: sandboxId
       },
-      labels: input.labels
+      labels: {
+        ...input.labels,
+        [WORKSPACE_DIRECTORY_LABEL]: workspaceDirectory(input)
+      }
     };
     return targetOut;
   }
   return {
     id: "cloudflare",
+    // Provider-state enumeration, served by the sandbox Worker's registry
+    // (`GET /sandboxes`) rather than by Cloudflare's own APIs.
+    //
+    // Why a registry is REQUIRED here, checked against the installed SDK
+    // (@cloudflare/sandbox 0.8.9) rather than assumed:
+    //
+    //  1. The SDK has no enumeration surface. `getSandbox(ns, id)` is
+    //     get-or-create against a Durable Object; nothing in its exports lists
+    //     a namespace. `listDurableObjectIds` is `cloudflare:test`-only.
+    //  2. The account-level REST list-objects endpoint returns
+    //     `{ id: <hex>, hasStoredData }` and nothing else. `idFromName` is
+    //     one-way, so a hex id cannot be mapped back to `claxedo-<workspaceId>`
+    //     — no name means no labels, no `app` ownership check, and no safe
+    //     destroy. A sweep over hex ids could only guess what it was deleting.
+    //  3. It would also need account-level CF credentials this driver
+    //     deliberately does not hold; it authenticates to one user-deployed
+    //     Worker with that Worker's own bearer token.
+    //
+    // So the Worker records each sandbox on `ensure-runtime` and drops it on
+    // destroy — the pattern Cloudflare recommends for precisely this reason.
+    //
+    // A Worker predating that route (or deployed with no R2 binding) answers
+    // 404/501, which THROWS `CloudflareSandboxListingUnsupportedError` rather
+    // than returning `[]`. An empty list from an old Worker would mean "nothing
+    // is orphaned" and hand GC a silent success — the defect this whole
+    // workstream removes. The manager turns that throw back into
+    // `listingUnsupported`, so an un-upgraded Worker is loudly visible.
+    async list() {
+      const res = await doFetch(`${base}/sandboxes`, {
+        method: "GET",
+        headers,
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      const data = await res.json().catch(() => ({}));
+      if (res.status === 404 || res.status === 501 || data?.supported === false) {
+        throw new CloudflareSandboxListingUnsupportedError(
+          data?.error ?? `Cloudflare sandbox Worker cannot enumerate sandboxes (${res.status}) \u2014 deploy a Worker with the /sandboxes registry route and an R2 BACKUP_BUCKET binding`
+        );
+      }
+      if (!res.ok) {
+        throw new Error(`Cloudflare sandbox listing failed (${res.status}): ${data?.error ?? "unknown error"}`);
+      }
+      return (data.sandboxes ?? []).flatMap((entry) => {
+        const sandboxId = entry.sandboxId;
+        if (!sandboxId) return [];
+        const { sandboxId: _id, ...labels } = entry;
+        const target = {
+          ...labels.workspaceId ? { workspaceId: labels.workspaceId } : {},
+          sandboxId,
+          // Identity, not a reachable address — GC only names what it destroys.
+          url: `${base}/sandbox/${encodeURIComponent(sandboxId)}/proxy`,
+          // Matches `ensureHost`'s `hostId = sandboxId`, so a live sandbox
+          // cannot fail GC's identity check and be destroyed as an orphan.
+          hostId: sandboxId,
+          driverResourceId: sandboxId,
+          labels,
+          driver: { id: "cloudflare", resourceId: sandboxId }
+        };
+        return [target];
+      });
+    },
     metadata: {
       driverRunsIn: ["worker"],
       hostStopBehavior: "not-supported",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "proxy"
+      secretBrokering: "proxy",
+      egressControl: "none",
+      persistence: sandboxDriverCatalog.cloudflare.metadata.persistence
     },
     ensureHost,
     async touch(target) {
@@ -146,9 +432,22 @@ function createCloudflareSandboxDriver(options) {
       if (status >= 400 && status !== 404) {
         throw new Error(`Cloudflare destroy failed (${status}) for ${target.sandboxId}`);
       }
+    },
+    async snapshot(target) {
+      const directory = target.labels?.[WORKSPACE_DIRECTORY_LABEL] ?? workspaceDir;
+      const { status, data } = await call(
+        target.sandboxId,
+        "backup",
+        { directories: captureDirectories(directory) }
+      );
+      if (status >= 400 || !data.backupId) {
+        throw new Error(`Cloudflare backup failed (${status}): ${data.error ?? "no backup id"}`);
+      }
+      return { snapshotId: data.backupId };
     }
   };
 }
 export {
+  CloudflareSandboxListingUnsupportedError,
   createCloudflareSandboxDriver
 };

package/dist/drivers/daytona.d.ts

@@ -18,9 +18,39 @@ export type DaytonaSandboxLike = {
     start: (timeout?: number) => Promise<void>;
     stop: (timeout?: number) => Promise<void>;
     delete: (timeout?: number) => Promise<void>;
+    /**
+     * Replace the sandbox's outbound egress policy in place, without stopping it
+     * — the Daytona SDK's `Sandbox.updateNetworkSettings`, which drives the same
+     * runner-side iptables mechanism as `create`'s `networkBlockAll` /
+     * `networkAllowList` / `domainAllowList`. This is what makes the create-time
+     * policy reappliable on reuse and resume; see `applyNetworkPolicy` below.
+     *
+     * Optional because a client injected by an embedder may predate it. When it
+     * is absent and a restricted policy was requested, reuse is REFUSED rather
+     * than silently served on the creation-time policy.
+     */
+    updateNetworkSettings?: (settings: {
+        networkBlockAll?: boolean;
+        networkAllowList?: string;
+        domainAllowList?: string;
+    }) => Promise<void>;
+    _experimental_createSnapshot?: (name: string, timeout?: number) => Promise<void>;
 };
 export type DaytonaClientLike = {
     findByLabels?: (labels: Record<string, string>) => Promise<DaytonaSandboxLike | undefined>;
+    /**
+     * One page of sandboxes matching `labels`. Pages are 1-based; a page that
+     * returns fewer than `limit` items (or none) is the last one — that is the
+     * termination rule `list()` below relies on, and any implementation must
+     * honor it or the sweep loops forever.
+     *
+     * `createDefaultClient` satisfies it by returning every match on page 1 and
+     * nothing after: the Daytona SDK's `list()` is an `AsyncIterableIterator`
+     * that paginates internally, so `limit` is its per-page fetch size and NOT a
+     * cap on the total (see @daytona/sdk `ListSandboxesQuery.limit`). There is no
+     * cursor to hand back, so re-slicing per page would re-walk the whole account
+     * on every call.
+     */
     list?: (labels?: Record<string, string>, page?: number, limit?: number) => Promise<{
         items?: DaytonaSandboxLike[];
     }>;
@@ -36,7 +66,10 @@ export type DaytonaClientLike = {
         autoStopInterval?: number;
         autoDeleteInterval?: number;
         networkBlockAll?: boolean;
+        /** Comma-separated allowed CIDR network addresses. */
         networkAllowList?: string;
+        /** Comma-separated allowed domains — the name-based egress allowlist. */
+        domainAllowList?: string;
     }, options?: {
         timeout?: number;
     }) => Promise<DaytonaSandboxLike>;