@claxedo/sandbox-manager 0.10.1 → 0.10.3

package/README.md

@@ -70,7 +70,8 @@ await manager.stop("workspace-1")
 
 Swap `createDockerSandboxDriver` for `createModalSandboxDriver`,
 `createVercelSandboxDriver`,
-`createCloudflareSandboxDriver`, or `createBoatSandboxDriver` (all under
+`createCloudflareSandboxDriver`, `createBoatSandboxDriver`, or
+`createAgent37SandboxDriver` (all under
 `@claxedo/sandbox-manager/drivers/*`) to place on a hosted provider instead —
 see [`docs/architecture.md`](docs/architecture.md) for the full driver
 comparison and each provider's required options. Swap `createMemoryLeaseStore`
@@ -83,6 +84,37 @@ tail and container exit information, with staged environment and registry secret
 values redacted before truncation. A diagnostic request failure preserves the
 original health failure.
 
+### Agent37: one container per instance
+
+An Agent37 instance runs one container of a registered image in a gVisor
+sandbox with a disk of its own, so the driver has no VM to prepare. It
+registers the sandbox image as a template on the account the first time that
+account boots it (34 s for the 3.7 GB image), named from the image and the
+command, with a command that boots the runtime. The boot env travels as the
+one instance variable `CLAXEDO_RUNTIME_ENV`, a sourceable script the command
+evaluates and unsets: Agent37 merges an env edit into what it stores and never
+returns the stored names, so separate variables could not be cleared at a later
+boot. The runtime's port is a public port of the instance, a URL that asks for
+no credential, and the runtime authenticates every route but `/global/health`.
+
+A stop keeps the whole filesystem except `/tmp` and releases CPU and memory;
+the disk is billed until the instance is deleted. A resume stores the boot's
+env, network policy and labels, then starts the instance, which is what hands a
+new container the stored env. An image update (`update` onto the new image's
+template) keeps only the instance's mount path, `/claxedo-persistent`, so the
+workspace, `~/.claxedo` and `~/.workspace-runtime` are symlinks into it; the
+sandbox refuses bind mounts. A resume keeps the image the instance last ran
+unless the person asked for the deployment's or its runtime is older than
+`MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION`.
+
+Measured 2026-11-11 with `scripts/agent37-live-check.ts` on the 2 vCPU / 4 GB
+shape, from the driver call to the runtime's first healthy answer: 3.5 s cold
+with the template registered (33 s the first time a host pulled the image),
+1.1 s to stop, 4.2 s to resume, 5.7 s to resume a running instance onto another
+size. A runtime that cannot start is reported 13 s after the create with its
+container's log. Not measured: Codex's command sandbox under gVisor, which
+refused `unshare -m` as root and has no `bwrap` on the image's path.
+
 ### Boat: what survives a stop, and what survives an image update
 
 A Boat sandbox is a Linux VM whose disk Boat snapshots at every stop; the
@@ -108,7 +140,13 @@ nothing. Without a template, or when the organization's key cannot read it, or
 for any other image, the first start seeds them. The seed runs once per image, at the start that first names it: it pulls the
 image, streams the trees out of a created container of it with `docker cp` and
 unpacks them as root, leaving out `~/.cache` (which Boat's own snapshots leave
-out too) and npm's cache. The persistent root is created as root too: Docker
+out too) and npm's cache. Boat's link to ghcr resets mid-pull (2 of 8 staging
+updates, `failed to copy: … connection reset by peer`), and
+Docker ends a pull at the first reset, keeping the layers it finished and none
+of the ones in flight. So the pull runs again after a transport failure
+(connection reset, unexpected EOF, a timeout) for as long as each run finishes
+a layer no run before it did; any other failure, and a run that finished
+nothing new, fails the boot with the pull's own output. The persistent root is created as root too: Docker
 made it as root on every sandbox that booted before the trees existed, and the
 VM user cannot create inside it. The seed then saves beside the trees what the
 container needs besides them: the image's env (`image.env`, given to the
@@ -152,9 +190,35 @@ the container leaves `running`/`paused`. A sandbox still archiving from a stop,
 which Boat offers no wait for, is read again after 250 ms, doubling to 2 s.
 
 A wake that pulled (before the stub) took 57–77 s, and failed when ghcr reset
