@claxedo/sandbox-manager 0.6.0 → 0.7.0

package/dist/lease-policy.mjs

@@ -1,56 +1,220 @@
-// src/lease-policy.ts
-var DEFAULT_WORKSPACE_HOST_DECISION_CONFIG = {
-  maxRetries: 8,
-  idleMs: 10 * 60 * 1e3,
-  backoffMaxMs: 3e4,
-  healthTimeoutMs: 6e4
-};
-var DRIVER_PLACEMENT = {
+// 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: {
-    canPauseAndRestartSameResource: true,
-    canCreateFilesystemSnapshot: false,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    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: {
-    canPauseAndRestartSameResource: false,
-    canCreateFilesystemSnapshot: true,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    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: {
-    canPauseAndRestartSameResource: false,
-    canCreateFilesystemSnapshot: true,
-    canStartFromPreparedImage: false,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    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: {
-    canPauseAndRestartSameResource: false,
-    canCreateFilesystemSnapshot: true,
-    canStartFromPreparedImage: false,
-    canStopExplicitly: false,
-    hasHealthProbe: true
+    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: {
-    canPauseAndRestartSameResource: true,
-    canCreateFilesystemSnapshot: false,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    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: {
-    canPauseAndRestartSameResource: true,
-    canCreateFilesystemSnapshot: false,
-    canStartFromPreparedImage: true,
-    canStopExplicitly: true,
-    hasHealthProbe: true
+    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/lease-policy.ts
+var DEFAULT_WORKSPACE_HOST_DECISION_CONFIG = {
+  maxRetries: 8,
+  idleMs: 10 * 60 * 1e3,
+  backoffMaxMs: 3e4,
+  healthTimeoutMs: 6e4
+};
 function sandboxDriverPlacement(driver) {
-  return DRIVER_PLACEMENT[driver];
+  const metadata = sandboxDriverCatalog[driver].metadata;
+  return {
+    canPauseAndRestartSameResource: metadata.persistence.resume === "same-sandbox",
+    canCreateFilesystemSnapshot: metadata.persistence.capture === "filesystem" || metadata.persistence.capture === "directories",
+    canStartFromPreparedImage: driver === "exe" || driver === "daytona" || driver === "modal" || driver === "box" || driver === "docker",
+    canStopExplicitly: metadata.hostStopBehavior !== "not-supported",
+    hasHealthProbe: true
+  };
 }
 function decideSandboxStart(lease, placement, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
   if (lease.status === "ready") {
@@ -83,20 +247,6 @@ function decideSandboxHealthFailure(lease, _placement, now, config = DEFAULT_WOR
   const backoff = Math.min(config.backoffMaxMs, 1e3 * 2 ** Math.max(0, retryCount - 1));
   return { action: "wait", until: now + backoff, reason: `health failure #${retryCount}, backoff ${backoff}ms` };
 }
-function decideSandboxIdle(lease, activeHoldCount, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
-  if (lease.status !== "ready") {
-    return { action: "skip", reason: `status is ${lease.status}, not ready` };
-  }
-  if (activeHoldCount > 0) {
-    return { action: "skip", reason: `${activeHoldCount} active hold(s)` };
-  }
-  const lastActivity = lease.last_activity_at ?? lease.created_at;
-  const idleFor = now - lastActivity;
-  if (idleFor < config.idleMs) {
-    return { action: "wait", until: lastActivity + config.idleMs, reason: `idle for ${idleFor}ms, need ${config.idleMs}ms` };
-  }
-  return { action: "stop_idle", reason: `idle for ${idleFor}ms (threshold: ${config.idleMs}ms)` };
-}
 function nextSandboxRetryAt(retryCount, now, config = DEFAULT_WORKSPACE_HOST_DECISION_CONFIG) {
   if (retryCount >= config.maxRetries) return null;
   return now + Math.min(config.backoffMaxMs, 1e3 * 2 ** Math.max(0, retryCount));
@@ -124,7 +274,6 @@ function decideStartMethod(lease, placement) {
 export {
   DEFAULT_WORKSPACE_HOST_DECISION_CONFIG,
   decideSandboxHealthFailure,
-  decideSandboxIdle,
   decideSandboxStart,
   nextSandboxRetryAt,
   sandboxDriverPlacement

package/dist/lease-types.d.ts

@@ -1,5 +1,6 @@
 import type { SandboxDriverID } from "./driver-catalog";
-export type SandboxLeaseRowStatus = "pending" | "acquiring" | "starting" | "ready" | "unhealthy" | "backoff" | "stopping" | "stopped" | "failed";
+import type { SandboxCheckpointReference, SandboxPersistenceCapabilities, SandboxRestoreStatus } from "./index";
+export type SandboxLeaseRowStatus = "pending" | "acquiring" | "starting" | "ready" | "unhealthy" | "backoff" | "stopping" | "stopped" | "destroyed" | "failed";
 export type SandboxComputeClass = "small" | "medium" | "large" | "gpu";
 export type SandboxLeaseRow = {
     workspace_id: string;
@@ -22,6 +23,10 @@ export type SandboxLeaseRow = {
     accel_base_image_id: string | null;
     accel_prepared_image_id: string | null;
     accel_snapshot_id: string | null;
+    labels?: Record<string, string> | null;
+    checkpoint: SandboxCheckpointReference | null;
+    persistence: SandboxPersistenceCapabilities | null;
+    restore: SandboxRestoreStatus | null;
     created_at: number;
     updated_at: number;
 };

package/dist/runtime-version.mjs

@@ -1,15 +1,7 @@
 // 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;
 }
 export {
   workspaceRuntimeVersion

package/dist/stores/memory.mjs

@@ -1,3 +1,29 @@
+// 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
 function applySandboxLeasePatch(current, patch, updatedAt) {
   return {
@@ -13,6 +39,9 @@ function applySandboxLeasePatch(current, patch, updatedAt) {
     ...patch.labels === void 0 ? {} : { labels: patch.labels },
     ...patch.nextRetryAt === void 0 ? {} : { nextRetryAt: patch.nextRetryAt ?? void 0 },
     ...patch.lastError === void 0 ? {} : { lastError: patch.lastError ?? void 0 },
+    ...patch.checkpoint === void 0 ? {} : { checkpoint: patch.checkpoint ?? void 0 },
+    ...patch.persistence === void 0 ? {} : { persistence: patch.persistence ?? void 0 },
+    ...patch.restore === void 0 ? {} : { restore: patch.restore ?? void 0 },
     updatedAt
   };
 }
@@ -50,7 +79,10 @@ function createMemoryLeaseStore(seed = []) {
         driverResourceId: resumable ? current.driverResourceId : void 0,
         lastHeartbeatAt: resumable ? current.lastHeartbeatAt : void 0,
         lastActivityAt: resumable ? current.lastActivityAt : void 0,
-        labels: resumable ? current.labels : void 0
+        labels: resumable ? current.labels : void 0,
+        checkpoint: current?.checkpoint,
+        persistence: current?.persistence,
+        restore: current?.restore
       };
       leases.set(workspaceId, next);
       return { acquired: true, lease: next };
@@ -106,7 +138,10 @@ function sandboxLease(input) {
     lastError: input.lastError,
     lastHeartbeatAt: input.lastHeartbeatAt,
     lastActivityAt: input.lastActivityAt,
-    labels: input.labels
+    labels: input.labels,
+    checkpoint: input.checkpoint,
+    persistence: input.persistence,
+    restore: input.restore
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claxedo/sandbox-manager",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Sandbox lifecycle manager with epoch-based leases and pluggable drivers for Daytona, Modal, Vercel Sandbox, Cloudflare, Box, and Docker",
   "license": "MIT",
@@ -44,6 +44,13 @@
       "import": "./dist/constants.mjs",
       "default": "./dist/constants.mjs"
     },
+    "./checkpoint-manager": {
+      "types": "./dist/checkpoint-manager.d.ts",
+      "bun": "./dist/checkpoint-manager.mjs",
+      "development": "./dist/checkpoint-manager.mjs",
+      "import": "./dist/checkpoint-manager.mjs",
+      "default": "./dist/checkpoint-manager.mjs"
+    },
     "./defaults": {
       "types": "./dist/defaults.d.ts",
       "bun": "./dist/defaults.mjs",
@@ -65,6 +72,13 @@
       "import": "./dist/drivers/box.mjs",
       "default": "./dist/drivers/box.mjs"
     },
+    "./drivers/exe": {
+      "types": "./dist/drivers/exe.d.ts",
+      "bun": "./dist/drivers/exe.mjs",
+      "development": "./dist/drivers/exe.mjs",
+      "import": "./dist/drivers/exe.mjs",
+      "default": "./dist/drivers/exe.mjs"
+    },
     "./drivers/cloudflare": {
       "types": "./dist/drivers/cloudflare.d.ts",
       "bun": "./dist/drivers/cloudflare.mjs",
@@ -174,7 +188,7 @@
     "build": "tsx scripts/build.ts",
     "prepublishOnly": "npm run build",
     "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "bun test src"
+    "test": "mkdir -p .artifacts/unit && bun test src --reporter=junit --reporter-outfile=.artifacts/unit/junit.xml"
   },
   "devDependencies": {
     "@tsconfig/node-lts": "22.0.4",