@multiplayer-app/sandbox 0.0.37 → 2.0.0-wip-yjs-state-changes.0

package/README.md

@@ -0,0 +1,121 @@
+# @multiplayer-app/sandbox
+
+Micro-VM worker library: runs micro-VMs and connects to the Multiplayer sandbox control
+plane. It auto-detects which micro-VM engines the host can run and advertises them to
+sandbox; sandbox schedules VMs onto it and proxies traffic through a single outbound
+WebSocket, so the worker needs **no inbound ports**.
+
+Supported engines (auto-detected): `qemu`, `firecracker`, `docker`, `docker-sandbox`,
+`lambda-microvm`, `fargate`, `remote`, and `mock`.
+
+`vm-gateway` can import this package directly and run the worker in-process (see
+`services/vm-gateway/src/index.ts`). The published package also installs a standalone
+`sandbox` executable. Engine configuration is env-driven and auto-detected —
+`WORKER_ID`, `WORKER_TOKEN`, `SANDBOX_URL`, `MAX_VMS`, `WORKER_REGION`, plus per-engine
+vars like `QEMU_IMAGES_DIR`, `DOCKER_STACK_IMAGES`, `MICROVM_IMAGE_ARN`,
+`FARGATE_CLUSTER`, `AGENT_URL` — see `src/config.ts` for the full list.
+`WORKER_TOKEN` is required. `WORKER_ID` is optional and defaults to the machine
+hostname; set it explicitly when multiple workers could report the same hostname.
+`SANDBOX_URL` is optional and defaults to
+`https://api.sandbox.filingramp.com`; set it explicitly for local or self-hosted
+control planes.
+
+## Start a worker
+
+Install the package globally and start the worker with its authentication token:
+
+```sh
+npm install --global @multiplayer-app/sandbox
+WORKER_TOKEN=<token> sandbox start
+```
+
+The worker ID defaults to the hostname and the control-plane URL defaults to
+`https://api.sandbox.filingramp.com`. Both can be overridden with environment
+variables or flags:
+
+```sh
+sandbox start --token <token> --worker-id worker-eu-01 \
+  --sandbox-url http://localhost:3011 --max-vms 5
+```
+
+For the `qemu` engine, the host needs QEMU (`qemu-system-*`) installed; for
+`firecracker`, a Linux host with `/dev/kvm`; for `docker`, just a running Docker
+daemon (Docker Desktop/OrbStack) plus local images from
+`scripts/setup-docker-images.sh` — no kernel images or virtualization support
+needed, making it the lowest-friction engine for local dev. One VM = one
+container; unlike the other local engines it also supports `exec`/`writeFiles`
+directly (`docker exec` / `docker cp`), and `pause`/`resume`/`stop`/`restore` map
+onto real `docker pause`/`unpause`/`stop`/`start`.
+
+`docker-sandbox` runs the same per-stack images through
+[Docker Sandboxes](https://www.docker.com/products/docker-sandboxes/) (the `sbx`
+CLI) instead of plain `docker run` — one VM = one `sbx` sandbox, each in its own
+microVM (stronger isolation than the `docker` engine, no HVF/KVM setup needed
+like QEMU/Firecracker). Requires `sbx` installed and signed in (`sbx login`) and
+a global network policy initialized once (`sbx policy init balanced`); sandboxes
+have a 1 GiB memory floor and there's no `pause`/`unpause` primitive (aliased to
+`stop`/`restore`). Images are bridged on demand from the same `docker` images
+above via `docker save` + `sbx template load` — no separate build step.
+
+`sbx`'s egress firewall applies here (it doesn't for the plain `docker` engine):
+a release's `APP_URL` host needs an explicit `sbx policy allow network <host>`
+rule or it 403s, even under the `balanced` policy. Note that `sbx` categorizes
+`host.docker.internal`/`gateway.docker.internal` requests under the `localhost`
+domain in its policy log (`sbx policy log`) — allow-rule the *resolved* host
+shown there, not the hostname you requested, if a rule doesn't seem to take.
+
+## Ops CLI
+
+Not published — for local/ops use only (image management, engine probing):
+
+```sh
+# See which engines this host can run (and why others can't)
+pnpm --filter @multiplayer-app/sandbox run cli -- detect
+
+# Download the per-stack base images (kernel + initramfs) the local engines need
+pnpm --filter @multiplayer-app/sandbox run cli -- images pull --from s3://<bucket>
+```
+
+Base images can also be built from scratch with `scripts/setup-vm-images.sh`
+(QEMU/Firecracker kernel + initramfs) or `scripts/setup-docker-images.sh`
+(Docker engine images).
+
+To build a complete, portable catalog for all runners, use:
+
+```sh
+pnpm run build:base-images
+
+# Build only selected runners/architecture/stacks
+RUNNERS="qemu docker" ARCH=x86_64 STACKS="node python" \
+  pnpm run build:base-images
+```
+
+The underlying script lives at `libs/sandbox/scripts/build-base-images.sh`.
+
+The default output is `libs/sandbox/dist-base-images/<runner>/<arch>/<stack>/` with a
+root `SHA256SUMS` file. QEMU and Firecracker entries contain `vmlinuz` and
+`initramfs.img`, while Lambda MicroVM entries contain `app.zip`. Docker, Docker
+Sandboxes, and Fargate images are built and tagged for an OCI registry instead
+of being duplicated as tar archives. Their prepared references are written to
+`container-images.tsv`. The default repository prefix is
+`multiplayerapp/sandbox`; override it with `CONTAINER_IMAGE_REPOSITORY`, and set
+`IMAGE_TAG` to the release version:
+
+```sh
+CONTAINER_IMAGE_REPOSITORY=my-dockerhub-user/sandbox IMAGE_TAG=v1.2.3 \
+  pnpm run build:base-images
+```
+
+Architecture-specific tags use `<version>-<arch>` so a separate publishing
+workflow can push them and optionally create a multi-architecture `<version>`
+manifest. The build script never uploads files or pushes images.
+
+Tags matching `sandbox-v*` run three release jobs: npm package publication and
+the two architecture-specific base-image publishers start after lint in
+parallel; once both architectures are available, a final job creates the
+multi-architecture Docker tags. The publisher expects the repository variable
+`SANDBOX_BASE_IMAGES_S3_BUCKET`, the existing `DOCKERHUB_ORGANIZATION` variable,
+and the existing `AWS_ROLE_ARN` and `DOCKERHUB_OIDC_ID` secrets.
+
+The runner-specific paths intentionally duplicate shared artifacts. That keeps
+each S3 prefix self-contained and allows runner formats to evolve independently.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAIA,OAAO,eAAe,CAAA"}