-the connection. An image update re-seeds:
-the new image is pulled and seeded as above, its stub replaces the old one, and
-the old image's trees are removed.
+the connection. A wake whose machine holds only an older image keeps serving
+that image: its trees, stub and env are there, and the runtime in them is no
+older than `MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION`. The wake answers
+with that image's label, so the workspace reads as outdated, instead of waiting
+60–100 s on the new image's pull and seed (staging). The update
+runs only when a start asks for it with `updateImage` (a person's Restart to
+update): the new image is pulled and seeded as above, its stub replaces the
+old one, and the old image's trees are removed. That step is a start of its
+own on the serving lease's epoch, whose phases are timed from the update. An
+update whose step fails leaves the lease serving its image and answers the
+start with the driver's reason, which the manager logs, and a start asking for
+the update of a workspace already serving the deployment's image answers it as
+it is. A cold start, and a wake whose older runtime is
+below the floor, takes the new image at once. On staging (0.10.1
+to 0.10.2) the wake that kept the image answered in 22 s and the update's step
+ran 92.7 s.
+
+`MINIMUM_SERVED_WORKSPACE_RUNTIME_VERSION` (`src/runtime-version.ts`) is the one
+floor for every driver: the oldest runtime this control plane and relay serve,
+whether a Cloudflare restore brings it back or a Boat wake keeps it. Below it a
+workspace updates and keeps its files on every driver: a Boat wake takes the
+new image over the same `/workspace` and homes, and a Cloudflare restore
+carries the repository and HOME into the current image. A runtime
+security fix, or a control-plane or relay contract an older runtime cannot
+speak, raises the floor and the workspace-runtime version together, in the
+commit that makes the change; a test keeps the floor at or below the runtime
+version the tree builds. Each connection names the image it serves
+(`runtimeImage`), and every mint of an outdated one is the
+`sandbox.runtime_outdated_served` event.
 
 A start runs as two commands: the preparation (daemon, login, seed, stub)
 changes nothing a running container serves from, so its failure leaves a
@@ -220,9 +284,12 @@ no runtime state and no boot env (`boatTemplateResetCommand`). On Boat,
 Lifecycle, in `drivers/boat-template.ts`, run by
 `bun run --cwd packages/claxedo-server sandbox:boat-template --image=<image>`:
 
-1. **Name.** `claxedo-rt-` and the first 12 hex digits of the SHA-256 of the
+1. **Name.** A prefix and the first 12 hex digits of the SHA-256 of the
    image reference. The reference is content-addressed (its tag names the
-   build) and names the trees directory, so it is the template's key.
+   build) and names the trees directory, so it is the template's key. The
+   prefix defaults to `claxedo-rt-`; deploy-cloud.yml passes
+   `--prefix=claxedo-rt-<environment>-`, since one Boat account holds every
+   environment's templates and pruning (step 5) works within a prefix.
 2. **Build, once per image.** A ready template is reused and one still saving
    is waited for; a missing or failed one is built on a builder sandbox: the
    Boat driver boots the image there (pull, seed, stub, runtime healthy), the
@@ -337,28 +404,31 @@ spend the owner's delivered accounts (owner ruling, 2026-09-28).
 ## Egress containment
 
 `SandboxManagerInput.net` restricts what the sandbox can reach on the network.
