@hotcell/daemon 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,241 @@
+export interface Config {
+    host: string;
+    port: number;
+    /**
+     * Default OCI image for new sandboxes. Defaults to a small Debian-based
+     * Python image (ships /bin/bash + python3) so the vertical slice works with
+     * zero local image builds. Build images/base and set SBX_IMAGE=sbx/base:latest
+     * for the richer toolset (Node 20, git, ripgrep, …).
+     */
+    defaultImage: string;
+    /**
+     * Runtime driver to use: `container` (Docker, the only built impl),
+     * `firecracker` (Linux microVM, Phase 3), or `applevz` (macOS microVM, Phase 3).
+     * Selects the isolation tier; the daemon/SDK/CLI are unchanged across drivers.
+     */
+    driver: string;
+    /** Default per-sandbox memory cap in MiB for new sandboxes (`0` = unlimited). */
+    defaultMemoryMb: number;
+    /** Default per-sandbox CPU cap in fractional cores (`0` = unlimited). */
+    defaultCpus: number;
+    /** Default per-sandbox process/thread cap for new sandboxes (`0` = unlimited). */
+    defaultPidsLimit: number;
+    /**
+     * Admission control: `enforce` rejects `create` when the host's memory budget
+     * is exhausted (prevents over-subscription / OOM when launching many
+     * sandboxes); `off` only reports capacity. Default `enforce`.
+     */
+    admission: "enforce" | "off";
+    /** Host memory budget in MiB for admission (`0` = auto-detect from the runtime). */
+    hostMemoryMb: number;
+    /** Host CPU budget for the capacity view (`0` = auto-detect from the runtime). */
+    hostCpus: number;
+    /** Memory over-commit factor applied to the host budget (e.g. `1.5` to oversubscribe). */
+    overcommit: number;
+    /**
+     * Admission **floor** (MiB) charged for an uncapped sandbox that's just started
+     * or not yet sampled. Once the metrics sampler sees it, admission uses its
+     * measured RSS instead (usage-based). Capped sandboxes use their cap.
+     */
+    defaultReservationMb: number;
+    /** Bind host for the preview-URL reverse proxy. */
+    proxyHost: string;
+    /** Port for the preview-URL reverse proxy (separate from the REST API). */
+    proxyPort: number;
+    /**
+     * Bind host for the egress credential proxy (LLM gateway). Defaults to
+     * loopback (single-tenant safe). On **native Linux** dockerd, sandboxes reach
+     * the daemon via the bridge gateway (`host.docker.internal` → ~172.17.0.1), so
+     * a loopback-only bind is unreachable from sandboxes — set `HOTCELL_EGRESS_HOST`
+     * to `0.0.0.0` (or the bridge IP) there, relying on the per-sandbox egress
+     * token + host firewall. Docker Desktop (macOS) reaches loopback as-is.
+     */
+    egressHost: string;
+    /** Port for the egress credential proxy. `0` disables it. */
+    egressPort: number;
+    /**
+     * Enforce default-deny egress: put sandboxes on a dedicated bridge network and
+     * (Linux only) install host `DOCKER-USER` iptables rules so the ONLY reachable
+     * destinations are the egress gateway + the pinned DNS resolver — everything else
+     * is dropped. Off by default (the gateway is then the "safe path available", not
+     * the "only path"). `HOTCELL_EGRESS_ENFORCE`. Advisory-only on macOS Docker Desktop.
+     */
+    egressEnforce: boolean;
+    /** Docker network name sandboxes join when egress is enforced. `HOTCELL_EGRESS_NETWORK`. */
+    egressNetwork: string;
+    /**
+     * IPv4 subnet (CIDR) for the egress-enforced bridge network. The host firewall
+     * scopes its allow/deny rules to this subnet, and the bridge gateway (`.1`) is the
+     * sandbox's route to the egress gateway. `/24` assumed. `HOTCELL_EGRESS_SUBNET`.
+     */
+    egressSubnet: string;
+    /**
+     * DNS resolver IP pinned into sandboxes under egress enforcement (so DNS can't be
+     * used as an exfil channel and DoH is the only blocked path). Empty = Docker's
+     * embedded resolver. `HOTCELL_EGRESS_DNS`.
+     */
+    egressDnsResolver: string;
+    /**
+     * Path to a JSON `{ allow, deny }` allowlist that fully REPLACES the built-in
+     * default (forward-proxy host allowlist). `HOTCELL_ALLOWLIST_FILE`. Empty = defaults.
+     */
+    allowlistFile: string;
+    /** Extra hosts appended to the allowlist (`HOTCELL_ALLOWLIST_EXTRA`, comma-separated). */
+    allowlistExtra: string[];
+    /**
+     * Include the `source_control` allowlist tier (github/gitlab/bitbucket). On by
+     * default so `git clone` works; set `HOTCELL_ALLOW_SOURCE_CONTROL=false` for
+     * high-security workloads (a writable git host is also an exfil channel).
+     */
+    allowSourceControl: boolean;
+    /**
+     * Default per-sandbox LLM spend ceiling in USD — the gateway returns 402 once a
+     * sandbox's cumulative provider cost reaches it, across all its tokens. Per-create
+     * `egressSpendCapUsd` overrides. `0` = unlimited. `HOTCELL_EGRESS_SPEND_CAP`.
+     */
+    egressSpendCapUsd: number;
+    /**
+     * Hostname advertised in egress base URLs returned to clients. Sandboxes reach
+     * the daemon host through this name, so on Docker Desktop it defaults to
+     * `host.docker.internal`. Set to a LAN IP/DNS name for remote sandboxes.
+     */
+    egressAdvertiseHost: string;
+    /**
+     * Provider API keys, held on the daemon host and injected into outbound calls
+     * so they never live inside a sandbox. Keyed by lower-case provider name
+     * (`openai`, `anthropic`, `openrouter`). A provider's gateway route exists only
+     * when its key is present here. Sourced from `HOTCELL_PROVIDER_KEY_<NAME>` env vars.
+     */
+    providerKeys: Record<string, string>;
+    /**
+     * Operator-defined / override provider shapes, keyed by lower-case provider
+     * name. Lets an operator add a provider the daemon doesn't ship (or repoint a
+     * built-in — e.g. route `openai` through a Cloudflare AI Gateway prefix) without
+     * a code change. Sourced from `HOTCELL_PROVIDER_<NAME>_BASEURL` / `_AUTHHEADER` /
+     * `_FORMAT`. A route still requires a key (`HOTCELL_PROVIDER_KEY_<NAME>`).
+     */
+    providerConfigs: Record<string, ProviderConfig>;
+    /** Host directory where sandbox backup tarballs + metadata are stored. */
+    backupDir: string;
+    /**
+     * Path to the embedded SQLite database holding durable control-plane state
+     * (sandbox/process/session/context/exposed-port records). Survives daemon
+     * restarts. Set to `:memory:` for an ephemeral, in-process store.
+     */
+    dbPath: string;
+    /**
+     * Default idle timeout (ms) applied to new sandboxes that don't specify their
+     * own `sleepAfter`. The reaper auto-pauses a sandbox after this long without
+     * activity. `0` (the default) disables auto-pause.
+     */
+    defaultSleepAfterMs: number;
+    /** How often (ms) the idle reaper scans for sandboxes to auto-pause. */
+    reapIntervalMs: number;
+    /** How often (ms) the metrics sampler integrates per-sandbox usage. `0` disables it. */
+    metricsIntervalMs: number;
+    /** Cost-meter rate: currency units per vCPU-hour. */
+    costCpuPerHour: number;
+    /** Cost-meter rate: currency units per GB-hour of memory. */
+    costMemGbPerHour: number;
+    /** Cost-meter rate: currency units per GB of preview-proxy egress. */
+    costEgressPerGb: number;
+    /**
+     * Path to a JSON model→price override file (`HOTCELL_MODEL_PRICES`), overlaid on the
+     * built-in table. Used to compute an LLM call's USD cost when the provider does
+     * not report one. Empty = built-in defaults only.
+     */
+    modelPricesPath: string;
+    /**
+     * Path to the signed `sbx-vz` Swift helper for the Apple VZ driver (`HOTCELL_DRIVER=applevz`).
+     * Built by `npm run build:vz`. Defaults to its in-repo build output; set
+     * `HOTCELL_VZ_HELPER_PATH` to a bundled/installed location. `HOTCELL_DRIVER=container` ignores it.
+     */
+    vzHelperPath: string;
+    /** Guest kernel image for the Apple VZ driver (`HOTCELL_VZ_KERNEL`). Uncompressed arm64 Image. */
+    vzKernel: string;
+    /** Base rootfs image for the Apple VZ driver (`HOTCELL_VZ_ROOTFS`). */
+    vzRootfs: string;
+    /** Per-sandbox VM state dir (disks, sockets) for the Apple VZ driver (`HOTCELL_VZ_STATE_DIR`). */
+    vzStateDir: string;
+    /** Default workspace disk size in GiB for a new VZ sandbox (`HOTCELL_VZ_DISK_GB`). */
+    vzDiskGb: number;
+    /**
+     * Cache dir for OCI→ext4 converted rootfs images + the blank workspace template
+     * (`HOTCELL_VZ_IMAGE_CACHE`). Keyed by image name; populated on demand from
+     * `HOTCELL_IMAGE`. Kept separate from the per-sandbox state dir so it survives.
+     */
+    vzImageCacheDir: string;
+    /**
+     * Warm-pool size for the Apple VZ driver (`HOTCELL_VZ_WARM_POOL`, default 0 = off):
+     * keep this many base-image microVMs pre-booted so a `create` of the base image
+     * is an instant adopt instead of a ~2s cold boot. The pool refills in the
+     * background as guests are claimed.
+     */
+    vzWarmPool: number;
+    /** `firecracker` binary path for the Firecracker driver (`HOTCELL_FC_BIN`). */
+    fcBin: string;
+    /** Guest kernel (uncompressed vmlinux) for the Firecracker driver (`HOTCELL_FC_KERNEL`). */
+    fcKernel: string;
+    /** Prebuilt base rootfs for the Firecracker driver (`HOTCELL_FC_ROOTFS`). */
+    fcRootfs: string;
+    /** Per-sandbox VM state dir for the Firecracker driver (`HOTCELL_FC_STATE_DIR`). */
+    fcStateDir: string;
+    /** Default workspace disk size in GiB for a new Firecracker sandbox (`HOTCELL_FC_DISK_GB`). */
+    fcDiskGb: number;
+    /**
+     * Warm-pool size for the Firecracker driver (`HOTCELL_FC_WARM_POOL`, default 0 = off):
+     * keep N pre-booted spare microVMs of the default image so a plain create
+     * adopts one instantly instead of cold-booting.
+     */
+    fcWarmPool: number;
+    /** Converted OCI→ext4 rootfs cache for the Firecracker driver (`HOTCELL_FC_IMAGE_CACHE`). */
+    fcImageCacheDir: string;
+    /** Minimum level emitted by the structured logger. */
+    logLevel: LogLevel;
+    /** Log encoding: `json` (one JSON object per line) or `pretty` (human). */
+    logFormat: LogFormat;
+    /**
+     * API key required on every REST call (except `/healthz` and the dashboard
+     * HTML). Empty string (the default) disables auth — loopback, single-tenant.
+     */
+    apiKey: string;
+    /**
+     * OTLP/HTTP traces endpoint (e.g. `http://localhost:4318`). When set, spans are
+     * batch-exported to `<endpoint>/v1/traces`. Empty disables export; recent spans
+     * are always kept in-memory for `GET /traces` regardless.
+     */
+    otlpEndpoint: string;
+    /** How many of the most recent metric samples per sandbox to retain in memory. */
+    metricsHistory: number;
+    /** How many of the most recent finished spans to retain in memory for `/traces`. */
+    traceRing: number;
+    /**
+     * Maximum accepted request body size in bytes (REST + egress gateway). Caps
+     * memory use from a single request. Must stay large enough for base64-encoded
+     * file writes. `HOTCELL_MAX_BODY_BYTES`, default 32 MiB.
+     */
+    maxBodyBytes: number;
+    /**
+     * Extra Host header values accepted by the API server, beyond the loopback
+     * names and `host`. The Host allowlist is a DNS-rebinding / localhost-CSRF
+     * guard. `HOTCELL_ALLOWED_HOSTS` (comma-separated). Empty by default.
+     */
+    allowedHosts: string[];
+}
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export type LogFormat = "json" | "pretty";
+/** Operator-supplied provider shape (base URL + auth header + key-format template). */
+export interface ProviderConfig {
+    baseUrl?: string;
+    /** Header the provider authenticates with (e.g. `authorization`, `x-api-key`). */
+    authHeader?: string;
+    /** Auth-header value template; `{key}` is replaced with the real key (e.g. `Bearer {key}`). */
+    formatTemplate?: string;
+}
+export declare function loadConfig(): Config;
+/**
+ * Build the preview URL for an exposed port. Uses a `*.localhost` subdomain,
+ * which browsers resolve to 127.0.0.1 with zero DNS/hosts config. Sandbox ids
+ * are dash-free hex, so `<id>-<port>` is an unambiguous label.
+ */
+export declare function previewUrl(config: Config, sandboxId: string, port: number): string;