package/dist/cli.js

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+/* eslint-disable no-console -- console output is the CLI's user interface */
+// Worker CLI. Published as the global `sandbox` executable and also available locally via
+// `pnpm --filter @multiplayer-app/sandbox run cli -- <args>`.
+require("dotenv/config");
+const commander_1 = require("commander");
+const package_json_1 = require("../package.json");
+const config_1 = require("./config");
+const executor_1 = require("./executor");
+const detect_1 = require("./executor/detect");
+const images_1 = require("./images");
+const socket_client_1 = require("./socket-client");
+const console_relays_1 = require("./console-relays");
+const program = new commander_1.Command();
+program
+    .name('sandbox')
+    .description('Run and manage a Multiplayer sandbox worker')
+    .version(package_json_1.version);
+program
+    .command('start')
+    .description('start a worker and connect it to the sandbox control plane')
+    .option('--token <token>', 'worker authentication token (env: WORKER_TOKEN)')
+    .option('--worker-id <id>', 'stable worker ID (env: WORKER_ID; default: hostname)')
+    .option('--sandbox-url <url>', 'control-plane URL (env: SANDBOX_URL; default: https://api.sandbox.filingramp.com)')
+    .option('--max-vms <count>', 'maximum concurrent VMs (env: MAX_VMS)')
+    .action(async (opts) => {
+    const config = (0, config_1.loadWorkerConfigFromEnv)({
+        ...process.env,
+        ...(opts.token ? { WORKER_TOKEN: opts.token } : {}),
+        ...(opts.workerId ? { WORKER_ID: opts.workerId } : {}),
+        ...(opts.sandboxUrl ? { SANDBOX_URL: opts.sandboxUrl } : {}),
+        ...(opts.maxVms ? { MAX_VMS: opts.maxVms } : {}),
+    });
+    const executor = (0, executor_1.createExecutor)(config);
+    const socket = (0, socket_client_1.connectToSandbox)(config, executor);
+    (0, console_relays_1.attachConsoleRelays)(executor, socket);
+    let stopping = false;
+    const stop = async (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        console.log(`\n${signal} received; shutting down sandbox worker...`);
+        socket.disconnect();
+        const results = await Promise.allSettled(executor.list().map((vm) => executor.destroy(vm.vmId)));
+        const failed = results.filter((result) => result.status === 'rejected');
+        if (failed.length)
+            console.error(`Failed to destroy ${failed.length} VM(s) during shutdown`);
+        process.exit(failed.length ? 1 : 0);
+    };
+    process.once('SIGINT', () => { void stop('SIGINT'); });
+    process.once('SIGTERM', () => { void stop('SIGTERM'); });
+    console.log(`Starting sandbox worker ${config.workerId} → ${config.sandboxUrl}`);
+    // Socket.IO's reconnect timers keep the process alive until a termination signal arrives.
+});
+program
+    .command('detect')
+    .description('probe this host and report which micro-VM engines it can run')
+    .action(() => {
+    const probes = (0, detect_1.probeEngines)((0, config_1.loadWorkerConfigFromEnv)({ ...process.env, WORKER_ID: '-', WORKER_TOKEN: '-' }));
+    for (const probe of probes) {
+        const status = probe.available ? 'available' : `unavailable — ${probe.reason}`;
+        console.log(`${probe.engine.padEnd(15)} ${status}`);
+    }
+});
+const images = program
+    .command('images')
+    .description('manage engine base images (kernel + initramfs for QEMU/Firecracker)');
+images
+    .command('pull')
+    .description('download per-stack base images from S3 or an HTTPS mirror into the standard location')
+    .requiredOption('--from <location>', 's3://bucket[/prefix] or https:// base URL (env: VM_IMAGES_URL)', process.env.VM_IMAGES_URL)
+    .option('--arch <arch>', 'image architecture', (0, images_1.hostArch)())
+    .option('--stack <stack...>', 'stacks to pull (default: all)')
+    .option('--dest <dir>', 'destination directory (default: ~/.multiplayer/vm-images/<arch>)')
+    .option('--endpoint <url>', 'custom S3 endpoint, e.g. a MinIO URL (env: VM_IMAGES_ENDPOINT)', process.env.VM_IMAGES_ENDPOINT)
+    .action(async (opts) => {
+    var _a;
+    const dest = (_a = opts.dest) !== null && _a !== void 0 ? _a : (0, images_1.defaultImagesDir)(opts.arch);
+    const files = await (0, images_1.pullImages)({ location: opts.from, arch: opts.arch, stacks: opts.stack, endpoint: opts.endpoint }, dest);
+    for (const file of files)
+        console.log(`pulled ${file}`);
+    console.log('\nbase images ready — "sandbox detect" shows which engines they enable');
+});
+images
+    .command('push')
+    .description('upload locally built per-stack base images (scripts/setup-vm-images.sh) to S3')
+    .requiredOption('--to <location>', 's3://bucket[/prefix] (env: VM_IMAGES_URL)', process.env.VM_IMAGES_URL)
+    .option('--arch <arch>', 'image architecture', (0, images_1.hostArch)())
+    .option('--stack <stack...>', 'stacks to push (default: all found locally)')
+    .option('--src <dir>', 'source directory (default: ~/.multiplayer/vm-images/<arch>)')
+    .option('--endpoint <url>', 'custom S3 endpoint, e.g. a MinIO URL (env: VM_IMAGES_ENDPOINT)', process.env.VM_IMAGES_ENDPOINT)
+    .action(async (opts) => {
+    var _a;
+    const src = (_a = opts.src) !== null && _a !== void 0 ? _a : (0, images_1.defaultImagesDir)(opts.arch);
+    const uploaded = await (0, images_1.pushImages)({ location: opts.to, arch: opts.arch, stacks: opts.stack, endpoint: opts.endpoint }, src);
+    for (const uri of uploaded)
+        console.log(`pushed ${uri}`);
+});
+program.parseAsync().catch((error) => {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

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

package/dist/config.d.ts

@@ -1,3 +1,88 @@
-export type { BuilderApiConfig, BuilderApiAgentDeps } from './builder-api-config';
-export { agentDepsFromConfig } from './builder-api-config';
+import { version as WORKER_VERSION } from '../package.json';
+export { WORKER_VERSION };
+export interface RemoteWorkerConfig {
+    agentUrl: string;
+    authToken?: string;
+}
+export interface FirecrackerWorkerConfig {
+    bin: string;
+    imagesDir: string;
+    kernelPath?: string;
+    initrdPath?: string;
+    vmDataPath: string;
+}
+export interface QemuWorkerConfig {
+    bin: string;
+    imagesDir: string;
+    kernelPath?: string;
+    initrdPath?: string;
+    vmDataPath: string;
+    portRangeStart: number;
+    portRangeEnd: number;
+    accel: string;
+    cpu: string;
+    machine: string;
+}
+export interface LambdaMicrovmWorkerConfig {
+    region?: string;
+    imageArn: string;
+    stackImageArns: Record<string, string>;
+    ingressConnectorArns?: string[];
+    egressConnectorArns?: string[];
+    executionRoleArn?: string;
+    maxIdleSeconds: number;
+    suspendedDurationSeconds: number;
+    maximumDurationInSeconds: number;
+}
+export interface DockerWorkerConfig {
+    bin: string;
+    imagePrefix: string;
+    imageTag: string;
+    stackImages: Record<string, string>;
+    network?: string;
+    portRangeStart: number;
+    portRangeEnd: number;
+    guestPort: number;
+}
+export interface DockerSandboxWorkerConfig {
+    bin: string;
+    imagePrefix: string;
+    imageTag: string;
+    /** Fully-qualified `sbx template load`ed ref overrides, keyed by stack. */
+    stackTemplates: Record<string, string>;
+    /** In-sandbox start command per stack — `sbx create shell` doesn't run the image's own CMD. */
+    stackAgentCommands: Record<string, string>;
+    workspaceRoot: string;
+    portRangeStart: number;
+    portRangeEnd: number;
+    guestPort: number;
+    minMemoryMib: number;
+}
+export interface FargateWorkerConfig {
+    region?: string;
+    cluster: string;
+    taskDefinition?: string;
+    stackTaskDefinitions: Record<string, string>;
+    subnets: string[];
+    securityGroups?: string[];
+    assignPublicIp: boolean;
+    guestPort: number;
+    startTimeoutMs: number;
+}
+export interface WorkerConfig {
+    workerId: string;
+    token: string;
+    sandboxUrl: string;
+    workerSocketPath: string;
+    maxVms: number;
+    region?: string;
+    remote: RemoteWorkerConfig;
+    firecracker: FirecrackerWorkerConfig;
+    qemu: QemuWorkerConfig;
+    docker: DockerWorkerConfig;
+    dockerSandbox: DockerSandboxWorkerConfig;
+    lambdaMicrovm: LambdaMicrovmWorkerConfig;
+    fargate: FargateWorkerConfig;
+}
+export declare function loadWorkerConfigFromEnv(env?: NodeJS.ProcessEnv): WorkerConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AACjF,OAAO,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/config.js

@@ -1,6 +1,144 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.agentDepsFromConfig = void 0;
-var builder_api_config_1 = require("./builder-api-config");
-Object.defineProperty(exports, "agentDepsFromConfig", { enumerable: true, get: function () { return builder_api_config_1.agentDepsFromConfig; } });
+exports.WORKER_VERSION = void 0;
+exports.loadWorkerConfigFromEnv = loadWorkerConfigFromEnv;
+const os_1 = __importDefault(require("os"));
+const path_1 = __importDefault(require("path"));
+const package_json_1 = require("../package.json");
+Object.defineProperty(exports, "WORKER_VERSION", { enumerable: true, get: function () { return package_json_1.version; } });
+const images_1 = require("./images");
+/** Format: "node:<value>,python:<value>" — per-stack overrides (MicroVM image ARNs, Fargate task defs). */
+function parseStackMap(raw) {
+    const map = {};
+    if (!raw)
+        return map;
+    for (const pair of raw.split(',')) {
+        const idx = pair.indexOf(':');
+        if (idx === -1)
+            continue;
+        const stack = pair.slice(0, idx).trim();
+        const arn = pair.slice(idx + 1).trim();
+        if (stack && arn)
+            map[stack] = arn;
+    }
+    return map;
+}
+function parseArnList(raw) {
+    if (!raw)
+        return undefined;
+    const arns = raw.split(',').map((s) => s.trim()).filter(Boolean);
+    return arns.length ? arns : undefined;
+}
+function loadWorkerConfigFromEnv(env = process.env) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v, _w, _x, _y, _z, _0, _1, _2, _3, _4, _5, _6, _7;
+    const workerId = ((_a = env.WORKER_ID) === null || _a === void 0 ? void 0 : _a.trim()) || os_1.default.hostname();
+    const token = env.WORKER_TOKEN;
+    if (!token) {
+        throw new Error('WORKER_TOKEN is required');
+    }
+    return {
+        workerId,
+        token,
+        sandboxUrl: (_b = env.SANDBOX_URL) !== null && _b !== void 0 ? _b : 'https://api.sandbox.filingramp.com',
+        workerSocketPath: (_c = env.WORKER_SOCKET_PATH) !== null && _c !== void 0 ? _c : '/v0/sapi/workers/ws',
+        maxVms: Number(env.MAX_VMS) || 10,
+        region: env.WORKER_REGION,
+        remote: {
+            // No default: an unset AGENT_URL means the remote engine is not configured on this worker
+            agentUrl: (_d = env.AGENT_URL) !== null && _d !== void 0 ? _d : '',
+            authToken: env.AGENT_TOKEN,
+        },
+        firecracker: {
+            bin: (_e = env.FIRECRACKER_BIN) !== null && _e !== void 0 ? _e : 'firecracker',
+            // Per-stack base images (<imagesDir>/<stack>/vmlinuz + initramfs.img) from
+            // `worker-cli images pull` / setup-vm-images.sh; engine detection checks
+            // existence, so missing images just disable the engine.
+            imagesDir: (_g = (_f = env.FIRECRACKER_IMAGES_DIR) !== null && _f !== void 0 ? _f : env.VM_IMAGES_DIR) !== null && _g !== void 0 ? _g : (0, images_1.defaultImagesDir)(),
+            // Explicit single-image override, applied to every stack when both are set
+            kernelPath: env.FIRECRACKER_KERNEL,
+            initrdPath: env.FIRECRACKER_INITRD,
+            vmDataPath: (_h = env.FIRECRACKER_VM_DATA) !== null && _h !== void 0 ? _h : path_1.default.join(os_1.default.tmpdir(), 'firecracker-vms'),
+        },
+        lambdaMicrovm: {
+            region: (_j = env.MICROVM_AWS_REGION) !== null && _j !== void 0 ? _j : env.AWS_REGION,
+            imageArn: (_k = env.MICROVM_IMAGE_ARN) !== null && _k !== void 0 ? _k : '',
+            stackImageArns: parseStackMap(env.MICROVM_STACK_IMAGE_ARNS),
+            ingressConnectorArns: parseArnList(env.MICROVM_INGRESS_CONNECTORS),
+            egressConnectorArns: parseArnList(env.MICROVM_EGRESS_CONNECTORS),
+            executionRoleArn: env.MICROVM_EXECUTION_ROLE_ARN,
+            // 0 disables auto-suspend; the sandbox drives pause/resume explicitly by default
+            maxIdleSeconds: Number((_l = env.MICROVM_MAX_IDLE_SECONDS) !== null && _l !== void 0 ? _l : 900),
+            suspendedDurationSeconds: Number((_m = env.MICROVM_SUSPENDED_DURATION_SECONDS) !== null && _m !== void 0 ? _m : 28800),
+            maximumDurationInSeconds: Number((_o = env.MICROVM_MAX_DURATION_SECONDS) !== null && _o !== void 0 ? _o : 28800),
+        },
+        fargate: {
+            region: (_p = env.FARGATE_AWS_REGION) !== null && _p !== void 0 ? _p : env.AWS_REGION,
+            cluster: (_q = env.FARGATE_CLUSTER) !== null && _q !== void 0 ? _q : '',
+            taskDefinition: env.FARGATE_TASK_DEFINITION,
+            // Per-stack task definitions: "node:builder-node:3,python:builder-python:1"
+            stackTaskDefinitions: parseStackMap(env.FARGATE_STACK_TASK_DEFS),
+            subnets: (_s = (_r = env.FARGATE_SUBNETS) === null || _r === void 0 ? void 0 : _r.split(',').map((s) => s.trim()).filter(Boolean)) !== null && _s !== void 0 ? _s : [],
+            securityGroups: (_t = env.FARGATE_SECURITY_GROUPS) === null || _t === void 0 ? void 0 : _t.split(',').map((s) => s.trim()).filter(Boolean),
+            // ENABLED when the worker runs outside the task VPC (proxies to the task's public IP)
+            assignPublicIp: env.FARGATE_ASSIGN_PUBLIC_IP === 'true',
+            guestPort: Number(env.FARGATE_GUEST_PORT) || 8080,
+            startTimeoutMs: Number(env.FARGATE_START_TIMEOUT_MS) || 180000,
+        },
+        docker: {
+            bin: (_u = env.DOCKER_BIN) !== null && _u !== void 0 ? _u : 'docker',
+            // Local images from `scripts/setup-docker-images.sh`: <imagePrefix>-<stack>:<imageTag>
+            imagePrefix: (_v = env.DOCKER_IMAGE_PREFIX) !== null && _v !== void 0 ? _v : 'multiplayer-builder-vm',
+            imageTag: (_w = env.DOCKER_IMAGE_TAG) !== null && _w !== void 0 ? _w : 'local',
+            stackImages: parseStackMap(env.DOCKER_STACK_IMAGES),
+            network: env.DOCKER_NETWORK,
+            portRangeStart: Number(env.DOCKER_PORT_MIN) || 9100,
+            portRangeEnd: Number(env.DOCKER_PORT_MAX) || 9199,
+            guestPort: Number(env.DOCKER_GUEST_PORT) || 8080,
+        },
+        dockerSandbox: {
+            bin: (_x = env.SBX_BIN) !== null && _x !== void 0 ? _x : 'sbx',
+            // Bridged from the same local images `docker` (imagePrefix-imageTag) already uses —
+            // `docker save` + `sbx template load`, see docker-sandbox-executor.ts.
+            imagePrefix: (_y = env.SBX_IMAGE_PREFIX) !== null && _y !== void 0 ? _y : 'multiplayer-builder-vm',
+            imageTag: (_z = env.SBX_IMAGE_TAG) !== null && _z !== void 0 ? _z : 'local',
+            stackTemplates: parseStackMap(env.SBX_STACK_TEMPLATES),
+            // `sbx create shell` doesn't run the image's own CMD, so the engine launches
+            // it explicitly — defaults match each Dockerfile's own WORKDIR /app + CMD.
+            stackAgentCommands: {
+                node: 'node app.js',
+                python: 'python app.py',
+                static: 'node app.js',
+                ...parseStackMap(env.SBX_STACK_AGENT_COMMANDS),
+            },
+            workspaceRoot: (_0 = env.SBX_WORKSPACE_DIR) !== null && _0 !== void 0 ? _0 : path_1.default.join(os_1.default.tmpdir(), 'sbx-vms'),
+            portRangeStart: Number(env.SBX_PORT_MIN) || 9200,
+            portRangeEnd: Number(env.SBX_PORT_MAX) || 9299,
+            guestPort: Number(env.SBX_GUEST_PORT) || 8080,
+            // sbx rejects sandboxes below 1 GiB memory.
+            minMemoryMib: Number(env.SBX_MIN_MEMORY_MIB) || 1024,
+        },
+        qemu: {
+            bin: (_1 = env.QEMU_BIN) !== null && _1 !== void 0 ? _1 : 'qemu-system-aarch64',
+            // Per-stack base images (<imagesDir>/<stack>/vmlinuz + initramfs.img) from
+            // `worker-cli images pull` / setup-vm-images.sh; engine detection checks
+            // existence, so missing images just disable the engine.
+            imagesDir: (_3 = (_2 = env.QEMU_IMAGES_DIR) !== null && _2 !== void 0 ? _2 : env.VM_IMAGES_DIR) !== null && _3 !== void 0 ? _3 : (0, images_1.defaultImagesDir)(),
+            // Explicit single-image override, applied to every stack when both are set
+            kernelPath: env.QEMU_KERNEL,
+            initrdPath: env.QEMU_INITRD,
+            vmDataPath: (_4 = env.QEMU_VM_DATA) !== null && _4 !== void 0 ? _4 : path_1.default.join(os_1.default.tmpdir(), 'qemu-vms'),
+            portRangeStart: Number(env.QEMU_PORT_MIN) || 9000,
+            portRangeEnd: Number(env.QEMU_PORT_MAX) || 9999,
+            // Accelerator: hvf (macOS host), kvm (Linux + /dev/kvm), tcg (software, any host — slow)
+            accel: (_5 = env.QEMU_ACCEL) !== null && _5 !== void 0 ? _5 : (process.platform === 'darwin' ? 'hvf' : 'kvm'),
+            // CPU model: host requires hvf/kvm; max is best for tcg on aarch64; qemu64 for tcg x86_64
+            cpu: (_6 = env.QEMU_CPU) !== null && _6 !== void 0 ? _6 : 'host',
+            // Machine type: virt (aarch64), q35 (x86_64)
+            machine: (_7 = env.QEMU_MACHINE) !== null && _7 !== void 0 ? _7 : 'virt',
+        },
+    };
+}
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":";;;AACA,2DAA0D;AAAjD,yHAAA,mBAAmB,OAAA"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/console-relays.d.ts

@@ -0,0 +1,10 @@
+import type { Socket } from 'socket.io-client';
+import type { MultiEngineExecutor } from './executor';
+/**
+ * Wires up VNC and serial relays for any executor that exposes console endpoints (QEMU: VNC +
+ * serial TCP ports; Firecracker: serial via process stdio pipe). All media (frames, terminal
+ * data) flows through the sandbox socket to browsers — the worker never accepts inbound
+ * connections from the internet. Wraps `executor.create`/`destroy` in place.
+ */
+export declare function attachConsoleRelays(executor: MultiEngineExecutor, sandboxSocket: Socket): void;
+//# sourceMappingURL=console-relays.d.ts.map

package/dist/console-relays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-relays.d.ts","sourceRoot":"","sources":["../src/console-relays.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAA;AAC9C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAIrD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAmC9F"}

package/dist/console-relays.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachConsoleRelays = attachConsoleRelays;
+const vnc_relay_1 = require("./services/vnc-relay");
+const serial_relay_1 = require("./services/serial-relay");
+/**
+ * Wires up VNC and serial relays for any executor that exposes console endpoints (QEMU: VNC +
+ * serial TCP ports; Firecracker: serial via process stdio pipe). All media (frames, terminal
+ * data) flows through the sandbox socket to browsers — the worker never accepts inbound
+ * connections from the internet. Wraps `executor.create`/`destroy` in place.
+ */
+function attachConsoleRelays(executor, sandboxSocket) {
+    const relays = new Map();
+    const originalCreate = executor.create.bind(executor);
+    executor.create = async (spec) => {
+        var _a;
+        const handle = await originalCreate(spec);
+        const entry = {};
+        if (handle.vncPort) {
+            const vnc = new vnc_relay_1.VncRelay(handle.vmId, '127.0.0.1', handle.vncPort, sandboxSocket);
+            vnc.start();
+            entry.vnc = vnc;
+        }
+        const serialSource = handle.serialPort
+            ? { type: 'tcp', host: '127.0.0.1', port: handle.serialPort }
+            : (_a = executor.getSerialSource) === null || _a === void 0 ? void 0 : _a.call(executor, handle.vmId);
+        if (serialSource) {
+            const serial = new serial_relay_1.SerialRelay(handle.vmId, serialSource, sandboxSocket);
+            serial.connect();
+            entry.serial = serial;
+        }
+        if (entry.vnc || entry.serial)
+            relays.set(handle.vmId, entry);
+        return handle;
+    };
+    const originalDestroy = executor.destroy.bind(executor);
+    executor.destroy = async (vmId) => {
+        var _a, _b;
+        const entry = relays.get(vmId);
+        (_a = entry === null || entry === void 0 ? void 0 : entry.vnc) === null || _a === void 0 ? void 0 : _a.destroy();
+        (_b = entry === null || entry === void 0 ? void 0 : entry.serial) === null || _b === void 0 ? void 0 : _b.destroy();
+        relays.delete(vmId);
+        return originalDestroy(vmId);
+    };
+}
+//# sourceMappingURL=console-relays.js.map

package/dist/console-relays.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console-relays.js","sourceRoot":"","sources":["../src/console-relays.ts"],"names":[],"mappings":";;AAWA,kDAmCC;AA5CD,oDAA+C;AAC/C,0DAAqD;AAErD;;;;;GAKG;AACH,SAAgB,mBAAmB,CAAC,QAA6B,EAAE,aAAqB;IACtF,MAAM,MAAM,GAAG,IAAI,GAAG,EAAoD,CAAA;IAE1E,MAAM,cAAc,GAAG,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACrD,QAAQ,CAAC,MAAM,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE;;QAC/B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,CAAA;QACzC,MAAM,KAAK,GAA6C,EAAE,CAAA;QAE1D,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,MAAM,GAAG,GAAG,IAAI,oBAAQ,CAAC,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,OAAO,EAAE,aAAa,CAAC,CAAA;YACjF,GAAG,CAAC,KAAK,EAAE,CAAA;YACX,KAAK,CAAC,GAAG,GAAG,GAAG,CAAA;QACjB,CAAC;QAED,MAAM,YAAY,GAAG,MAAM,CAAC,UAAU;YACpC,CAAC,CAAC,EAAE,IAAI,EAAE,KAAc,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,CAAC,UAAU,EAAE;YACtE,CAAC,CAAC,MAAA,QAAQ,CAAC,eAAe,yDAAG,MAAM,CAAC,IAAI,CAAC,CAAA;QAC3C,IAAI,YAAY,EAAE,CAAC;YACjB,MAAM,MAAM,GAAG,IAAI,0BAAW,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,EAAE,aAAa,CAAC,CAAA;YACxE,MAAM,CAAC,OAAO,EAAE,CAAA;YAChB,KAAK,CAAC,MAAM,GAAG,MAAM,CAAA;QACvB,CAAC;QAED,IAAI,KAAK,CAAC,GAAG,IAAI,KAAK,CAAC,MAAM;YAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QAC7D,OAAO,MAAM,CAAA;IACf,CAAC,CAAA;IAED,MAAM,eAAe,GAAG,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACvD,QAAQ,CAAC,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE;;QAChC,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QAC9B,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,GAAG,0CAAE,OAAO,EAAE,CAAA;QACrB,MAAA,KAAK,aAAL,KAAK,uBAAL,KAAK,CAAE,MAAM,0CAAE,OAAO,EAAE,CAAA;QACxB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;QACnB,OAAO,eAAe,CAAC,IAAI,CAAC,CAAA;IAC9B,CAAC,CAAA;AACH,CAAC"}

package/dist/executor/detect.d.ts

@@ -0,0 +1,15 @@
+import { type VmEngine } from '@multiplayer-app/builder-types';
+import type { WorkerConfig } from '../config';
+export interface EngineProbe {
+    engine: VmEngine;
+    available: boolean;
+    /** Why the engine is unavailable (for startup logs). */
+    reason?: string;
+}
+/** Probe every engine against this host + config. Mock is always runnable. */
+export declare function probeEngines(config: WorkerConfig): EngineProbe[];
+export declare function detectEngines(config: WorkerConfig): {
+    engines: VmEngine[];
+    defaultEngine: VmEngine;
+};
+//# sourceMappingURL=detect.d.ts.map

package/dist/executor/detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/executor/detect.ts"],"names":[],"mappings":"AAGA,OAAO,EAAa,KAAK,QAAQ,EAAE,MAAM,gCAAgC,CAAA;AAEzE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAK7C,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,QAAQ,CAAA;IAChB,SAAS,EAAE,OAAO,CAAA;IAClB,wDAAwD;IACxD,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAyID,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,MAAM,EAAE,YAAY,GAAG,WAAW,EAAE,CAWhE;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG;IAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;IAAC,aAAa,EAAE,QAAQ,CAAA;CAAE,CAcpG"}