-It is a *separate* control from brokered secrets, with a **different** posture,
-and the difference matters:
-
-- **Brokered secrets fail closed.** A driver that cannot broker refuses to
-  provision (`error: "secret_brokering_unsupported"`).
-- **Egress does not.** Only `vercel` (names) can enforce an allowlist. Every
-  other driver declares `metadata.egressControl: "none"`, and for those the
-  manager **withholds** the policy and provisions anyway — the sandbox runs
-  with unrestricted egress.
-
-Withholding rather than passing is deliberate: `docker`, `modal` and `boat`
-throw when handed a restricted policy, and `cloudflare` and the fetch
-bridge accept one and silently ignore it. Withholding at the manager means the
-throwing drivers never see a policy (their throws stay as their own last line of
-defence) and the silently-dropping ones stop pretending.
-
-The gap is never silent. `createSandboxManager` warns at composition, and again
-each time a policy is withheld:
+It is a *separate* control from brokered secrets, and both fail closed:
+
+- **Brokered secrets.** A driver that cannot broker refuses to provision
+  (`error: "secret_brokering_unsupported"`).
+- **Egress.** `cloudflare` and `vercel` (names) and `agent37` (names and IPv4
+  ranges) enforce an allowlist. `docker`,
+  `modal` and `boat` declare `metadata.egressControl: "none"` and throw when
+  handed a restricted policy, so a start with one on those drivers is refused
+  before a lease exists (`error: "sandbox_egress_uncontained:<driver>"`), and
+  `sandboxStartFailureReason` turns that into the one line a person reads.
+
+A start may instead pass `uncontainedEgress: "allow"` in its
+`SandboxManagerInput`: the manager then **withholds** the policy and provisions
+anyway, so the sandbox runs with unrestricted egress. The setting is read per
+start, not composed into the manager, because it is the workspace owner's
+decision (the hosted control plane reads its organization's opt-in at each
+start), and a withdrawn allowance refuses the very next start. Withholding
+rather than passing keeps the throwing drivers' throws as their own last line
+of defence. That gap is never silent: the manager warns on the first withheld
+start per driver per isolate:
 
 ```text
-[sandbox-manager] SANDBOX EGRESS IS UNRESTRICTED: driver "cloudflare" declares
-egressControl: "none", so workspace ws_1 can reach ANY host on the internet …
+[sandbox-manager] SANDBOX EGRESS IS UNRESTRICTED: driver "boat" declares
+egressControl: "none" and this start allows uncontained egress, so
+workspace ws_1 can reach ANY host on the internet …
 ```
 
 Pass `onEgressUnenforced` to route that into telemetry instead of `console.warn`
@@ -366,9 +436,9 @@ Pass `onEgressUnenforced` to route that into telemetry instead of `console.warn`
 replaces the console warning, so only do it if the replacement is as visible.
 
 `driver.metadata.egressControl` is the machine-readable source of truth, and
-`sandboxEgressDisposition(control, net)` is the pure predicate the manager uses,
-so you can ask the same question before composing. One exception stays fail
-closed: a hosts-only driver handed an address-only policy is refused
+`sandboxEgressDisposition(control, net, uncontained)` is the pure predicate the
+manager uses, so you can ask the same question before composing. A hosts-only
+driver handed an address-only policy is refused
 (`sandbox_egress_policy_unenforceable`) rather than degraded, because that
 driver *does* enforce egress — it just cannot express that encoding.
 

package/dist/checkpoint-manager.mjs

