@claxedo/sandbox-manager 0.5.1

package/dist/drivers/cloudflare.mjs

@@ -0,0 +1,151 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+
+// 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/cloudflare.ts
+var DEFAULT_WORKSPACE_DIR = "/workspace";
+var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
+var DEFAULT_TIMEOUT_MS = 12e4;
+function cleanUrl(input) {
+  return input.replace(/\/+$/, "");
+}
+function sandboxIdFor(workspaceId) {
+  return `claxedo-${workspaceId}`;
+}
+function createCloudflareSandboxDriver(options) {
+  const doFetch = options.fetch ?? fetch;
+  const runtimePort = options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
+  const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
+  const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const base = cleanUrl(options.workerUrl);
+  const headers = {
+    Authorization: `Bearer ${options.apiToken}`,
+    "Content-Type": "application/json"
+  };
+  async function call(sandboxId, action, body, method = "POST") {
+    const url = `${base}/sandbox/${encodeURIComponent(sandboxId)}${action ? `/${action}` : ""}`;
+    const res = await doFetch(url, {
+      method,
+      headers,
+      ...method === "POST" ? { body: JSON.stringify(body) } : {},
+      signal: AbortSignal.timeout(timeoutMs)
+    });
+    const data = await res.json().catch(() => ({}));
+    return { status: res.status, data };
+  }
+  function workspaceDirectory(input) {
+    return input.workspaceRoot ?? workspaceDir;
+  }
+  async function bootEnv(input, hostId) {
+    const env = {
+      ...workspaceRuntimeTargetEnv({
+        workspaceId: input.workspaceId,
+        hostId,
+        directory: workspaceDirectory(input),
+        port: runtimePort,
+        host: "0.0.0.0"
+      }),
+      ...workspaceRuntimeSourceEnv({ source: input.source }),
+      ...input.env,
+      ...await options.env?.(input, { id: hostId })
+    };
+    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
+    if (options.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = options.controlEnv.relayJwksUrl;
+    if (options.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = options.controlEnv.relayVerifyPem;
+    if (options.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = options.controlEnv.managementJwksUrl;
+    return env;
+  }
+  function egressRegistrations(input) {
+    if (!input.secrets?.length) return void 0;
+    return input.secrets.map((secret) => {
+      if (!secret.header) {
+        throw new Error(
+          `cloudflare brokered secret "${secret.name}" requires a header \u2014 the egress proxy injects the value as an HTTP header`
+        );
+      }
+      if (secret.hosts.length === 0) {
+        throw new Error(`cloudflare brokered secret "${secret.name}" requires at least one host in its egress allowlist`);
+      }
+      return { hosts: secret.hosts, header: secret.header, value: secret.value };
+    });
+  }
+  async function ensureHost(input) {
+    const sandboxId = sandboxIdFor(input.workspaceId);
+    const hostId = sandboxId;
+    const egress = egressRegistrations(input);
+    const { status, data } = await call(
+      sandboxId,
+      "ensure-runtime",
+      {
+        env: await bootEnv(input, hostId),
+        port: runtimePort,
+        command: runtimeCommand,
+        ...egress ? { egress } : {}
+      }
+    );
+    if (status >= 500) return { provisioning: true, retryAfterMs: 2e3 };
+    if (status >= 400 || !data?.url) {
+      throw new Error(`Cloudflare ensure-runtime failed (${status}): ${data?.error ?? "no runtime url"}`);
+    }
+    const targetOut = {
+      workspaceId: input.workspaceId,
+      sandboxId,
+      url: data.url,
+      hostId,
+      driverResourceId: sandboxId,
+      driver: {
+        id: "cloudflare",
+        resourceId: sandboxId
+      },
+      labels: input.labels
+    };
+    return targetOut;
+  }
+  return {
+    id: "cloudflare",
+    metadata: {
+      driverRunsIn: ["worker"],
+      hostStopBehavior: "not-supported",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "proxy"
+    },
+    ensureHost,
+    async touch(target) {
+      await call(target.sandboxId, "touch-runtime", { port: runtimePort }).catch(() => void 0);
+    },
+    async stop(target) {
+      void target;
+    },
+    async destroy(target) {
+      const { status } = await call(target.sandboxId, "", {}, "DELETE");
+      if (status >= 400 && status !== 404) {
+        throw new Error(`Cloudflare destroy failed (${status}) for ${target.sandboxId}`);
+      }
+    }
+  };
+}
+export {
+  createCloudflareSandboxDriver
+};

package/dist/drivers/daytona.d.ts

@@ -0,0 +1,94 @@
+import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+export type DaytonaSandboxLike = {
+    id: string;
+    state?: string;
+    labels?: Record<string, string>;
+    process: {
+        executeCommand: (command: string, cwd?: string, env?: Record<string, string>, timeout?: number) => Promise<unknown>;
+    };
+    getPreviewLink: (port: number) => Promise<{
+        url?: string;
+        token?: string;
+    }>;
+    getSignedPreviewUrl: (port: number, expiresInSeconds?: number) => Promise<{
+        url?: string;
+        token?: string;
+    }>;
+    refreshActivity: () => Promise<void>;
+    start: (timeout?: number) => Promise<void>;
+    stop: (timeout?: number) => Promise<void>;
+    delete: (timeout?: number) => Promise<void>;
+};
+export type DaytonaClientLike = {
+    findByLabels?: (labels: Record<string, string>) => Promise<DaytonaSandboxLike | undefined>;
+    list?: (labels?: Record<string, string>, page?: number, limit?: number) => Promise<{
+        items?: DaytonaSandboxLike[];
+    }>;
+    create: (params: {
+        name?: string;
+        image?: string;
+        snapshot?: string;
+        envVars?: Record<string, string>;
+        /** Env-var-name → Daytona secret-name references (brokered secrets). */
+        secrets?: Record<string, string>;
+        labels?: Record<string, string>;
+        public?: boolean;
+        autoStopInterval?: number;
+        autoDeleteInterval?: number;
+        networkBlockAll?: boolean;
+        networkAllowList?: string;
+    }, options?: {
+        timeout?: number;
+    }) => Promise<DaytonaSandboxLike>;
+    get: (sandboxIdOrName: string) => Promise<DaytonaSandboxLike>;
+    /**
+     * Create-or-update an org secret whose value is only substituted by
+     * Daytona's egress proxy for requests to `hosts`
+     * (https://www.daytona.io/docs/en/secrets/). Referenced from `create`'s
+     * `secrets` map; inside the sandbox the env var holds only an opaque
+     * `dtn_secret_…` placeholder, never the value.
+     */
+    upsertSecret?: (params: {
+        name: string;
+        value: string;
+        hosts: string[];
+    }) => Promise<void>;
+};
+export type DaytonaSandboxDriverOptions = {
+    /** Daytona API base URL. Defaults to the SDK default. */
+    apiUrl?: string;
+    /** Daytona API key. */
+    apiKey: string;
+    /** Optional Daytona organization id. */
+    organizationId?: string;
+    /** Optional Daytona target/region. */
+    target?: string;
+    /** Snapshot the sandbox boots from. */
+    baseSnapshot: string;
+    /** Port the workspace-runtime listens on inside the sandbox. */
+    runtimePort?: number;
+    /** Path to the workspace-runtime binary inside the image. */
+    runtimeCommand?: string;
+    /** Workspace directory inside the sandbox. */
+    workspaceDir?: string;
+    /** Default runner injected as WORKSPACE_RUNTIME_RUNNER. */
+    runner?: string;
+    /** Static control-plane config injected so the runtime verifies relay-proxied requests. */
+    controlEnv?: {
+        relayJwksUrl?: string;
+        relayVerifyPem?: string;
+        managementJwksUrl?: string;
+    };
+    /** Dynamic runtime env that needs the acquired sandbox id or current lease. */
+    env?: (input: SandboxDriverEnsureInput, sandbox: DaytonaSandboxLike) => Record<string, string> | Promise<Record<string, string>>;
+    /** Auto-stop / auto-delete policy, in minutes. */
+    autoStopMinutes?: number;
+    autoDeleteMinutes?: number;
+    /** Signed preview URL expiry, in seconds. */
+    previewExpirySeconds?: number;
+    /** Daytona SDK operation timeout, in seconds. */
+    operationTimeoutSeconds?: number;
+    /** Injected for tests. */
+    client?: DaytonaClientLike;
+};
+export declare function createDaytonaSandboxDriver(options: DaytonaSandboxDriverOptions): SandboxDriver;

package/dist/drivers/daytona.mjs

@@ -0,0 +1,235 @@
+import { createRequire as __createRequire } from 'module';var require = __createRequire(import.meta.url);
+
+// src/drivers/daytona.ts
+import { Daytona } from "@daytona/sdk";
+
+// src/daytona-allow-list.ts
+function formatDaytonaAllowList(cidrs) {
+  return cidrs.slice(0, 10).join(",");
+}
+
+// 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/command.ts
+function shell(input) {
+  return `'${input.replace(/'/g, `'"'"'`)}'`;
+}
+
+// src/constants.ts
+var DEFAULT_WORKSPACE_RUNTIME_PORT = 2593;
+
+// src/drivers/daytona.ts
+var DEFAULT_RUNTIME_COMMAND = "/usr/local/bin/workspace-runtime";
+var DEFAULT_WORKSPACE_DIR = "/workspace";
+var DEFAULT_PREVIEW_EXPIRY_S = 3600;
+var DEFAULT_OPERATION_TIMEOUT_S = 60;
+function labelName(workspaceId) {
+  return `claxedo-${workspaceId}`;
+}
+function daytonaSecretName(workspaceId, secretName) {
+  const safe = (value) => value.replace(/[^a-zA-Z0-9_-]+/g, "-");
+  return `claxedo-${safe(workspaceId)}-${safe(secretName)}`;
+}
+function transientDriverError(err) {
+  const shaped = err;
+  const status = shaped.response?.status ?? shaped.status;
+  if (typeof status === "number" && status >= 500) return true;
+  const text = `${shaped.name ?? ""} ${shaped.message ?? ""}`.toLowerCase();
+  return text.includes("timeout") || text.includes("pending") || text.includes("starting");
+}
+function createDefaultClient(options) {
+  const sdk = new Daytona({
+    apiKey: options.apiKey,
+    ...options.apiUrl ? { apiUrl: options.apiUrl } : {},
+    ...options.organizationId ? { organizationId: options.organizationId } : {},
+    ...options.target ? { target: options.target } : {},
+    _experimental: { otelEnabled: false }
+  });
+  return {
+    async findByLabels(labels) {
+      for await (const sandbox of sdk.list({ labels })) return sandbox;
+      return void 0;
+    },
+    create(params, operation) {
+      if (params.image) return sdk.create({ ...params, image: params.image }, operation);
+      return sdk.create(params, operation);
+    },
+    get: (sandboxIdOrName) => sdk.get(sandboxIdOrName),
+    async upsertSecret({ name, value, hosts }) {
+      await sdk.secret.create({ name, value, hosts });
+    }
+  };
+}
+function createDaytonaSandboxDriver(options) {
+  const client = options.client ?? createDefaultClient(options);
+  const runtimePort = options.runtimePort ?? DEFAULT_WORKSPACE_RUNTIME_PORT;
+  const runtimeCommand = options.runtimeCommand ?? DEFAULT_RUNTIME_COMMAND;
+  const workspaceDir = options.workspaceDir ?? DEFAULT_WORKSPACE_DIR;
+  const previewExpiry = options.previewExpirySeconds ?? DEFAULT_PREVIEW_EXPIRY_S;
+  const operationTimeout = options.operationTimeoutSeconds ?? DEFAULT_OPERATION_TIMEOUT_S;
+  function workspaceDirectory(input) {
+    return input.workspaceRoot ?? workspaceDir;
+  }
+  function staticBootEnv(input, hostId, directory) {
+    const env = {
+      ...workspaceRuntimeTargetEnv({
+        workspaceId: input.workspaceId,
+        hostId,
+        directory,
+        port: runtimePort
+      }),
+      ...workspaceRuntimeSourceEnv({ source: input.source }),
+      ...input.env
+    };
+    if (options.runner) env.WORKSPACE_RUNTIME_RUNNER = options.runner;
+    if (options.controlEnv?.relayJwksUrl) env.WORKSPACE_RUNTIME_RELAY_JWKS_URL = options.controlEnv.relayJwksUrl;
+    if (options.controlEnv?.relayVerifyPem) env.WORKSPACE_RUNTIME_RELAY_HOST_VERIFY_PEM = options.controlEnv.relayVerifyPem;
+    if (options.controlEnv?.managementJwksUrl) env.WORKSPACE_RUNTIME_MANAGEMENT_JWKS_URL = options.controlEnv.managementJwksUrl;
+    return env;
+  }
+  async function bootEnv(input, sandbox, hostId) {
+    return {
+      ...staticBootEnv(input, hostId, workspaceDirectory(input)),
+      ...await options.env?.(input, sandbox)
+    };
+  }
+  async function findExisting(workspaceId) {
+    const labels = { "claxedo.workspaceId": workspaceId };
+    if (client.findByLabels) return client.findByLabels(labels).catch(() => void 0);
+    const result = await client.list?.(labels, 1, 1).catch(() => void 0);
+    return result?.items?.[0];
+  }
+  async function sandboxById(sandboxId) {
+    return client.get(sandboxId);
+  }
+  async function previewUrl(sandbox) {
+    const signed = await sandbox.getSignedPreviewUrl(runtimePort, previewExpiry).catch(() => void 0);
+    if (signed?.url) return signed;
+    return sandbox.getPreviewLink(runtimePort).catch(() => void 0);
+  }
+  async function startRuntime(sandbox, input, env) {
+    const directory = workspaceDirectory(input);
+    const script = `if (command -v ss >/dev/null && ss -ltn 2>/dev/null | grep -q :${runtimePort}); then exit 0; fi; mkdir -p ${shell(directory)}; cd ${shell(directory)}; nohup ${runtimeCommand} > /tmp/claxedo-wr.log 2>&1 & sleep 1`;
+    await sandbox.process.executeCommand(`sh -lc ${shell(script)}`, directory, env, operationTimeout).catch(() => void 0);
+  }
+  async function ensureStarted(sandbox) {
+    if (!sandbox.state || sandbox.state === "started") return true;
+    if (sandbox.state === "starting") return false;
+    await sandbox.start(operationTimeout).catch(() => void 0);
+    return sandbox.state === "started";
+  }
+  async function readyTarget(input, sandbox, hostId) {
+    await startRuntime(sandbox, input, await bootEnv(input, sandbox, hostId));
+    const preview = await previewUrl(sandbox);
+    if (!preview?.url) return { provisioning: true, retryAfterMs: 2e3 };
+    const target = {
+      workspaceId: input.workspaceId,
+      sandboxId: sandbox.id,
+      url: preview.url,
+      hostId,
+      driverResourceId: sandbox.id,
+      driver: {
+        id: "daytona",
+        resourceId: sandbox.id
+      },
+      labels: { ...input.labels, ...preview.token ? { "daytona.previewToken": preview.token } : {} }
+    };
+    return target;
+  }
+  async function brokeredSecretReferences(input) {
+    if (!input.secrets?.length) return {};
+    if (!client.upsertSecret) {
+      throw new Error("daytona sandbox client does not support secret brokering");
+    }
+    const references = {};
+    for (const secret of input.secrets) {
+      if (secret.hosts.length === 0) {
+        throw new Error(`daytona brokered secret "${secret.name}" requires at least one host in its egress allowlist`);
+      }
+      const secretName = daytonaSecretName(input.workspaceId, secret.name);
+      await client.upsertSecret({ name: secretName, value: secret.value, hosts: secret.hosts });
+      references[secret.name] = secretName;
+    }
+    return references;
+  }
+  async function ensureHost(input) {
+    const hostId = labelName(input.workspaceId);
+    const bootSource = input.bootSource?.kind === "image" ? { image: input.bootSource.image } : { snapshot: input.bootSource?.kind === "driver-snapshot" ? input.bootSource.snapshotId : input.snapshot ?? options.baseSnapshot };
+    const net = network(input);
+    const secrets = await brokeredSecretReferences(input);
+    const sandbox = await findExisting(input.workspaceId) ?? await client.create({
+      name: labelName(input.workspaceId),
+      ...bootSource,
+      envVars: staticBootEnv(input, hostId, workspaceDirectory(input)),
+      ...Object.keys(secrets).length ? { secrets } : {},
+      labels: { ...input.labels, "claxedo.workspaceId": input.workspaceId },
+      public: false,
+      ...net,
+      ...options.autoStopMinutes !== void 0 ? { autoStopInterval: options.autoStopMinutes } : {},
+      ...options.autoDeleteMinutes !== void 0 ? { autoDeleteInterval: options.autoDeleteMinutes } : {}
+    }, { timeout: operationTimeout }).catch((err) => {
+      if (transientDriverError(err)) return void 0;
+      throw err;
+    });
+    if (!sandbox) return { provisioning: true, retryAfterMs: 2e3 };
+    if (!await ensureStarted(sandbox)) return { provisioning: true, retryAfterMs: 2e3 };
+    return readyTarget(input, sandbox, hostId);
+  }
+  return {
+    id: "daytona",
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "native"
+    },
+    ensureHost,
+    async resumeHost(input) {
+      const sandbox = await sandboxById(input.lease.sandboxId);
+      if (!await ensureStarted(sandbox)) return { provisioning: true, retryAfterMs: 2e3 };
+      return readyTarget(input.ensure, sandbox, input.ensure.hostId ?? labelName(input.ensure.workspaceId));
+    },
+    async touch(target) {
+      await sandboxById(target.sandboxId).then((sandbox) => sandbox.refreshActivity()).catch(() => void 0);
+    },
+    async suspend(target) {
+      await sandboxById(target.sandboxId).then((sandbox) => sandbox.stop(operationTimeout)).catch(() => void 0);
+    },
+    async stop(target) {
+      await sandboxById(target.sandboxId).then((sandbox) => sandbox.stop(operationTimeout)).catch(() => void 0);
+    },
+    async destroy(target) {
+      await sandboxById(target.sandboxId).then((sandbox) => sandbox.delete(operationTimeout)).catch((err) => {
+        const status = err.response?.status ?? err.status;
+        if (status !== 404) throw err;
+      });
+    }
+  };
+}
+function network(input) {
+  if (!input.net || input.net.mode === "allow-all") return {};
+  const cidrs = input.net.cidrs ?? [];
+  if (cidrs.length === 0) return { networkBlockAll: true };
+  return { networkAllowList: formatDaytonaAllowList(cidrs) };
+}
+export {
+  createDaytonaSandboxDriver
+};

package/dist/drivers/docker.d.ts

@@ -0,0 +1,36 @@
+import type { SandboxDriver, SandboxDriverEnsureInput } from "..";
+type SandboxEnv = Record<string, string | undefined>;
+export type DockerCommandResult = {
+    stdout?: string | Buffer;
+    stderr?: string | Buffer;
+};
+export type DockerCommandRunner = (args: string[], timeoutMs?: number) => Promise<DockerCommandResult>;
+export type DockerSandboxDriverOptions = {
+    image: string;
+    runtimePort?: number;
+    runtimeCommand?: string;
+    workspaceDir?: string;
+    runner?: string;
+    env?: (input: SandboxDriverEnsureInput, host: {
+        id: string;
+    }) => Record<string, string> | Promise<Record<string, string>>;
+    syncLocalAuth?: boolean;
+    authHome?: string;
+    operationTimeoutMs?: number;
+    docker?: DockerCommandRunner;
+};
+export declare function dockerSandboxSyncLocalAuth(env?: SandboxEnv): boolean;
+export declare function dockerSandboxAuthHome(env?: SandboxEnv): string;
+export declare function dockerSandboxImageFromEnv(env?: SandboxEnv): string;
+export declare function parseDockerPort(input: string): string | undefined;
+export declare function dockerLocalAuthCandidates(home: string): ({
+    kind: "file";
+    source: string;
+    target: string;
+} | {
+    kind: "dir";
+    source: string;
+    target: string;
+})[];
+export declare function createDockerSandboxDriver(options: DockerSandboxDriverOptions): SandboxDriver;
+export {};