@claxedo/sandbox-manager 0.5.2 → 0.7.0

package/dist/hosted-network-policy.mjs

@@ -0,0 +1,61 @@
+// 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
+];
+function hostOf(value) {
+  const raw = value?.trim();
+  if (!raw) return;
+  try {
+    const host = new URL(raw).hostname.trim().toLowerCase();
+    return host ? host : void 0;
+  } catch {
+    return;
+  }
+}
+function sandboxSourceHost(source) {
+  if (!source || source.kind !== "git") return;
+  return hostOf(source.repoUrl);
+}
+function hostedSandboxNetworkPolicy(input) {
+  const hosts = /* @__PURE__ */ new Set();
+  for (const entry of input.controlPlane) {
+    const host = hostOf(entry) ?? entry?.trim().toLowerCase();
+    if (host) hosts.add(host);
+  }
+  const sourceHost = sandboxSourceHost(input.source);
+  if (sourceHost) hosts.add(sourceHost);
+  for (const host of SANDBOX_BASELINE_EGRESS_HOSTS) hosts.add(host);
+  for (const host of input.extraHosts ?? []) {
+    const trimmed = host.trim().toLowerCase();
+    if (trimmed) hosts.add(trimmed);
+  }
+  return { mode: "restricted", hosts: [...hosts] };
+}
+export {
+  SANDBOX_BASELINE_EGRESS_HOSTS,
+  SANDBOX_MODEL_PROVIDER_HOSTS,
+  SANDBOX_PACKAGE_REGISTRY_HOSTS,
+  hostedSandboxNetworkPolicy,
+  sandboxSourceHost
+};

package/dist/image.d.ts

@@ -1,8 +1,23 @@
 import { Daytona, Image } from "@daytona/sdk";
 export { RUNTIME_DIR, WORKSPACE_RUNTIME_PORT, WORKSPACE_DIR } from "./defaults";
 export { SNAPSHOT_SCHEMA_VERSION, snapshotVersion, defaultSandboxImage, defaultSnapshotName, } from "./image-name";
+/**
+ * Sink for snapshot-build progress. Every message here reports a long
+ * operation an operator is actively waiting on — a snapshot build takes
+ * minutes, and the Daytona builder's `onLogs` stream is the only view into
+ * whether it is progressing or wedged.
+ *
+ * Defaults to `console.info`, deliberately unconditional: the same reasoning as
+ * `onEgressUnenforced` in index.ts — someone who never wires a sink still sees
+ * the build. Pass your own to route it into a logger; pass `() => {}` only if
+ * you have another way to observe the build.
+ */
+export type SandboxImageLogSink = (message: string, context?: Record<string, unknown>) => void;
+export type SandboxImageOptions = {
+    log?: SandboxImageLogSink;
+};
 export declare const SANDBOX_IMAGE_REPOSITORY: string;
 export declare const SANDBOX_IMAGE: string;
 export declare const SNAPSHOT_NAME: string;
 export declare function buildSandboxImage(): Image;
-export declare function ensureSnapshot(daytona: Daytona): Promise<string>;
+export declare function ensureSnapshot(daytona: Daytona, options?: SandboxImageOptions): Promise<string>;

package/dist/image.mjs

@@ -11,16 +11,8 @@ var RUNTIME_DIR = "/opt/workspace-runtime";
 
 // 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
@@ -45,10 +37,10 @@ function defaultSnapshotName(version = workspaceRuntimeVersion(), buildId, env =
 }
 
 // src/image.ts
-var log = {
-  info(_message, _context) {
-  }
-};
+function defaultImageLogSink(message, context) {
+  if (context) console.info(message, context);
+  else console.info(message);
+}
 var SANDBOX_IMAGE_REPOSITORY = sandboxImageRepository();
 var SANDBOX_IMAGE = process.env.CLAXEDO_SANDBOX_IMAGE || defaultSandboxImage();
 var SNAPSHOT_NAME = process.env.CLAXEDO_SNAPSHOT_NAME || defaultSnapshotName();