package/dist/config.js

@@ -0,0 +1,152 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/**
+ * Read a daemon env var with legacy fallback: `HOTCELL_<name>` wins, then the
+ * pre-rename `HOTCELL_<name>` — so deployments configured before the hotcell
+ * rename keep working unchanged.
+ */
+function env(name) {
+    return process.env[`HOTCELL_${name}`] ?? process.env[`HOTCELL_${name}`];
+}
+/**
+ * Root for daemon state (db, backups, VM state, image caches): `~/.hotcell`,
+ * except when a pre-rename `~/.sbx` already exists and `~/.hotcell` doesn't —
+ * then the legacy root keeps being used so existing installs keep their data.
+ */
+function stateRoot() {
+    const modern = join(homedir(), ".hotcell");
+    const legacy = join(homedir(), ".sbx");
+    if (!existsSync(modern) && existsSync(legacy))
+        return legacy;
+    return modern;
+}
+export function loadConfig() {
+    return {
+        host: env("HOST") ?? "127.0.0.1",
+        port: Number(env("PORT") ?? 4750),
+        defaultImage: env("IMAGE") ?? "python:3.11-slim-bookworm",
+        driver: env("DRIVER") ?? "container",
+        defaultMemoryMb: Number(env("DEFAULT_MEMORY_MB") ?? 0),
+        defaultCpus: Number(env("DEFAULT_CPUS") ?? 0),
+        defaultPidsLimit: Number(env("DEFAULT_PIDS") ?? 0),
+        admission: env("ADMISSION") === "off" ? "off" : "enforce",
+        hostMemoryMb: Number(env("HOST_MEMORY_MB") ?? 0),
+        hostCpus: Number(env("HOST_CPUS") ?? 0),
+        overcommit: Number(env("OVERCOMMIT") ?? 1),
+        defaultReservationMb: Number(env("DEFAULT_RESERVATION_MB") ?? 256),
+        proxyHost: env("PROXY_HOST") ?? "127.0.0.1",
+        proxyPort: Number(env("PROXY_PORT") ?? 4751),
+        egressHost: env("EGRESS_HOST") ?? "127.0.0.1",
+        egressPort: Number(env("EGRESS_PORT") ?? 4752),
+        egressAdvertiseHost: env("EGRESS_ADVERTISE_HOST") ?? "host.docker.internal",
+        egressEnforce: env("EGRESS_ENFORCE") === "true",
+        egressNetwork: env("EGRESS_NETWORK") ?? "hotcell-egress",
+        egressSubnet: env("EGRESS_SUBNET") ?? "10.200.0.0/24",
+        egressDnsResolver: env("EGRESS_DNS") ?? "",
+        allowlistFile: env("ALLOWLIST_FILE") ?? "",
+        allowlistExtra: (env("ALLOWLIST_EXTRA") ?? "")
+            .split(",")
+            .map((h) => h.trim())
+            .filter(Boolean),
+        allowSourceControl: env("ALLOW_SOURCE_CONTROL") !== "false",
+        egressSpendCapUsd: Number(env("EGRESS_SPEND_CAP") ?? 0),
+        providerKeys: loadProviderKeys(),
+        providerConfigs: loadProviderConfigs(),
+        backupDir: env("BACKUP_DIR") ?? join(stateRoot(), "backups"),
+        dbPath: env("DB") ?? join(stateRoot(), "state.db"),
+        defaultSleepAfterMs: Number(env("SLEEP_AFTER_MS") ?? 0),
+        reapIntervalMs: Number(env("REAP_INTERVAL_MS") ?? 15000),
+        metricsIntervalMs: Number(env("METRICS_INTERVAL_MS") ?? 10000),
+        costCpuPerHour: Number(env("COST_CPU_PER_HOUR") ?? 0.05),
+        costMemGbPerHour: Number(env("COST_MEM_GB_PER_HOUR") ?? 0.005),
+        costEgressPerGb: Number(env("COST_EGRESS_PER_GB") ?? 0.01),
+        modelPricesPath: env("MODEL_PRICES") ?? "",
+        vzHelperPath: env("VZ_HELPER_PATH") ?? "helpers/hotcell-vz/dist/hotcell-vz",
+        vzKernel: env("VZ_KERNEL") ?? "helpers/hotcell-vz/guest/vmlinux-vz",
+        vzRootfs: env("VZ_ROOTFS") ?? "helpers/hotcell-vz/guest/rootfs.img",
+        vzStateDir: env("VZ_STATE_DIR") ?? join(stateRoot(), "vz"),
+        vzDiskGb: Number(env("VZ_DISK_GB") ?? 4),
+        vzImageCacheDir: env("VZ_IMAGE_CACHE") ?? join(stateRoot(), "vz", "images"),
+        vzWarmPool: Number(env("VZ_WARM_POOL") ?? 0),
+        fcBin: env("FC_BIN") ?? "firecracker",
+        fcKernel: env("FC_KERNEL") ?? "helpers/hotcell-vz/guest/vmlinux-fc",
+        fcRootfs: env("FC_ROOTFS") ?? "helpers/hotcell-vz/guest/rootfs.img",
+        fcStateDir: env("FC_STATE_DIR") ?? join(stateRoot(), "fc"),
+        fcDiskGb: Number(env("FC_DISK_GB") ?? 8),
+        fcWarmPool: Number(env("FC_WARM_POOL") ?? 0),
+        fcImageCacheDir: env("FC_IMAGE_CACHE") ?? join(stateRoot(), "fc", "images"),
+        logLevel: parseLogLevel(env("LOG_LEVEL")),
+        logFormat: env("LOG_FORMAT") === "json" ? "json" : "pretty",
+        apiKey: env("API_KEY") ?? "",
+        otlpEndpoint: (env("OTLP_ENDPOINT") ?? "").replace(/\/$/, ""),
+        metricsHistory: Number(env("METRICS_HISTORY") ?? 60),
+        traceRing: Number(env("TRACE_RING") ?? 200),
+        maxBodyBytes: Number(env("MAX_BODY_BYTES") ?? 32 * 1024 * 1024),
+        allowedHosts: (env("ALLOWED_HOSTS") ?? "")
+            .split(",")
+            .map((h) => h.trim())
+            .filter(Boolean),
+    };
+}
+/** Collect provider keys from `HOTCELL_PROVIDER_KEY_<NAME>` env vars (name
+ *  lowercased); legacy `SBX_PROVIDER_KEY_<NAME>` still read, HOTCELL_ wins. */
+function loadProviderKeys() {
+    const keys = {};
+    for (const prefix of ["SBX_PROVIDER_KEY_", "HOTCELL_PROVIDER_KEY_"]) {
+        // legacy first so HOTCELL_ overwrites on conflict
+        for (const [name, value] of Object.entries(process.env)) {
+            if (name.startsWith(prefix) && value) {
+                keys[name.slice(prefix.length).toLowerCase()] = value;
+            }
+        }
+    }
+    return keys;
+}
+/**
+ * Collect operator-defined provider shapes from `HOTCELL_PROVIDER_<NAME>_<FIELD>` env
+ * vars (FIELD ∈ BASEURL/AUTHHEADER/FORMAT), skipping the `HOTCELL_PROVIDER_KEY_*`
+ * namespace. The provider name is lower-cased; e.g.
+ * `HOTCELL_PROVIDER_CFOPENAI_BASEURL=https://gateway.ai.cloudflare.com/v1/<acct>/<gw>/openai`
+ * defines a `cfopenai` route (pair with `HOTCELL_PROVIDER_KEY_CFOPENAI`).
+ */
+function loadProviderConfigs() {
+    const out = {};
+    // Legacy prefix scanned first so HOTCELL_ overwrites on conflict.
+    for (const prefix of ["SBX_PROVIDER_", "HOTCELL_PROVIDER_"]) {
+        for (const [name, value] of Object.entries(process.env)) {
+            if (!name.startsWith(prefix) || !value)
+                continue;
+            if (name.startsWith("SBX_PROVIDER_KEY_") || name.startsWith("HOTCELL_PROVIDER_KEY_"))
+                continue;
+            const rest = name.slice(prefix.length); // <NAME>_<FIELD>
+            const us = rest.lastIndexOf("_");
+            if (us <= 0)
+                continue;
+            const provName = rest.slice(0, us).toLowerCase();
+            const field = rest.slice(us + 1).toUpperCase();
+            const cfg = (out[provName] ??= {});
+            if (field === "BASEURL")
+                cfg.baseUrl = value;
+            else if (field === "AUTHHEADER")
+                cfg.authHeader = value.toLowerCase();
+            else if (field === "FORMAT")
+                cfg.formatTemplate = value;
+        }
+    }
+    return out;
+}
+function parseLogLevel(value) {
+    return value === "debug" || value === "info" || value === "warn" || value === "error"
+        ? value
+        : "info";
+}
+/**
+ * Build the preview URL for an exposed port. Uses a `*.localhost` subdomain,
+ * which browsers resolve to 127.0.0.1 with zero DNS/hosts config. Sandbox ids
+ * are dash-free hex, so `<id>-<port>` is an unambiguous label.
+ */
+export function previewUrl(config, sandboxId, port) {
+    return `http://${sandboxId}-${port}.localhost:${config.proxyPort}/`;
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/cost.d.ts

@@ -0,0 +1,9 @@
+import type { Config } from "./config.js";
+import type { CostBreakdown, SandboxUsage } from "./types.js";
+/**
+ * Translate cumulative usage into a cost breakdown using the configured rates.
+ * CPU is exact (integrated vCPU-seconds), memory is integrated GB-seconds, and
+ * egress is the preview-proxy bytes the sandbox has sent out. (Full internet
+ * egress metering arrives with the Phase 3 egress credential proxy.)
+ */
+export declare function computeCost(usage: SandboxUsage, config: Config): CostBreakdown;

package/dist/cost.js

@@ -0,0 +1,19 @@
+const BYTES_PER_GB = 1e9;
+const SECONDS_PER_HOUR = 3600;
+/**
+ * Translate cumulative usage into a cost breakdown using the configured rates.
+ * CPU is exact (integrated vCPU-seconds), memory is integrated GB-seconds, and
+ * egress is the preview-proxy bytes the sandbox has sent out. (Full internet
+ * egress metering arrives with the Phase 3 egress credential proxy.)
+ */
+export function computeCost(usage, config) {
+    const cpu = (usage.cpuSeconds / SECONDS_PER_HOUR) * config.costCpuPerHour;
+    const memGbSeconds = usage.memByteSeconds / BYTES_PER_GB;
+    const mem = (memGbSeconds / SECONDS_PER_HOUR) * config.costMemGbPerHour;
+    const egress = (usage.egressBytes / BYTES_PER_GB) * config.costEgressPerGb;
+    // LLM cost is the provider's own reported figure (e.g. OpenRouter usage.cost) —
+    // the source of truth, not a rate we apply.
+    const provider = usage.providerCost ?? 0;
+    return { cpu, mem, egress, provider, total: cpu + mem + egress + provider };
+}
+//# sourceMappingURL=cost.js.map

package/dist/cost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cost.js","sourceRoot":"","sources":["../src/cost.ts"],"names":[],"mappings":"AAGA,MAAM,YAAY,GAAG,GAAG,CAAC;AACzB,MAAM,gBAAgB,GAAG,IAAI,CAAC;AAE9B;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB,EAAE,MAAc;IAC7D,MAAM,GAAG,GAAG,CAAC,KAAK,CAAC,UAAU,GAAG,gBAAgB,CAAC,GAAG,MAAM,CAAC,cAAc,CAAC;IAC1E,MAAM,YAAY,GAAG,KAAK,CAAC,cAAc,GAAG,YAAY,CAAC;IACzD,MAAM,GAAG,GAAG,CAAC,YAAY,GAAG,gBAAgB,CAAC,GAAG,MAAM,CAAC,gBAAgB,CAAC;IACxE,MAAM,MAAM,GAAG,CAAC,KAAK,CAAC,WAAW,GAAG,YAAY,CAAC,GAAG,MAAM,CAAC,eAAe,CAAC;IAC3E,gFAAgF;IAChF,4CAA4C;IAC5C,MAAM,QAAQ,GAAG,KAAK,CAAC,YAAY,IAAI,CAAC,CAAC;IACzC,OAAO,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,MAAM,GAAG,QAAQ,EAAE,CAAC;AAC9E,CAAC"}

package/dist/density-bench.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/density-bench.js

@@ -0,0 +1,97 @@
+/**
+ * Firecracker density benchmark (plan §Verification 4): launch N small microVMs
+ * on one host, prove they're all live and functional, and measure what density
+ * actually costs — boot latency distribution, host memory per VM, teardown.
+ *
+ * Run on a KVM host: SBX_DENSITY_N=40 npm run bench:density
+ * (image conversion must be cached — run smoke:fc once first).
+ */
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { FirecrackerDriver } from "./driver/firecracker.js";
+const N = Number(process.env.SBX_DENSITY_N ?? 40);
+const CONCURRENCY = Number(process.env.SBX_DENSITY_CONCURRENCY ?? 4);
+const MEM_MB = Number(process.env.SBX_DENSITY_MEM_MB ?? 256);
+function hostAvailableMb() {
+    const m = /MemAvailable:\s+(\d+)\s+kB/.exec(readFileSync("/proc/meminfo", "utf8"));
+    return m ? Math.round(Number(m[1]) / 1024) : 0;
+}
+function pct(sorted, p) {
+    return sorted[Math.min(sorted.length - 1, Math.floor((p / 100) * sorted.length))] ?? 0;
+}
+async function main() {
+    const stateDir = mkdtempSync(join(tmpdir(), "hotcell-density-"));
+    const image = process.env.SBX_FC_SMOKE_IMAGE ?? "alpine:3.20";
+    const driver = new FirecrackerDriver({
+        fcBin: process.env.SBX_FC_BIN ?? "firecracker",
+        kernel: process.env.SBX_FC_KERNEL ?? "helpers/hotcell-vz/guest/vmlinux-fc",
+        rootfs: "helpers/hotcell-vz/guest/rootfs.img",
+        stateDir,
+        diskGb: 1,
+        imageCacheDir: process.env.SBX_FC_IMAGE_CACHE ?? join(homedir(), ".sbx", "fc", "images"),
+    });
+    const ids = Array.from({ length: N }, (_, i) => `dens${String(i).padStart(3, "0")}`);
+    const bootMs = [];
+    const failures = [];
+    const memBefore = hostAvailableMb();
+    const t0 = Date.now();
+    console.error(`[density] booting ${N} microVMs (${MEM_MB}MB cap each, concurrency ${CONCURRENCY})…`);
+    let next = 0;
+    const worker = async () => {
+        while (next < ids.length) {
+            const id = ids[next++];
+            const t = Date.now();
+            try {
+                await driver.create({ id, image, env: {}, persist: true, limits: { memoryMb: MEM_MB, cpus: 1 } });
+                bootMs.push(Date.now() - t);
+            }
+            catch (err) {
+                failures.push(`${id}: ${err.message.slice(0, 120)}`);
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: CONCURRENCY }, worker));
+    const bootWallS = ((Date.now() - t0) / 1000).toFixed(1);
+    const memAfter = hostAvailableMb();
+    // Every VM must be live and functional, not just booted.
+    console.error("[density] exec in every VM…");
+    let functional = 0;
+    for (const id of ids) {
+        if (failures.some((f) => f.startsWith(id)))
+            continue;
+        try {
+            let out = "";
+            const code = await driver.exec(id, "echo ok-$HOSTNAME", {}, (e) => {
+                if (e.type === "stdout")
+                    out += e.data;
+            });
+            if (code === 0 && /ok-/.test(out))
+                functional++;
+        }
+        catch {
+            failures.push(`${id}: exec failed post-boot`);
+        }
+    }
+    const booted = bootMs.length;
+    const perVmMb = booted > 0 ? Math.round((memBefore - memAfter) / booted) : 0;
+    bootMs.sort((a, b) => a - b);
+    console.log(`\ndensity-bench: ${booted}/${N} booted, ${functional} functional, ${failures.length} failures`);
+    console.log(`  boot latency: p50 ${pct(bootMs, 50)}ms / p95 ${pct(bootMs, 95)}ms / max ${pct(bootMs, 100)}ms`);
+    console.log(`  wall time to boot all: ${bootWallS}s`);
+    console.log(`  host memory: ${memBefore}MB → ${memAfter}MB available (~${perVmMb}MB per live VM)`);
+    for (const f of failures.slice(0, 5))
+        console.log(`  ✗ ${f}`);
+    console.error("[density] tearing down…");
+    const tDown = Date.now();
+    for (const id of ids)
+        await driver.destroy(id).catch(() => { });
+    console.log(`  teardown: ${((Date.now() - tDown) / 1000).toFixed(1)}s; host available now ${hostAvailableMb()}MB`);
+    rmSync(stateDir, { recursive: true, force: true });
+    return failures.length === 0 && functional === booted && booted === N ? 0 : 1;
+}
+main().then((code) => process.exit(code), (err) => {
+    console.error("density-bench FAILED:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=density-bench.js.map

package/dist/density-bench.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"density-bench.js","sourceRoot":"","sources":["../src/density-bench.ts"],"names":[],"mappings":"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"}

package/dist/driver/agent-driver.d.ts

@@ -0,0 +1,67 @@
+import type { AgentConn } from "./agent.js";
+import { UnsupportedDriver } from "./unsupported.js";
+import type { ProcessLiveness, SandboxStats, StartProcessResult, TcpBridge, TerminalOptions, TerminalSession } from "./types.js";
+import type { ExecEvent, ExecOptions, FileChangeEvent, FileInfo, ListFilesOptions, MkdirOptions, ReadFileOptions, StartProcessOptions, WaitForPortOptions, WatchOptions, WriteFileOptions } from "../types.js";
+/**
+ * Shared base for microVM drivers whose in-guest work is served by the `sbx-agent`
+ * over the A.4 wire protocol (`AgentConn`). Every agent-served `Driver` method —
+ * exec, files, watch, processes, preview bridge, terminal, stats, backup/restore —
+ * is implemented here **once**, in terms of a single abstract `openConn(id)` that
+ * each concrete driver provides for its transport (Apple VZ relays a unix socket
+ * to the guest vsock; Firecracker connects to a vsock UDS with a CONNECT
+ * handshake). Concrete drivers only implement lifecycle (`create`/`stop`/`start`/
+ * `destroy`), `openConn`, and the host probes (`ping`/`hostInfo`) — the whole
+ * point of the abstraction is that the surface above the driver is identical.
+ */
+export declare abstract class AgentDriver extends UnsupportedDriver {
+    /**
+     * Open a fresh agent connection to a running sandbox, resolved once the agent's
+     * Hello arrives. Throws `<name>: sandbox <id> is not running` if it isn't live.
+     * The connection is single-use unless the caller keeps it (long-lived streams).
+     */
+    protected abstract openConn(id: string): Promise<AgentConn>;
+    /** Open a connection, run `fn`, always close it. For one-shot request/response ops. */
+    protected withConn<T>(id: string, fn: (c: AgentConn) => Promise<T>): Promise<T>;
+    exec(id: string, command: string, opts: ExecOptions, onEvent: (e: ExecEvent) => void): Promise<number>;
+    writeFile(id: string, opts: WriteFileOptions): Promise<void>;
+    readFile(id: string, opts: ReadFileOptions): Promise<string>;
+    mkdir(id: string, opts: MkdirOptions): Promise<void>;
+    listFiles(id: string, opts: ListFilesOptions): Promise<FileInfo[]>;
+    waitForPort(id: string, port: number, opts: WaitForPortOptions): Promise<boolean>;
+    /** Watch a path recursively for changes over the agent (poll-based mtime diff),
+     *  streaming events until `opts.signal` aborts. Holds a connection for its life. */
+    watchFiles(id: string, path: string, opts: WatchOptions & {
+        signal: AbortSignal;
+    }, onEvent: (e: FileChangeEvent) => void): Promise<void>;
+    startProcess(id: string, procId: string, command: string, opts: StartProcessOptions): Promise<StartProcessResult>;
+    listProcesses(id: string, procs: Array<{
+        procId: string;
+        pid: number;
+    }>): Promise<ProcessLiveness[]>;
+    killProcess(id: string, pid: number, signal?: string): Promise<void>;
+    streamProcessLogs(id: string, logPath: string, opts: {
+        follow: boolean;
+        signal: AbortSignal;
+    }, onData: (chunk: string) => void): Promise<void>;
+    /** Raw byte bridge to `host:port` inside the guest — backs the preview-URL proxy.
+     *  Each bridge holds its own connection (the duplex is long-lived). */
+    openTcpBridge(id: string, port: number, host: string): Promise<TcpBridge>;
+    /** Interactive PTY shell — backs the dashboard/CLI terminal. */
+    openTerminal(id: string, opts: TerminalOptions): Promise<TerminalSession>;
+    /** Live resource snapshot from the guest's /proc + cgroup files (via the agent).
+     *  cpuPercent is left 0 by the guest — the metrics sampler derives it from the
+     *  delta of successive cpuTotalUsageNs samples, exactly as for the container driver. */
+    stats(id: string): Promise<SandboxStats>;
+    /** Tar the guest's /workspace to `tarPath` on the host (over the agent). */
+    createBackup(id: string, tarPath: string): Promise<{
+        bytes: number;
+    }>;
+    /** Replace the guest's /workspace with the tar at `tarPath` (cleared first). */
+    restoreBackup(id: string, tarPath: string): Promise<void>;
+    /** Run a command and collect its full stdout/stderr/exit (for the process shims). */
+    protected execCapture(id: string, command: string, opts?: ExecOptions): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+}