@@ -21,6 +21,11 @@ var PUBLIC_API_ERRORS = {
   org_invitation_invalid: { family: "access", status: 409, message: "Invitation is invalid or unavailable" },
   org_invitation_pending: { family: "access", status: 409, message: "An invitation to this address is already pending" },
   org_invitation_rate_limited: { family: "access", status: 429, message: "Organization invitation limit exceeded" },
+  org_limit_reached: { family: "access", status: 403, message: "An account owns at most 3 organizations" },
+  org_creation_rate_limited: { family: "access", status: 429, message: "Organization creation limit exceeded" },
+  project_limit_reached: { family: "access", status: 402, message: "Free accounts have 3 projects. Get Cloud or Self-host for unlimited projects." },
+  seats_full: { family: "access", status: 402, message: "Add teammate seats to invite more people." },
+  email_verification_required: { family: "access", status: 403, message: "A verified email address is required" },
   org_invitation_email_mismatch: { family: "access", status: 403, message: "Sign in with the invited verified email address" },
   org_invitation_delivery_unavailable: { family: "access", status: 503, message: "Invitation delivery is unavailable" },
   team_not_found: { family: "access", status: 404, message: "Team not found" },
@@ -30,6 +35,12 @@ var PUBLIC_API_ERRORS = {
   project_member_not_found: { family: "access", status: 404, message: "Project member not found" },
   project_member_owner_immutable: { family: "access", status: 409, message: "The project owner's access cannot be changed" },
   resource_conflict: { family: "access", status: 409, message: "Organization or team authority changed concurrently" },
+  org_not_deletable: { family: "access", status: 409, message: "A personal organization goes with its account, and a deployment's with the deployment" },
+  org_has_workspaces: { family: "access", status: 409, message: "Delete the organization's workspaces first" },
+  account_owns_workspaces: { family: "access", status: 409, message: "Delete your workspaces first" },
+  account_founds_organization: { family: "access", status: 409, message: "Delete the organizations you founded first" },
+  account_has_cloud_subscription: { family: "access", status: 409, message: "Cancel Cloud before deleting this account" },
+  recent_sign_in_required: { family: "access", status: 403, message: "Sign in again to confirm this deletion" },
   session_not_found: { family: "session_share", status: 404, message: "This session is not on the control plane, so it cannot be shared from People yet." },
   session_share_admin_required: { family: "session_share", status: 403, message: "Only the person who started this session can manage its People." },
   session_share_target_required: { family: "session_share", status: 400, message: "A session is shared with exactly one person" },
@@ -53,11 +64,19 @@ var PUBLIC_API_ERRORS = {
   enrollment_paused: { status: 403, message: "enrollment_paused" },
   enrollment_owner_ineligible: { status: 403, message: "enrollment_owner_ineligible" },
   enrollment_key_version_mismatch: { status: 403, message: "enrollment_key_version_mismatch" },
+  enrollment_denied: { status: 403, message: "enrollment_denied" },
+  enrollment_approval_expired: { status: 403, message: "enrollment_approval_expired" },
+  enrollment_awaiting_approval: { status: 403, message: "enrollment_awaiting_approval" },
   invitation_invalid: { status: 403, message: "invitation_invalid" },
   invitation_expired: { status: 410, message: "invitation_expired" },
   invitation_revoked: { status: 410, message: "invitation_revoked" },
   invitation_redeemed: { status: 409, message: "invitation_redeemed" },
   invitation_host_conflict: { status: 409, message: "invitation_host_conflict" },
+  pairing_invalid: { status: 403, message: "pairing_invalid" },
+  pairing_expired: { status: 410, message: "pairing_expired" },
+  pairing_used: { status: 409, message: "pairing_used" },
+  pairing_owner_signed_out: { status: 410, message: "pairing_owner_signed_out" },
+  pairing_decided: { status: 409, message: "pairing_decided" },
   enrollment_generation_superseded: { status: 409, message: "enrollment_generation_superseded" },
   host_assignment_outside_scope: { status: 400, message: "host_assignment_outside_scope" },
   host_sealing_key_undeclared: { status: 409, message: "host_sealing_key_undeclared" },

package/dist/contract.d.ts

@@ -3,7 +3,7 @@ import type { SandboxMachineClass, SandboxPhaseTiming, SandboxSecretBrokering, S
 export type { SandboxMachineClass, SandboxSecretBrokering } from "@claxedo/sandbox-contract";
 import { type SandboxCheckpointCaptureInput, type SandboxCheckpointRestoreInput, type SandboxCheckpointResult, type SandboxStopInput } from "./checkpoint-manager";
 import type { SandboxLifecycleEvent } from "./lease-lifecycle";
-import type { SandboxBrokeredSecret, SandboxEgressControl, SandboxEgressUnenforcedEvent, SandboxNetworkPolicy } from "./egress-policy";
+import type { SandboxBrokeredSecret, SandboxEgressControl, SandboxEgressUnenforcedEvent, SandboxNetworkPolicy, SandboxUncontainedEgress } from "./egress-policy";
 import type { SandboxLeaseFailure } from "./lease-failure";
 export { DEFAULT_WORKSPACE_RUNTIME_PORT };
 export type SandboxRegion = string;
@@ -101,18 +101,20 @@ export type SandboxDriverMetadata = {
      * else; the encodings are alternatives, not additive requirements.
      *
      * - `"hosts-and-cidrs"` — the provider filters by name AND by address.
-     * - `"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 (docker, boat,
-     *   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.
+     * - `"hosts"` — the provider filters by hostname only (the Vercel firewall;
+     *   the Cloudflare container started without internet, with each allowed
+     *   host routed through the sandbox Worker).
+     * - `"none"` — the driver cannot express an egress allowlist: docker, boat
+     *   and modal throw when handed a restricted policy. 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
+     * `sandboxEgressDisposition` enforces where it can, and where it cannot
+     * refuses the start unless the start allows uncontained egress
+     * (`SandboxManagerInput.uncontainedEgress`), in which case the policy is
+     * withheld and the gap reported. See `SandboxEgressDisposition` and
      * `public-docs/sandbox-egress.md` for the operator-facing consequence.
      */
     egressControl: SandboxEgressControl;
@@ -337,6 +339,13 @@ export type SandboxDriverEnsureInput = {
     net?: SandboxNetworkPolicy;
     /** Optional snapshot/image to boot from (user-supplied or pre-built). */
     snapshot?: string;
+    /**
+     * The person asked for the deployment's image. Without it, a resume of a
+     * machine that holds only an older image may keep serving that one and
+     * report it, so the workspace reads as outdated instead of waiting on the
+     * new image's preparation.
+     */
+    updateImage?: true;
 };
 export type SandboxTarget = {
     workspaceId?: string;
@@ -498,11 +507,23 @@ export type SandboxManagerInput = {
     source?: SandboxSource;
     exposure?: SandboxExposure;
     /**
-     * @see SandboxDriverEnsureInput.net — enforced by a capable driver, withheld
-     * (with a warning) by one that declares `egressControl: "none"`.
+     * @see SandboxDriverEnsureInput.net — enforced by a capable driver; on one
+     * that declares `egressControl: "none"` the start is refused, or the policy
+     * withheld with a warning where `uncontainedEgress` allows it.
      */
     net?: SandboxNetworkPolicy;
+    /**
+     * What this start does with a restricted `net` on a driver that declares
+     * `egressControl: "none"`: refused (`sandbox_egress_uncontained`, the
+     * default), or allowed to run with the policy withheld and the gap reported
+     * through `onEgressUnenforced`. Allowing is the workspace owner's explicit
+     * decision, read per start so a withdrawn allowance refuses the next one:
+     * the sandbox then holds a private checkout and can reach any host.
+     */
+    uncontainedEgress?: SandboxUncontainedEgress;
     snapshot?: string;
+    /** @see SandboxDriverEnsureInput.updateImage */
+    updateImage?: true;
     /**
      * Called by the one ensure whose acquire created the workspace's first
      * lease, before its driver is asked for anything; a concurrent start that
@@ -551,6 +572,8 @@ export type SandboxEnsureResult = ({
      * delivered — the provider edge still holds the previous set.
      */
     stale?: true;
+    /** @see SandboxTargetResult */
+    imageOutdated?: true;
 }) | {
     status: "provisioning";
     retryAfterMs: number;
@@ -572,7 +595,7 @@ export type SandboxTargetResult = ({
     epoch: number;
     routingId?: string;
     homeRegion: SandboxRegion;
-    /** The runtime booted from an image other than the driver's current one; its next ensure boots the current one. */
+    /** The runtime booted from an image other than the driver's current one; an ensure asked to `updateImage` boots the current one. */
     imageOutdated?: true;
     /** The start that brought this epoch up, as observed; the run still delivering its settings is timed from it. */
     start?: SandboxEpochStart;
@@ -671,9 +694,9 @@ export type SandboxManagerOptions = {
     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.
+     * Sink for the warning raised the first time per driver per isolate that a
+     * start's restricted policy is withheld from a driver that cannot enforce it
+     * (`SandboxManagerInput.uncontainedEgress: "allow"`).
      *
      * Defaults to `console.warn(event.message)`. Pass your own to route the gap
      * into a telemetry pipeline instead — but note the default is deliberately

package/dist/driver-billing.d.ts

@@ -23,6 +23,29 @@ export type SandboxDriverBilling = {
     excludes?: string;
 };
 export declare const boatBilling: SandboxDriverBilling;
+/**
+ * The shape an Agent37 instance of each class is created at. Agent37 sells four
+ * shapes and none above 4 vCPU, so `large` is its 4 vCPU / 16 GB one. The disk
+ * holds the workspace and the runtime's state and is billed while stopped too.
+ */
+export declare const agent37MachineShapes: {
+    readonly small: {
+        readonly cpu: 2;
+        readonly memory: 4;
+        readonly disk: 10;
+    };
+    readonly default: {
+        readonly cpu: 4;
+        readonly memory: 8;
+        readonly disk: 20;
+    };
+    readonly large: {
+        readonly cpu: 4;
+        readonly memory: 16;
+        readonly disk: 40;
+    };
+};
+export declare const agent37Billing: SandboxDriverBilling;
 export declare const cloudflareBilling: SandboxDriverBilling;
 /** The rate a sandbox of this class runs at; a driver with one size answers it for the class it was not asked for. */
 export declare function sandboxMachineRate(billing: SandboxDriverBilling | undefined, machineClass: SandboxMachineClass | null): SandboxMachineRate | undefined;

package/dist/driver-catalog.mjs

@@ -26,6 +26,27 @@ var boatBilling = {
     large: { size: "large", vcpu: 8, memoryGb: 16, usdPerHour: 0.072 }
   }
 };
+var AGENT37_USD_PER_MONTH = { vcpu: 0.8, memoryGb: 0.7, diskGb: 0.09 };
+var AGENT37_MONTH_HOURS = 730;
+var agent37MachineShapes = {
+  small: { cpu: 2, memory: 4, disk: 10 },
+  default: { cpu: 4, memory: 8, disk: 20 },
+  large: { cpu: 4, memory: 16, disk: 40 }
+};
+function agent37Rate(shape) {
+  const usdPerMonth = shape.cpu * AGENT37_USD_PER_MONTH.vcpu + shape.memory * AGENT37_USD_PER_MONTH.memoryGb + shape.disk * AGENT37_USD_PER_MONTH.diskGb;
+  return { size: `${shape.cpu} vCPU / ${shape.memory} GB`, vcpu: shape.cpu, memoryGb: shape.memory, usdPerHour: usdPerMonth / AGENT37_MONTH_HOURS };
+}
+var agent37Billing = {
+  source: { url: "https://www.agent37.com/docs/agents-api/billing", readOn: "2026-11-11" },
+  meter: "Agent37 meters an instance per minute at a monthly rate over 730 hours: $0.80 per vCPU, $0.70 per GB of memory and $0.09 per GB of disk while it runs, and the disk alone while it is stopped.",
+  rates: {
+    small: agent37Rate(agent37MachineShapes.small),
+    default: agent37Rate(agent37MachineShapes.default),
+    large: agent37Rate(agent37MachineShapes.large)
+  },
+  excludes: `the disk of a stopped instance, billed at $${AGENT37_USD_PER_MONTH.diskGb} per GB a month until the instance is deleted`
+};
 var CLOUDFLARE_USD_PER_GIB_SECOND_MEMORY = 25e-7;
 var CLOUDFLARE_USD_PER_GB_SECOND_DISK = 7e-8;
 var CLOUDFLARE_USD_PER_VCPU_SECOND_ACTIVE = 2e-5;
@@ -61,7 +82,7 @@ function trimToUndefined(value) {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : void 0;
 }
-var sandboxDriverIds = ["modal", "vercel", "cloudflare", "boat", "docker"];
+var sandboxDriverIds = ["modal", "vercel", "cloudflare", "boat", "agent37", "docker"];
 var sandboxDriverCredentialFields = {
   modal: [
     { key: "token_id", label: "Token ID", secret: true },
@@ -77,6 +98,7 @@ var sandboxDriverCredentialFields = {
     { key: "worker_url", label: "Worker URL" }
   ],
   boat: [{ key: "api_key", label: "API Key", secret: true }],
+  agent37: [{ key: "api_key", label: "API Key", secret: true }],
   docker: [{ key: "image", label: "Image" }]
 };
 var sandboxDriverLabels = {
@@ -84,6 +106,7 @@ var sandboxDriverLabels = {
   vercel: "Vercel",
   cloudflare: "Cloudflare",
   boat: "Boat",
+  agent37: "Agent37",
   docker: "Docker"
 };
 function isSandboxDriverID(input) {
@@ -117,6 +140,10 @@ function sandboxDriverAuthValues(cfg, id, env = process.env) {
     const api_key = trimToUndefined(cfg?.auth?.boat?.api_key) ?? trimToUndefined(env.BOAT_API_KEY);
     return api_key ? { api_key } : void 0;
   }
+  if (id === "agent37") {
+    const api_key = trimToUndefined(cfg?.auth?.agent37?.api_key) ?? trimToUndefined(env.AGENT37_API_KEY);
+    return api_key ? { api_key } : void 0;
+  }
   if (!dockerSandboxDriverEnabled(env))
     return;
   const image = trimToUndefined(cfg?.auth?.docker?.image) ?? trimToUndefined(env.CLAXEDO_DOCKER_SANDBOX_IMAGE) ?? trimToUndefined(env.CLAXEDO_SANDBOX_IMAGE);
@@ -233,8 +260,8 @@ var sandboxDriverCatalog = {
       hostWatchesIdle: true,
       targetAccess: "relay",
       secretBrokering: "native",
-      // Credential handlers do not restrict unrelated destinations.
-      egressControl: "none",
+      // The sandbox Worker starts the container without internet and routes each allowed host through itself; a Worker that cannot confirm that refuses the start.
+      egressControl: "hosts",
       // A container snapshot holds the whole root filesystem; the platform keeps it 30 days past its last restore and offers no deletion.
       persistence: {
         resume: "replacement-restore",
@@ -272,6 +299,33 @@ var sandboxDriverCatalog = {
       machineClasses: ["small", "default", "large"]
     }
   },
+  agent37: {
+    id: "agent37",
+    label: sandboxDriverLabels.agent37,
+    credentialFields: sandboxDriverCredentialFields.agent37,
+    runtimeNetwork: { controlPlane: "direct", relay: "configured" },
+    runtimeEnv: "callback",
+    preparedImage: true,
+    billing: agent37Billing,
+    metadata: {
+      driverRunsIn: ["worker", "node"],
+      hostStopBehavior: "suspends-host",
+      hostResumeBehavior: "same-host",
+      targetAccess: "relay",
+      secretBrokering: "none",
+      // An instance's network policy lists domains, reached over HTTPS on 443 alone, and IPv4 ranges; private ranges stay blocked whatever it lists.
+      egressControl: "hosts-and-cidrs",
+      persistence: {
+        resume: "same-sandbox",
+        capture: "none",
+        clone: false,
+        captureSource: "not-applicable",
+        retention: "provider-managed",
+        restoreMount: "same-resource"
+      },
+      machineClasses: ["small", "default", "large"]
+    }
+  },
   docker: {
     id: "docker",
     label: sandboxDriverLabels.docker,

package/dist/driver-ensure-input.d.ts

@@ -0,0 +1,22 @@
+import type { SandboxDriver, SandboxDriverEnsureInput, SandboxLease, SandboxManagerInput, SandboxRegion } from "./contract";
+export declare function leaseHostId(driver: SandboxDriver, workspaceId: string, lease: SandboxLease, managerInput: SandboxManagerInput | undefined): string;
+/**
+ * Build the driver-facing ensure input.
+ *
+ * This is the ONLY place a `SandboxDriverEnsureInput` is constructed, which is
+ * what makes the egress guarantee structural rather than a promise kept by each
+ * call site: `net` is copied across only when `sandboxEgressDisposition` says
+ * the driver can enforce it. A driver declaring `egressControl: "none"` — every
+ * one of which throws on a restricted policy — cannot be reached by one through
+ * any path; `admit` has already refused the start, or the start allowed it to
+ * run uncontained.
+ */
+export declare function ensureHostInput(input: {
+    driver: SandboxDriver;
+    workspaceId: string;
+    lease: SandboxLease;
+    homeRegion: SandboxRegion;
+    managerInput?: SandboxManagerInput;
+    leaseEnv?: Record<string, string>;
+    appLabel: string;
+}): SandboxDriverEnsureInput;

package/dist/drivers/agent37-client.d.ts

@@ -0,0 +1,87 @@
+export type Agent37Fetch = (input: string, init?: RequestInit) => Promise<Response>;
+declare const INSTANCE_STATUSES: readonly ["provisioning", "running", "stopping", "stopped", "starting", "restarting", "updating", "sleeping", "waking", "failed", "deleting", "deleted"];
+export type Agent37InstanceStatus = (typeof INSTANCE_STATUSES)[number];
+export type Agent37Resources = {
+    cpu: number;
+    memory: number;
+    disk: number;
+};
+/** `"deny-all"` cuts DNS too; an `allow` entry is a domain (HTTPS on 443 only) or an IPv4 address or range. */
+export type Agent37Network = "allow-all" | "deny-all" | {
+    allow: string[];
+};
+export type Agent37Instance = {
+    id: string;
+    status: Agent37InstanceStatus;
+    /** The registry reference the instance's image was registered from. */
+    imageRef?: string;
+    resources: Agent37Resources;
+    metadata: Record<string, string>;
+    /** Each port's permanent URL that asks for no credential. */
+    publicPorts: {
+        port: number;
+        url: string;
+    }[];
+};
+export type Agent37ContainerHealth = {
+    logs: string;
+    running: boolean;
+    restartCount: number;
+};
+export declare class Agent37ApiError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    /** Agent37 answers these to the key itself; an instance of another workspace reads as `not_found`. */
+    readonly providerKeyRefused: boolean;
+    constructor(message: string, code: string, status?: number | undefined);
+}
+export type Agent37ClientOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    timeoutMs?: number;
+    fetchImpl?: Agent37Fetch;
+};
+export declare function createAgent37Client(options: Agent37ClientOptions): {
+    templateExists(name: string): Promise<boolean>;
+    /** A name another registration took first holds the same image and command, since the name is derived from both. */
+    registerTemplate(input: {
+        name: string;
+        imageRef: string;
+        entrypoint: string[];
+    }): Promise<void>;
+    create(input: {
+        template: string;
+        name: string;
+        metadata: Record<string, string>;
+        env: Record<string, string>;
+        network: Agent37Network;
+        resources: Agent37Resources;
+        publicPort: number;
+        mountPath: string;
+    }): Promise<Agent37Instance>;
+    get(id: string): Promise<Agent37Instance>;
+    list(): Promise<Agent37Instance[]>;
+    /** `env` reaches the container at its next start, restart, update or resize; `network` applies to a running one within seconds; `metadata` replaces what is stored. */
+    edit(id: string, input: {
+        env?: Record<string, string>;
+        network?: Agent37Network;
+        metadata?: Record<string, string>;
+    }): Promise<Agent37Instance>;
+    start: (id: string) => Promise<"deleted" | "deleting" | "failed" | "provisioning" | "restarting" | "running" | "sleeping" | "starting" | "stopped" | "stopping" | "updating" | "waking">;
+    stop: (id: string) => Promise<"deleted" | "deleting" | "failed" | "provisioning" | "restarting" | "running" | "sleeping" | "starting" | "stopped" | "stopping" | "updating" | "waking">;
+    restart: (id: string) => Promise<"deleted" | "deleting" | "failed" | "provisioning" | "restarting" | "running" | "sleeping" | "starting" | "stopped" | "stopping" | "updating" | "waking">;
+    /** Moves the instance onto `template`, keeping only its mount path; a stopped one stays stopped and boots that image at its next start. */
+    update: (id: string, template: string) => Promise<"deleted" | "deleting" | "failed" | "provisioning" | "restarting" | "running" | "sleeping" | "starting" | "stopped" | "stopping" | "updating" | "waking">;
+    /** Recreates the running container at the new size. Disk only grows. */
+    resize: (id: string, resources: Agent37Resources) => Promise<"deleted" | "deleting" | "failed" | "provisioning" | "restarting" | "running" | "sleeping" | "starting" | "stopped" | "stopping" | "updating" | "waking">;
+    publishPort(id: string, port: number): Promise<string>;
+    delete(id: string): Promise<void>;
+    /** Runs through `sh -c` as the image's user; a command that exits nonzero is an answer, not an error. */
+    exec(id: string, command: string): Promise<{
+        exitCode: number;
+        stdout: string;
+    }>;
+    /** Answers in any state; Agent37 starts a container that exited again, and `restartCount` counts each boot after the first. */
+    containerHealth(id: string, tail: number): Promise<Agent37ContainerHealth>;
+};
+export {};

package/dist/drivers/agent37.d.ts

@@ -0,0 +1,25 @@
+import { type SandboxDriver, type SandboxDriverEnsureInput } from "../contract";
+import { type WorkspaceRuntimeControlEnv } from "../runtime-env";
+import { type Agent37Fetch } from "./agent37-client";
+export type { Agent37Fetch };
+export type Agent37SandboxDriverOptions = {
+    apiKey: string;
+    baseUrl?: string;
+    image: string;
+    runtimePort?: number;
+    runtimeCommand?: string;
+    workspaceDir?: string;
+    nativeHarness?: string;
+    controlEnv?: WorkspaceRuntimeControlEnv;
+    env?: (input: SandboxDriverEnsureInput, host: {
+        id: string;
+    }) => Record<string, string> | Promise<Record<string, string>>;
+    provisionTimeoutMs?: number;
+    healthTimeoutMs?: number;
+    healthIntervalMs?: number;
+    /** How long a boot waits between two reads of its container's restart count. */
+    containerCheckMs?: number;
+    operationTimeoutMs?: number;
+    fetchImpl?: Agent37Fetch;
+};
+export declare function createAgent37SandboxDriver(options: Agent37SandboxDriverOptions): SandboxDriver;