@@ -58,22 +50,23 @@ function buildSandboxImage() {
 function snapshotUsable(state) {
   return state === "ready" || state === "active";
 }
-async function createSnapshot(daytona) {
-  log.info("Creating sandbox snapshot (this may take a few minutes)...", { name: SNAPSHOT_NAME });
+async function createSnapshot(daytona, log) {
+  log("Creating sandbox snapshot (this may take a few minutes)...", { name: SNAPSHOT_NAME });
   await daytona.snapshot.create(
     { name: SNAPSHOT_NAME, image: buildSandboxImage() },
     {
       timeout: 120,
-      onLogs: (chunk) => log.info("[snapshot]", { text: chunk })
+      onLogs: (chunk) => log("[snapshot]", { text: chunk })
     }
   );
   return SNAPSHOT_NAME;
 }
-async function ensureSnapshot(daytona) {
+async function ensureSnapshot(daytona, options = {}) {
+  const log = options.log ?? defaultImageLogSink;
   try {
     const existing = await daytona.snapshot.get(SNAPSHOT_NAME);
     if (existing.state === "inactive") {
-      log.info("Snapshot is inactive, reactivating...", { name: SNAPSHOT_NAME, id: existing.id });
+      log("Snapshot is inactive, reactivating...", { name: SNAPSHOT_NAME, id: existing.id });
       await daytona.snapshot.activate({ id: existing.id });
       for (let i = 0; i < 120; i++) {
         const snap = await daytona.snapshot.get(SNAPSHOT_NAME);
@@ -84,12 +77,12 @@ async function ensureSnapshot(daytona) {
       throw new Error("Snapshot activation timed out");
     }
     if (existing.state === "building") {
-      log.info("Snapshot is building, waiting (up to 10 min)...", { name: SNAPSHOT_NAME });
+      log("Snapshot is building, waiting (up to 10 min)...", { name: SNAPSHOT_NAME });
       for (let i = 0; i < 300; i++) {
         const snap = await daytona.snapshot.get(SNAPSHOT_NAME);
         if (snapshotUsable(snap.state)) return SNAPSHOT_NAME;
         if (snap.state === "error") throw new Error(`Snapshot build failed: ${snap.errorReason}`);
-        if (i % 15 === 0) log.info("Still waiting for snapshot...", { state: snap.state, elapsed: `${i * 2}s` });
+        if (i % 15 === 0) log("Still waiting for snapshot...", { state: snap.state, elapsed: `${i * 2}s` });
         await new Promise((resolve) => setTimeout(resolve, 2e3));
       }
       throw new Error("Snapshot build timed out after 10 minutes");
@@ -98,7 +91,7 @@ async function ensureSnapshot(daytona) {
   } catch (err) {
     if (!(err instanceof DaytonaNotFoundError)) throw err;
   }
-  return createSnapshot(daytona);
+  return createSnapshot(daytona, log);
 }
 export {
   RUNTIME_DIR,

package/dist/index.d.ts

@@ -1,8 +1,64 @@
 import { DEFAULT_WORKSPACE_RUNTIME_PORT } from "./constants";
 import type { SandboxDriverID } from "./driver-catalog";
+import { type SandboxCheckpointCaptureInput, type SandboxCheckpointRestoreInput, type SandboxCheckpointResult } from "./checkpoint-manager";
 export { DEFAULT_WORKSPACE_RUNTIME_PORT };
+export * from "./checkpoint-manager";
+export * from "./hosted-network-policy";
 export type SandboxRegion = string;
 export type SandboxDriverId = SandboxDriverID | "fetch";
+export type SandboxCaptureScope = "none" | "same-resource" | "filesystem" | "directories";
+export type SandboxCaptureSourceBehavior = "not-applicable" | "preserved" | "stopped" | "deleted";
+export type SandboxRestoreMountBehavior = "not-applicable" | "same-resource" | "copy-on-write" | "new-resource";
+export type SandboxPersistenceCapabilities = {
+    resume: "same-sandbox" | "replacement-restore";
+    capture: SandboxCaptureScope;
+    clone: boolean;
+    captureSource: SandboxCaptureSourceBehavior;
+    retention: "not-applicable" | "provider-managed" | "explicit";
+    restoreMount: SandboxRestoreMountBehavior;
+};
+export declare function validateSandboxPersistenceCapabilities(input: SandboxPersistenceCapabilities): {
+    valid: false;
+    reason: string;
+} | {
+    reason?: undefined;
+    valid: true;
+};
+export type SandboxCheckpointReference = {
+    id: string;
+    providerReference: string;
+    sourceEpoch: number;
+    capturedAt: number;
+    metadata: {
+        scope: Exclude<SandboxCaptureScope, "none">;
+        sourceBehavior: Exclude<SandboxCaptureSourceBehavior, "not-applicable">;
+        retentionExpiresAt?: number;
+        restoreMount: Exclude<SandboxRestoreMountBehavior, "not-applicable">;
+    };
+};
+type SandboxRestoreIdentity = {
+    checkpointId: string;
+    sourceEpoch: number;
+};
+export type SandboxRestoreStatus = (SandboxRestoreIdentity & {
+    state: "pending";
+    requestedAt: number;
+}) | (SandboxRestoreIdentity & {
+    state: "restoring";
+    requestedAt: number;
+    startedAt: number;
+}) | (SandboxRestoreIdentity & {
+    state: "ready";
+    requestedAt: number;
+    startedAt: number;
+    completedAt: number;
+}) | (SandboxRestoreIdentity & {
+    state: "failed";
+    requestedAt: number;
+    startedAt?: number;
+    failedAt: number;
+    error: string;
+});
 export type SandboxDriverMetadata = {
     /** Where the sandbox driver code can execute. This is not sandbox infrastructure. */
     driverRunsIn: Array<"worker" | "node" | "local">;
@@ -35,6 +91,100 @@ export type SandboxDriverMetadata = {
      * that is not yet wired and therefore also fails closed.
      */
     secretBrokering: "native" | "proxy" | "none";
+    /**
+     * How the driver can enforce a RESTRICTED `SandboxNetworkPolicy` — i.e.
+     * whether the sandbox's outbound network can actually be contained.
+     *
+     * A `SandboxNetworkPolicy` states the same allowance in up to two encodings:
+     * `hosts` (names) and `cidrs` (addresses). A driver contains egress if it
+     * enforces AT LEAST ONE encoding the policy carries and blocks everything
+     * else; the encodings are alternatives, not additive requirements.
+     *
+     * - `"hosts-and-cidrs"` — the provider filters by name AND by address
+     *   (Daytona: `domainAllowList` + `networkAllowList`).
+     * - `"hosts"` — the provider filters by hostname only (Vercel firewall).
+     * - `"none"` — the driver cannot express an egress allowlist. This covers
+     *   BOTH drivers that throw when handed a restricted policy (exe, docker,
+     *   box, and modal for host policy) AND — more dangerously — drivers that
+     *   silently ignore `net` and run wide open (cloudflare, the fetch bridge).
+     *   Modal is `"none"` even though it can cut the network entirely: a total
+     *   blackout is not an allowlist and cannot serve a workspace that has to
+     *   clone a repo and reach a model provider.
+     *
+     * The manager reads this to decide what the driver is handed:
+     * `sandboxEgressDisposition` enforces where it can and WITHHOLDS (loudly)
+     * where it cannot. See `SandboxEgressDisposition` for the posture and
+     * `public-docs/sandbox-egress.md` for the operator-facing consequence.
+     */
+    egressControl: SandboxEgressControl;
+    persistence: SandboxPersistenceCapabilities;
+};
+/** @see SandboxDriverMetadata.egressControl */
+export type SandboxEgressControl = "none" | "hosts" | "hosts-and-cidrs";
+/**
+ * What the manager does with a caller's `net` for a given driver.
+ *
+ * Owner directive (2026-07-28): *"for egress in sandbox enforce where we can
+ * and document where we cant."* That replaces the previous fail-closed refusal
+ * for drivers with no egress control at all — provisioning now proceeds, and
+ * the gap is made loud instead of fatal.
+ *
+ *  - `"enforce"` — the driver gets the policy verbatim and contains the
+ *    sandbox. Also the answer when the caller asked for no containment
+ *    (absent / `allow-all`), which is nothing to enforce.
+ *  - `"withhold"` — the driver declares `egressControl: "none"`, so there is no
+ *    containment to be had. The policy is NOT handed down: half the `"none"`
+ *    drivers throw on a restricted policy (exe, docker, modal, box) and the
+ *    other half silently drop it (cloudflare, the fetch bridge). Withholding at
+ *    the manager means the throwing drivers never see one — their throws stay
+ *    in place as their own last line of defence — and the silently-dropping
+ *    ones stop pretending. The sandbox comes up with UNRESTRICTED egress, which
+ *    is a real exposure, so the manager warns (see `onEgressUnenforced`).
+ *  - `"refuse"` — the driver HAS egress control but cannot express this
+ *    particular policy's encoding (a hosts-only driver handed an address-only
+ *    allowlist). Deliberately still fail-closed: this is a composition mistake
+ *    on an otherwise-enforcing driver, and degrading it to "withhold" would
+ *    weaken the enforcing path. `hostedSandboxNetworkPolicy` only ever emits
+ *    hosts, so no production path reaches it.
+ *
+ * Pure, like `validateSandboxPersistenceCapabilities`, so the manager, the
+ * composition layer, and tests can all ask the same question.
+ */
+export type SandboxEgressDisposition = {
+    action: "enforce";
+} | {
+    action: "withhold";
+    reason: "sandbox_egress_uncontained";
+} | {
+    action: "refuse";
+    reason: "sandbox_egress_policy_unenforceable";
+};
+/** @see SandboxEgressDisposition */
+export declare function sandboxEgressDisposition(control: SandboxEgressControl, net: SandboxNetworkPolicy | undefined): SandboxEgressDisposition;
+/**
+ * Emitted whenever a restricted egress policy is withheld because the composed
+ * driver declares no egress control. This is the "document where we can't" half
+ * of the directive expressed at runtime: an unrestricted sandbox that nobody
+ * was told about is the original finding, so the degrade is never silent.
+ *
+ * Two phases, because a per-create line is easy to miss in request logs:
+ *  - `"composition"` — once per `createSandboxManager` per driver, at boot.
+ *  - `"ensure"` — every time a caller's policy is actually withheld, naming the
+ *    workspace and the allowlist that did not take effect.
+ */
+export type SandboxEgressUnenforcedEvent = {
+    phase: "composition" | "ensure";
+    reason: "sandbox_egress_uncontained";
+    /** `SandboxDriver.id` of the composed driver. */
+    driver: string;
+    /** Always `"none"` today — carried so a sink can group without re-deriving. */
+    egressControl: SandboxEgressControl;
+    /** Ready-to-log sentence. Sinks that only forward text can use this alone. */
+    message: string;
+    /** Present on `"ensure"`. */
+    workspaceId?: string;
+    /** The allowlist the caller asked for and did NOT get. Present on `"ensure"`. */
+    requested?: SandboxNetworkPolicy;
 };
 /**
  * A credential the SANDBOX must be able to USE for outbound requests but must
@@ -92,6 +242,9 @@ export type SandboxLease = {
     lastHeartbeatAt?: number;
     lastActivityAt?: number;
     labels?: Record<string, string>;
+    checkpoint?: SandboxCheckpointReference;
+    persistence?: SandboxPersistenceCapabilities;
+    restore?: SandboxRestoreStatus;
 };
 export type SandboxLeaseAcquireInput = {
     homeRegion: SandboxRegion;
@@ -112,6 +265,12 @@ export type SandboxLeasePatch = Partial<Pick<SandboxLease, "status" | "sandboxId
     nextRetryAt?: number | null;
     /** `null` clears the stored value; `undefined` leaves it unchanged. */
     lastError?: string | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    checkpoint?: SandboxCheckpointReference | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    persistence?: SandboxPersistenceCapabilities | null;
+    /** `null` clears the stored value; `undefined` leaves it unchanged. */
+    restore?: SandboxRestoreStatus | null;
 };
 /**
  * Canonical SandboxLeasePatch merge semantics shared by every lease store driver:
@@ -162,7 +321,16 @@ export type SandboxDriverEnsureInput = {
     secrets?: SandboxBrokeredSecret[];
     source?: SandboxSource;
     exposure?: SandboxExposure;
-    /** Optional egress policy (allow-all when omitted). */
+    /**
+     * Egress policy. Omitted means allow-all, which is only appropriate for a
+     * single-tenant deployment the operator already trusts.
+     *
+     * A driver can rely on this being ABSENT whenever it declares
+     * `egressControl: "none"`: the manager withholds the policy rather than hand
+     * it to a driver that would either throw on it or silently drop it. A driver
+     * that receives a restricted policy here is one that declared it can enforce
+     * it. @see SandboxEgressDisposition
+     */
     net?: SandboxNetworkPolicy;
     /** Optional snapshot/image to boot from (user-supplied or pre-built). */
     snapshot?: string;
@@ -183,6 +351,11 @@ export type SandboxTarget = {
 export type SandboxSnapshotResult = {
     snapshotId: string;
 };
+export type SandboxCommandResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
 export type SandboxDriver = {
     id: string;
     metadata: SandboxDriverMetadata;
@@ -203,6 +376,11 @@ export type SandboxDriver = {
     stop?: (target: SandboxTarget) => Promise<void>;
     destroy?: (target: SandboxTarget) => Promise<void>;
     snapshot?: (target: SandboxTarget) => Promise<SandboxSnapshotResult>;
+    inspect?: (target: SandboxTarget) => Promise<SandboxTarget | undefined>;
+    exec?: (target: SandboxTarget, command: string) => Promise<SandboxCommandResult>;
+    clone?: (target: SandboxTarget, input: {
+        name: string;
+    }) => Promise<SandboxTarget>;
 };
 export type SandboxManager = {
     ensure: (workspaceId: string, input: SandboxManagerInput) => Promise<SandboxEnsureResult>;
@@ -211,6 +389,8 @@ export type SandboxManager = {
     target: (workspaceId: string) => Promise<SandboxTargetResult>;
     touch: (workspaceId: string) => Promise<SandboxTouchResult>;
     snapshot: (workspaceId: string) => Promise<SandboxSnapshotManagerResult>;
+    checkpoint: (workspaceId: string, input: SandboxCheckpointCaptureInput) => Promise<SandboxCheckpointResult>;
+    restore: (workspaceId: string, input: SandboxCheckpointRestoreInput) => Promise<SandboxCheckpointResult>;
     stop: (workspaceId: string) => Promise<SandboxMutationResult>;
     destroy: (workspaceId: string) => Promise<SandboxMutationResult>;
     release: (workspaceId: string) => Promise<{
@@ -232,6 +412,10 @@ export type SandboxManagerInput = {
     secrets?: SandboxBrokeredSecret[];
     source?: SandboxSource;
     exposure?: SandboxExposure;
+    /**
+     * @see SandboxDriverEnsureInput.net — enforced by a capable driver, withheld
+     * (with a warning) by one that declares `egressControl: "none"`.
+     */
     net?: SandboxNetworkPolicy;
     snapshot?: string;
 };
@@ -301,7 +485,31 @@ export type SandboxGarbageCollectResult = {
         target: SandboxTarget;
         error: string;
     }>;
+    /**
+     * Set when the driver cannot enumerate provider state, so the four arrays
+     * above mean "we could not look" rather than "nothing is orphaned". Absent on
+     * a real sweep. Callers must treat it as a FAILED sweep: four empty arrays
+     * reported as success is the exact defect finding B1 names.
+     */
+    listingUnsupported?: true;
+    /** Driver id, so an ops report can name which driver could not look. */
+    driver?: string;
 };
+/**
+ * A driver's `list()` may throw this shape to say "my backing service cannot
+ * enumerate", as distinct from "listing failed this time". `garbageCollect()`
+ * converts it into `listingUnsupported` (a loud, non-fatal capability gap);
+ * every other error propagates as a real sweep failure.
+ *
+ * Structural rather than an `instanceof` check on purpose: drivers are published
+ * as separate entry points and bundlers duplicate class identities, so a
+ * nominal check would silently fall through to "transient failure" in exactly
+ * the deployment that needs the distinction.
+ */
+export type SandboxListingUnsupported = {
+    listingUnsupported: true;
+};
+export declare function isSandboxListingUnsupported(err: unknown): err is SandboxListingUnsupported;
 export type SandboxManagerOptions = {
     leaseStore: SandboxLeaseStore;
     driver: SandboxDriver;
@@ -312,5 +520,16 @@ export type SandboxManagerOptions = {
     retryCapCooldownMs?: number;
     now?: () => number;
     appLabel?: string;
+    /**
+     * Sink for the loud half of "enforce where we can, document where we can't".
+     * Called at composition time and again every time a restricted policy is
+     * withheld from a driver that cannot enforce it.
+     *
+     * Defaults to `console.warn(event.message)`. Pass your own to route the gap
+     * into a telemetry pipeline instead — but note the default is deliberately
+     * unconditional: an operator who never wires a sink still gets the warning.
+     * Pass `() => {}` only if you have another way to surface it.
+     */
+    onEgressUnenforced?: (event: SandboxEgressUnenforcedEvent) => void;
 };
 export declare function createSandboxManager(options: SandboxManagerOptions): SandboxManager;