@claxedo/sandbox-manager 0.6.0 → 0.7.0

package/dist/drivers/exe.mjs

@@ -0,0 +1,469 @@
+// src/command.ts
+function shell(input) {
+  return `'${input.replace(/'/g, `'"'"'`)}'`;
+}
+
+// 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/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)}` : "";
+}
+function defaultSandboxImage(version = workspaceRuntimeVersion(), buildId, env = process.env) {
+  return `${sandboxImageRepository(env)}:workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+}
+function defaultSnapshotName(version = workspaceRuntimeVersion(), buildId, env = process.env) {
+  return `claxedo-workspace-runtime-${snapshotVersion(version)}${buildIdSuffix(buildId, env)}-v${SNAPSHOT_SCHEMA_VERSION}`;
+}
+
+// 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/image.ts
+import { Image, DaytonaNotFoundError } from "@daytona/sdk";
+var SANDBOX_IMAGE_REPOSITORY = sandboxImageRepository();
+var SANDBOX_IMAGE = process.env.CLAXEDO_SANDBOX_IMAGE || defaultSandboxImage();
+var SNAPSHOT_NAME = process.env.CLAXEDO_SNAPSHOT_NAME || defaultSnapshotName();
+
+// src/runtime-env.ts
+function workspaceRuntimeTargetEnv(input) {
+  return {
+    WORKSPACE_RUNTIME_WORKSPACE_ID: input.workspaceId,
+    ...input.hostId ? { WORKSPACE_RUNTIME_HOST_ID: input.hostId } : {},
+    WORKSPACE_RUNTIME_DIRECTORY: input.directory,
+    WORKSPACE_RUNTIME_PORT: String(input.port),
+    ...input.host ? { WORKSPACE_RUNTIME_HOST: input.host } : {}
+  };
+}
+function workspaceRuntimeSourceEnv(input) {
+  if (!input.source || input.source.kind === "empty") return { WORKSPACE_RUNTIME_SOURCE_KIND: "empty" };
+  return {
+    WORKSPACE_RUNTIME_SOURCE_KIND: "git",
+    WORKSPACE_RUNTIME_GIT_REPO_URL: input.source.repoUrl,
+    ...input.source.branch ? { WORKSPACE_RUNTIME_GIT_BRANCH: input.source.branch } : {}
+  };
+}
+
+// src/drivers/exe.ts
+var DEFAULT_ENDPOINT = "https://exe.dev/exec";
+var DEFAULT_RUNTIME_COMMAND = "workspace-runtime";
+var DEFAULT_WORKSPACE_DIR = "/workspace";
+var DEFAULT_OPERATION_TIMEOUT_MS = 12e4;
+var DEFAULT_EXE_APP_LABEL = "claxedo";
+var DEFAULT_HEALTH_TIMEOUT_MS = 6e4;
+var DEFAULT_HEALTH_INTERVAL_MS = 1e3;
+function exeWorkspaceName(workspaceId, epoch) {
+  const slug = workspaceId.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 30) || "workspace";
+  const hash = [...workspaceId].reduce((value, char) => Math.imul(value ^ char.charCodeAt(0), 16777619), 2166136261);
+  return `claxedo-ws-${slug}-${(hash >>> 0).toString(36).slice(0, 8)}-g${epoch}`.slice(0, 63).replace(/-+$/g, "");
+}
+function createExeSandboxDriver(options) {
+  const endpoint = options.endpoint ?? DEFAULT_ENDPOINT;
+  const image = options.image ?? SANDBOX_IMAGE;
+  const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
+  const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
+  const operationTimeoutMs = options.operationTimeoutMs ?? DEFAULT_OPERATION_TIMEOUT_MS;
+  const healthTimeoutMs = options.healthTimeoutMs ?? DEFAULT_HEALTH_TIMEOUT_MS;
+  const healthIntervalMs = options.healthIntervalMs ?? DEFAULT_HEALTH_INTERVAL_MS;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const labels = /* @__PURE__ */ new Map();
+  async function api(command) {
+    const response = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${options.apiToken}`,
+        "Content-Type": "text/plain; charset=utf-8"
+      },
+      body: command,
+      signal: AbortSignal.timeout(operationTimeoutMs)
+    });
+    const text = await response.text();
+    const body = text ? JSON.parse(text) : {};
+    if (!response.ok || body.ok === false || typeof body.error === "string") {
+      throw new Error(`exe.dev command failed (${response.status}): ${String(body.error ?? body.message ?? response.statusText)}`);
+    }
+    return body;
+  }
+  function vm(input) {
+    if (!input || typeof input !== "object") return;
+    const value = input;
+    if (typeof value.vm_name !== "string") return;
+    return {
+      vm_name: value.vm_name,
+      ...typeof value.https_url === "string" ? { https_url: value.https_url } : {},
+      ...typeof value.ssh_dest === "string" ? { ssh_dest: value.ssh_dest } : {},
+      ...typeof value.status === "string" ? { status: value.status } : {},
+      ...Array.isArray(value.tags) ? { tags: value.tags.filter((tag) => typeof tag === "string") } : {}
+    };
+  }
+  function durableLabels(item) {
+    const cached = labels.get(item.vm_name);
+    if (cached) return cached;
+    const tags = item.tags ?? [];
+    if (!tags.includes("claxedo")) return;
+    const workspaceId = tags.find((tag) => tag.startsWith("workspace-"))?.slice("workspace-".length);
+    if (!workspaceId) return;
+    const epoch = item.vm_name.match(/-g(\d+)$/)?.[1];
+    if (!epoch) return;
+    return { app: DEFAULT_EXE_APP_LABEL, workspaceId, epoch };
+  }
+  async function inspect(name) {
+    const result = await api(`ls ${shell(name)}`);
+    return (Array.isArray(result.vms) ? result.vms : []).map(vm).find((candidate) => candidate?.vm_name === name);
+  }
+  function target(input) {
+    const url = input.vm.https_url ?? `https://${input.vm.vm_name}.exe.xyz`;
+    return {
+      ...input.workspaceId ? { workspaceId: input.workspaceId } : {},
+      sandboxId: input.vm.vm_name,
+      url,
+      hostId: input.hostId ?? input.vm.vm_name,
+      driverResourceId: input.vm.vm_name,
+      labels: input.labels ?? labels.get(input.vm.vm_name),
+      driver: { id: "exe", resourceId: input.vm.vm_name }
+    };
+  }
+  async function execute(name, command) {
+    const body = await api(`ssh ${shell(name)} ${shell(command)}`);
+    const result = body.result && typeof body.result === "object" ? body.result : body;
+    return {
+      stdout: typeof result.stdout === "string" ? result.stdout : "",
+      stderr: typeof result.stderr === "string" ? result.stderr : "",
+      exitCode: typeof result.exit_code === "number" ? result.exit_code : typeof result.exitCode === "number" ? result.exitCode : 0
+    };
+  }
+  async function executeOrThrow(name, command, label) {
+    const result = await execute(name, command);
+    if (result.exitCode !== 0) {
+      throw new Error(`exe.dev ${name} ${label} failed (${result.exitCode}): ${result.stderr || result.stdout}`);
+    }
+    return result;
+  }
+  function runtimePort(input) {
+    return input.workspaceRuntimePort ?? options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
+  }
+  function directory(input) {
+    return input.workspaceRoot ?? workspaceDir;
+  }
+  async function boot(vm2, input, hostId) {
+    const env = {
+      ...workspaceRuntimeTargetEnv({
+        workspaceId: input.workspaceId,
+        hostId,
+        directory: directory(input),
+        port: runtimePort(input),
+        host: "0.0.0.0"
+      }),
+      ...workspaceRuntimeSourceEnv({ source: input.source }),
+      ...input.env,
+      ...await options.env?.(input, vm2)
+    };
+    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
+    const envArgs = Object.entries(env).map(([key, value]) => `${key}=${shell(value)}`).join(" ");
+    await executeOrThrow(
+      vm2.vm_name,
+      `mkdir -p ${shell(directory(input))} && (pkill -f ${shell(runtimeCommand)} || true) && cd ${shell(directory(input))} && nohup env ${envArgs} ${runtimeCommand} > .claxedo-workspace-runtime.log 2>&1 < /dev/null &`,
+      "runtime start"
+    );
+    const until = Date.now() + healthTimeoutMs;
+    while (Date.now() <= until) {
+      const health = await execute(
+        vm2.vm_name,
+        `curl -sf -o /dev/null -w '%{http_code}' http://127.0.0.1:${runtimePort(input)}/global/health || true`
+      );
+      if (health.stdout.trim() === "200") {
+        labels.set(vm2.vm_name, input.labels);
+        return target({ vm: vm2, workspaceId: input.workspaceId, hostId, labels: input.labels });
+      }
+      await new Promise((resolve) => setTimeout(resolve, healthIntervalMs));
+    }
+    throw new Error(`exe.dev ${vm2.vm_name} workspace runtime did not become healthy`);
+  }
+  function assertNetwork(input) {
+    if (input.net && input.net.mode !== "allow-all") {
+      throw new Error("exe.dev SandboxDriver cannot enforce host-based network policy");
+    }
+  }
+  async function ensureHost(input) {
+    assertNetwork(input);
+    const name = exeWorkspaceName(input.workspaceId, input.epoch);
+    const existing = await inspect(name);
+    const created = existing ?? vm(await api(
+      `new --name=${shell(name)} --image=${shell(input.bootSource?.kind === "image" ? input.bootSource.image : image)} --tag=claxedo --tag=${shell(`workspace-${input.workspaceId}`)} ${input.hostId ? `--tag=${shell(`host-${input.hostId}`)} ` : ""}--no-email`
+    ).then((result) => result.vm ?? result));
+    if (!created) throw new Error(`exe.dev did not return VM metadata for ${name}`);
+    return boot(created, input, input.hostId ?? name);
+  }
+  async function resumeHost(input) {
+    assertNetwork(input.ensure);
+    const name = input.lease.sandboxId ?? exeWorkspaceName(input.ensure.workspaceId, input.lease.epoch);
+    const existing = await inspect(name);
+    if (!existing) return ensureHost(input.ensure);
+    return boot(existing, input.ensure, input.ensure.hostId ?? input.lease.hostId ?? name);
+  }
+  return {
+    id: "exe",
+    metadata: sandboxDriverCatalog.exe.metadata,
+    ensureHost,
+    resumeHost,
+    // Provider-state enumeration for `garbageCollect()`. Labels come from
+    // DURABLE provider state (tags + the VM name's epoch suffix), not the
+    // in-process cache — see `durableLabels`. A VM whose labels cannot be
+    // recovered is returned WITHOUT them so GC skips it as unlabeled rather
+    // than acting on a guess; it is never destroyed on partial identity.
+    async list() {
+      const result = await api("ls claxedo-ws-*");
+      return (Array.isArray(result.vms) ? result.vms : []).map(vm).filter((item) => !!item && item.vm_name.startsWith("claxedo-ws-")).map((item) => {
+        const recovered = durableLabels(item);
+        const hostId = item.tags?.find((tag) => tag.startsWith("host-"))?.slice("host-".length);
+        return target({
+          vm: item,
+          ...recovered?.workspaceId ? { workspaceId: recovered.workspaceId } : {},
+          ...recovered ? { labels: recovered } : {},
+          ...hostId ? { hostId } : {}
+        });
+      });
+    },
+    async inspect(input) {
+      const current = await inspect(input.sandboxId);
+      return current ? target({ vm: current, workspaceId: input.workspaceId, hostId: input.hostId }) : void 0;
+    },
+    exec: (input, command) => execute(input.sandboxId, command),
+    async stop(input) {
+      await executeOrThrow(input.sandboxId, `pkill -f ${shell(runtimeCommand)} || true`, "runtime stop");
+    },
+    async destroy(input) {
+      await api(`rm ${shell(input.sandboxId)}`);
+      labels.delete(input.sandboxId);
+    },
+    async clone(input, clone) {
+      const name = exeWorkspaceName(clone.name, 1);
+      const copied = vm(await api(`cp ${shell(input.sandboxId)} ${shell(name)} --copy-tags`).then(
+        (result) => result.vm ?? result
+      ));
+      if (!copied) throw new Error(`exe.dev did not return cloned VM metadata for ${name}`);
+      return target({ vm: copied });
+    },
+    async touch() {
+    }
+  };
+}
+export {
+  createExeSandboxDriver,
+  exeWorkspaceName
+};

package/dist/drivers/fetch-bridge.mjs

@@ -77,7 +77,16 @@ function createFetchBridgeSandboxDriver(options) {
       hostStopBehavior: "suspends-host",
       hostResumeBehavior: "same-host",
       targetAccess: "relay",
-      secretBrokering: "none"
+      secretBrokering: "none",
+      egressControl: "none",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: false,
+        captureSource: "not-applicable",
+        retention: "not-applicable",
+        restoreMount: "not-applicable"
+      }
     },
     ensureHost,
     async list() {