@claxedo/sandbox-manager

@claxedo/sandbox-manager handles sandbox placement and lease management for running @claxedo/workspace-runtime inside provider sandboxes. It owns the generic pieces — SandboxManager, epoch-based SandboxLease, SandboxTarget, SandboxLeaseStore, and SandboxDriver — plus provider drivers for Cloudflare, Daytona, Docker, fetch bridge, Modal, and Vercel. It deliberately does not own product auth, billing, schema, routes, or relay tokens; applications supply those through adapters and call createSandboxManager.

Install

npm install @claxedo/sandbox-manager

Quickstart

Construct a manager with a lease store and a provider driver, then ensure a workspace’s sandbox exists:

import { createSandboxManager } from "@claxedo/sandbox-manager"
import { createMemoryLeaseStore } from "@claxedo/sandbox-manager/stores/memory"
import { createDockerSandboxDriver } from "@claxedo/sandbox-manager/drivers/docker"

const manager = createSandboxManager({
  leaseStore: createMemoryLeaseStore(),
  driver: createDockerSandboxDriver({ image: "ghcr.io/acme/workspace-sandbox:latest" }),
  appLabel: "my-product", // ownership filter for GC; defaults to "claxedo"
})

const target = await manager.ensure("ws_1", { homeRegion: "us-east" })

Credentials & secrets

There are two channels for getting values into a sandbox, chosen by whether the code inside is trusted with the raw value:

env — ordinary readable environment variables, for credentials the agent is meant to hold (e.g. the user’s own model API key).
secrets — brokered credentials the sandbox can use on outbound requests but never read. The raw value never enters the sandbox; the provider injects it on egress to an allowlist of hosts.

await manager.ensure("ws_1", {
  homeRegion: "us-east",
  secrets: [{
    name: "NOTION_TOKEN",
    value: notionToken,          // never enters the sandbox in plaintext
    hosts: ["api.notion.com"],   // injected only for these hosts
    header: "Authorization",
  }],
})

Key capabilities

Epoch leases — deterministic placement with stale-lease reclamation and bounded retry/backoff.
Drivers (/drivers/{cloudflare,daytona,docker,modal,vercel,fetch-bridge}) — pluggable per-provider placement.
Brokered-secret support matrix — Daytona and Vercel are native, Cloudflare is proxy (via /drivers/cloudflare-egress), Modal and Docker/fetch are none.

Full API

See the README on GitHub for the full credential/secret model and the per-provider brokering mechanism table.