Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat: ranked sandbox backends per os

ogsamratb4c01fc61438
diff --git a/apps/server/src/box/backends/apple.ts b/apps/server/src/box/backends/apple.ts
new file mode 100644
index 00000000..f9971ad2
--- /dev/null
+++ b/apps/server/src/box/backends/apple.ts
@@ -0,0 +1,313 @@
+// Ported from the CLI (omnirush-cli src/box/backends/apple.js,
+// feat/local-box-backends); keep the two in step. Desktop differences: types;
+// the container-name prefix (containerName's env); boxd missing from the
+// sidecars is a reason.
+//
+// Apple's `container` (github.com/apple/container) as a box backend: macOS 26+
+// on Apple silicon, each container its own lightweight VM, no Docker. One
+// persistent container per project, made with `container create`, the
+// project and the run folder shared in at their paths (virtiofs), boxd
+// started as the entrypoint from the run folder and published on this
+// machine's loopback at a port chosen here (`-p` needs one named), with the
+// container's own address as the second way in. Snapshots are boxd's index
+// walk (there is no `container diff`).
+//
+// Written to the CLI of the 1.x line (1.0.0 froze the CLI; checked against
+// docs/command-reference.md and the Swift sources of 1.5.0, Sep 2026):
+// container system version --format json [{appName, version, buildType, commit}]
+// container system status exit 0 while the API server runs
+// container create|start|delete --force|inspect|list --all --format json
+// container image pull --platform linux/arm64 | image inspect | image list --format json | image delete
+// create: --name --label k=v --mount type=bind,source=,target=[,readonly] -p ip:host:container
+// -e K=V --workdir --cpus --memory --init --entrypoint
+// list/inspect JSON: { configuration: { id, image: { reference, descriptor: { digest } },
+// labels, publishedPorts }, status: running|stopped|stopping|unknown,
+// networks: [{ ipv4Address: "192.168.64.3/24" }] }
+
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { BOX_PORT, HOME_IN_BOX, LABEL, RUN_DIR, SHIMS_DIR, containerName, containerRoot, firstLine, freePort, helperPath, newToken, type BoxInstallLog, type BoxRuntime } from "../common.js";
+import { runCommand, type RunCommand } from "../run.js";
+import type { RuntimeResult } from "../runtime.js";
+import { versionAtLeast } from "./shared.js";
+import type { BoxDriver, OpenContext, Opened, PresentImage } from "./types.js";
+
+type Env = NodeJS.ProcessEnv;
+
+/** The `container` releases this backend is written for: 1.x (the CLI is frozen within it). */
+export const SUPPORTED = { min: "1.0.0", below: "2.0.0", tested: "1.5.0" };
+
+const BIN_DIRS = ["/usr/local/bin", "/opt/homebrew/bin"];
+
+export function findAppleBin({ env = process.env, exists = existsSync }: { env?: Env; exists?: (file: string) => boolean } = {}): string | null {
+ const asked = String(env.OMNIRUSH_BOX_APPLE_BIN || "").trim();
+ if (asked) return exists(asked) ? asked : null;
+ const dirs = [...String(env.PATH || "").split(":").filter(Boolean), ...BIN_DIRS];
+ for (const dir of dirs) {
+ const file = path.posix.join(dir, "container");
+ if (exists(file)) return file;
+ }
+ return null;
+}
+
+/** macOS major version from the Darwin kernel release (Darwin 25 = macOS 26). */
+export function macosMajor(release = os.release()): number | null {
+ const darwin = Number.parseInt(String(release).split(".")[0] ?? "", 10);
+ return Number.isFinite(darwin) && darwin >= 20 ? darwin + 1 : null;
+}
+
+function record(value: unknown): Record<string, unknown> {
+ return value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : {};
+}
+
+/** Versions from `container system version --format json` (or `--version` text). */
+export function parseVersions(stdout: unknown): { version: string; server?: string | null } {
+ const text = String(stdout ?? "").trim();
+ try {
+ const list: unknown = JSON.parse(text);
+ if (Array.isArray(list)) {
+ const entries = list.map(record);
+ const cli = entries.find((entry) => /^container$|cli/i.test(String(entry.appName ?? ""))) ?? entries[0];
+ const server = entries.find((entry) => /apiserver/i.test(String(entry.appName ?? "")));
+ return { version: String(cli?.version ?? ""), server: server ? String(server.version ?? "") : null };
+ }
+ } catch { /* text */ }
+ const match = /(\d+\.\d+\.\d+)/.exec(text);
+ return { version: match ? match[1]! : "" };
+}
+
+export async function probeApple({ env = process.env, platform = process.platform, arch = process.arch, release = os.release(), run = runCommand, exists = existsSync, timeoutMs = 6_000 }: { env?: Env; platform?: NodeJS.Platform; arch?: string; release?: string; run?: RunCommand; exists?: (file: string) => boolean; timeoutMs?: number } = {}): Promise<RuntimeResult> {
+ const base = { name: "apple", backend: "apple" };
+ if (platform !== "darwin") return { ...base, ok: false, reason: "Apple container is macOS only" };
+ if (arch !== "arm64") return { ...base, ok: false, reason: "Apple container needs an Apple silicon Mac" };
+ const major = macosMajor(release);
+ if (major !== null && major < 26) return { ...base, ok: false, reason: `Apple container needs macOS 26 or later (this is macOS ${major})` };
+ const bin = findAppleBin({ env, exists });
+ if (!bin) return { ...base, ok: false, reason: "Apple container is not installed (github.com/apple/container releases)" };
+ let res = await run(bin, ["system", "version", "--format", "json"], { env, timeoutMs });
+ let versions = res.code === 0 ? parseVersions(res.stdout) : { version: "" };
+ if (!versions.version) {
+ res = await run(bin, ["--version"], { env, timeoutMs });
+ versions = parseVersions(res.stdout);
+ }
+ const { version } = versions;
+ if (!version) return { ...base, ok: false, bin, reason: `could not read Apple container's version: ${firstLine(res.stderr) || res.code}` };
+ if (!versionAtLeast(version, SUPPORTED.min) || versionAtLeast(version, SUPPORTED.below)) {
+ return { ...base, ok: false, bin, version, reason: `Apple container ${version} is outside the supported ${SUPPORTED.min.split(".")[0]}.x line (tested with ${SUPPORTED.tested})` };
+ }
+ const status = await run(bin, ["system", "status"], { env, timeoutMs });
+ const said = `${status.stdout}\n${status.stderr}`;
+ if (status.code !== 0 || /not running|not registered|unavailable/i.test(said) || versions.server === null) {
+ return { ...base, ok: false, bin, version, reason: "Apple container is installed but not started (run `container system start` once)" };
+ }
+ return { ...base, ok: true, bin, version, os: "linux", arch: "arm64", flavor: "apple-container", rootless: true, vm: true };
+}
+
+const DIGEST = /^sha256:[0-9a-f]{64}$/;
+
+/** The first sha256 digest of an image record (index, descriptor, then anywhere). */
+export function findDigest(value: unknown): string | null {
+ const ok = (d: unknown): d is string => typeof d === "string" && DIGEST.test(d);
+ const rec = record(Array.isArray(value) ? value[0] : value);
+ const configuration = record(rec.configuration);
+ for (const cand of [record(rec.index).digest, record(rec.descriptor).digest, record(record(configuration.image).descriptor).digest, rec.digest]) if (ok(cand)) return cand;
+ let found: string | null = null;
+ const walk = (v: unknown) => {
+ if (found || v === null || typeof v !== "object") return;
+ for (const [k, x] of Object.entries(v)) {
+ if (k === "digest" && ok(x)) { found = x; return; }
+ walk(x);
+ }
+ };
+ walk(rec);
+ return found;
+}
+
+function parseJson(text: unknown): unknown {
+ try { return JSON.parse(String(text ?? "").trim()); } catch { return null; }
+}
+
+export type AppleBoxInfo = { id: string; running: boolean; status: string; image: string; digest: string | null; labels: Record<string, string>; address: string | null; created: string | null };
+
+export function snapshotInfo(snap: unknown): AppleBoxInfo {
+ const s = record(snap);
+ const cfg = record(s.configuration);
+ const image = record(cfg.image);
+ const networks = Array.isArray(s.networks) ? s.networks.map(record) : [];
+ const address = networks.map((n) => String(n.ipv4Address ?? n.address ?? "").split("/")[0]).find(Boolean) ?? null;
+ const labels = Object.fromEntries(Object.entries(record(cfg.labels)).map(([k, v]) => [k, String(v)]));
+ const digest = record(image.descriptor).digest;
+ return {
+ id: String(cfg.id ?? ""),
+ running: String(s.status ?? "") === "running",
+ status: String(s.status ?? ""),
+ image: String(image.reference ?? ""),
+ digest: typeof digest === "string" ? digest : null,
+ labels,
+ address,
+ created: typeof cfg.creationDate === "string" || typeof cfg.creationDate === "number" ? String(cfg.creationDate) : null,
+ };
+}
+
+async function inspectBox(runtime: BoxRuntime, name: string, run: RunCommand): Promise<AppleBoxInfo | null> {
+ const res = await run(runtime.bin, ["inspect", name], { timeoutMs: 20_000 });
+ if (res.code !== 0) return null;
+ const parsed = parseJson(res.stdout);
+ const snap = Array.isArray(parsed) ? parsed[0] : parsed;
+ if (!record(snap).configuration) return null;
+ return snapshotInfo(snap);
+}
+
+/** VM size for a box: what the user asked, else half the Mac (2–8 CPUs, 2–8 GiB; Apple's default 1 GiB is too small for installs). */
+export function appleResources({ env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { env?: Env; cpus?: number; memory?: number } = {}): string[] {
+ const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);
+ const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();
+ const c = askedCpus > 0 ? askedCpus : Math.max(2, Math.min(8, Math.floor(cpus / 2)));
+ const m = askedMem || `${Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)))}G`;
+ return ["--cpus", String(c), "--memory", m];
+}
+
+export function createAppleArgs({ name, key, root, croot, image, runFolder, shims = null, pkglog = null, token, port, env = process.env }: { name: string; key: string; root: string; croot: string; image: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; port: number; env?: Env }): string[] {
+ return [
+ "create", "--name", name,
+ "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`, "--label", `${LABEL}.port=${port}`,
+ "--mount", `type=bind,source=${root},target=${croot}`,
+ "--mount", `type=bind,source=${runFolder},target=${RUN_DIR}`,
+ "--mount", `type=bind,source=${path.join(runFolder, "bin")},target=/opt/omnirush/bin,readonly`,
+ ...(shims ? ["--mount", `type=bind,source=${shims},target=${SHIMS_DIR}-src,readonly`] : []),
+ ...(pkglog ? ["--mount", `type=bind,source=${pkglog.root},target=${containerRoot(pkglog.root, "darwin")}`] : []),
+ "-p", `127.0.0.1:${port}:${BOX_PORT}`,
+ "-e", `BOXD_TOKEN=${token}`, "-e", "BOXD_UID=0", "-e", "BOXD_GID=0", "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,
+ "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",
+ "--workdir", croot,
+ ...appleResources({ env }),
+ "--init",
+ "--entrypoint", "/opt/omnirush/bin/boxd",
+ image,
+ ];
+}
+
+/** Copy boxd into the run folder's bin/ (mounted read-only at /opt/omnirush/bin). */
+function placeBoxd(runFolder: string, env: Env): string | null {
+ const source = helperPath("boxd", { goos: "linux", goarch: "arm64", env });
+ if (!source) return "the sandbox helper boxd (linux-arm64) is missing from this install";
+ const dir = path.join(runFolder, "bin");
+ mkdirSync(dir, { recursive: true });
+ const target = path.join(dir, "boxd");
+ let same = false;
+ try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }
+ if (!same) {
+ copyFileSync(source, `${target}.tmp`);
+ chmodSync(`${target}.tmp`, 0o755);
+ copyFileSync(`${target}.tmp`, target);
+ chmodSync(target, 0o755);
+ }
+ return null;
+}
+
+async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<PresentImage | null> {
+ const res = await run(runtime.bin, ["image", "inspect", image.pull], { timeoutMs: 20_000 });
+ if (res.code !== 0) return null;
+ const parsed = parseJson(res.stdout);
+ if (!parsed || (Array.isArray(parsed) && parsed.length === 0)) return null;
+ const digest = findDigest(parsed);
+ return { id: digest || image.pull, digest, arch: "arm64" };
+}
+
+async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ ok: true } | { ok: false; error: string }> {
+ const res = await run(runtime.bin, ["image", "pull", "--platform", "linux/arm64", image.pull], { timeoutMs: 60 * 60_000 });
+ return res.code === 0 ? { ok: true } : { ok: false, error: firstLine(res.stderr) || `image pull exited ${res.code}` };
+}
+
+async function open(ctx: OpenContext): Promise<Opened> {
+ const { key, name, root, croot, runtime, run, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling } = ctx;
+ let info = await inspectBox(runtime, name, run);
+ if (info && info.labels[`${LABEL}.root`] && info.labels[`${LABEL}.root`] !== root) return { ok: false, error: `container ${name} belongs to another folder` };
+ const placed = placeBoxd(runFolder, env);
+ if (placed) return { ok: false, error: placed };
+ const tokenFile = path.join(runFolder, "box-token");
+ let created = null;
+ if (!info) {
+ let present = await imagePresent(runtime, image, { run });
+ if (!present) {
+ if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };
+ onPulling();
+ const pulled = await pull(runtime, image, { run });
+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };
+ present = await imagePresent(runtime, image, { run });
+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };
+ }
+ const token = newToken();
+ writeFileSync(tokenFile, token, { mode: 0o600 });
+ const port = await freePort();
+ const made = await run(runtime.bin, createAppleArgs({ name, key, root, croot, image: image.pull, runFolder, shims, pkglog, token, port, env }), { timeoutMs: 120_000 });
+ if (made.code !== 0) return { ok: false, error: `could not create the sandbox: ${firstLine(made.stderr)}` };
+ created = { ref: image.ref, pull: image.pull, digest: image.digest || present.digest, id: present.id, stack: image.stack };
+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "apple" });
+ info = await inspectBox(runtime, name, run);
+ if (!info) return { ok: false, error: "the sandbox was created but cannot be inspected" };
+ }
+ if (!info.running) {
+ const started = await run(runtime.bin, ["start", name], { timeoutMs: 120_000 });
+ if (started.code !== 0) return { ok: false, error: `could not start the sandbox: ${firstLine(started.stderr)}` };
+ info = (await inspectBox(runtime, name, run)) ?? info;
+ }
+ let token = "";
+ try { token = readFileSync(tokenFile, "utf8").trim(); } catch { /* none */ }
+ const port = Number(info.labels[`${LABEL}.port`]) || 0;
+ if (!token || !port) return { ok: false, error: "the sandbox has no port or token (Reset sandbox makes a new one)" };
+ const alternates = info.address ? [{ host: info.address, port: BOX_PORT, token }] : [];
+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token }, alternates, uid: 0, gid: 0, containerId: info.id || name, imageId: info.digest || info.image, mounts: [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root, "darwin")] : [])] };
+}
+
+export const appleDriver: BoxDriver = {
+ kind: "apple",
+ execFallback: false,
+ imagePresent,
+ pull,
+ pullCommand(runtime, image) {
+ return { bin: runtime.bin, args: ["image", "pull", "--platform", "linux/arm64", image.pull] };
+ },
+ async exists(runtime, key, { run = runCommand, env = process.env } = {}) {
+ return Boolean(await inspectBox(runtime, containerName(key, env), run));
+ },
+ open,
+ async list(runtime, { run = runCommand } = {}) {
+ const res = await run(runtime.bin, ["list", "--all", "--format", "json"], { timeoutMs: 30_000 });
+ if (res.code !== 0) return [];
+ const parsed = parseJson(res.stdout);
+ if (!Array.isArray(parsed)) return [];
+ return parsed.map(snapshotInfo).filter((info) => info.labels[LABEL] === "1").map((info) => ({ key: info.labels[`${LABEL}.key`] ?? "", name: info.id, root: info.labels[`${LABEL}.root`] ?? "", running: info.running, image: info.image, created: String(info.created ?? "") }));
+ },
+ async remove(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await run(runtime.bin, ["delete", "--force", containerName(key, env)], { timeoutMs: 60_000 });
+ return { removed: res.code === 0 };
+ },
+ async gcImages(runtime, { run = runCommand, current, used }) {
+ const removed = [];
+ const res = await run(runtime.bin, ["image", "list", "--format", "json"], { timeoutMs: 30_000 });
+ const parsed = parseJson(res.stdout);
+ for (const entry of Array.isArray(parsed) ? parsed.map(record) : []) {
+ const ref = String(entry.reference ?? entry.name ?? "");
+ if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref)) continue;
+ const del = await run(runtime.bin, ["image", "delete", ref], { timeoutMs: 60_000 });
+ if (del.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });
+ }
+ return removed;
+ },
+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await run(runtime.bin, ["stop", containerName(key, env)], { timeoutMs: 60_000 });
+ return { stopped: res.code === 0 };
+ },
+ async upperBytes() {
+ return null;
+ },
+ shellCommand(runtime, { key, croot, env = process.env }) {
+ return { bin: runtime.bin, args: ["exec", "--interactive", "--tty", "--workdir", croot, containerName(key, env), "/bin/bash", "-l"] };
+ },
+ execCommand(runtime, { key, env = process.env }) {
+ return { bin: runtime.bin, args: ["exec", "--interactive", containerName(key, env)], env: {} };
+ },
+};
diff --git a/apps/server/src/box/backends/bwrap.ts b/apps/server/src/box/backends/bwrap.ts
new file mode 100644
index 00000000..3bec757b
--- /dev/null
+++ b/apps/server/src/box/backends/bwrap.ts
@@ -0,0 +1,281 @@
+// Ported from the CLI (omnirush-cli src/box/backends/bwrap.js,
+// feat/local-box-backends); keep the two in step. Desktop differences: types;
+// the one-time admin step (`sudo omnirush sandbox enable`) is the CLI's, so
+// the AppArmor reason names the CLI; boxrun missing from the sidecars is a
+// reason, not a path.
+//
+// The bubblewrap backend (Linux; also what runs inside the OmniRush WSL
+// distro): no daemon, no root, nothing to install where unprivileged user
+// namespaces work. `boxrun` (box/go/cmd/boxrun) pulls the pinned image and
+// unpacks it (~/.omnirush/box/bwrap/store), and runs each project's box as
+// that root filesystem under a per-project overlay upper layer
+// (~/.omnirush/box/bwrap/boxes/<key>), in its own user, mount, PID, IPC and
+// UTS namespaces, on the host's network. The upper layer stays on disk, so
+// installs survive restarts; boxd is the same helper the containers run.
+//
+// Ubuntu 23.10+ blocks unprivileged user namespaces through AppArmor
+// (kernel.apparmor_restrict_unprivileged_userns=1): the probe says so in one
+// line and the next backend (rootless Podman, Docker) is used.
+
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { GOARCH, RUN_DIR, SHIMS_DIR, containerName, containerRoot, helperPath, newToken, readJson, writeJson, type BoxInstallLog, type BoxRuntime } from "../common.js";
+import { runCommand, type RunCommand } from "../run.js";
+import type { RuntimeResult } from "../runtime.js";
+import { boxshExec, num, parseOut, str } from "./shared.js";
+import type { BoxDriver, ListedBox, OpenContext, Opened, PresentImage, Removed } from "./types.js";
+
+export { parseOut } from "./shared.js";
+
+type Env = NodeJS.ProcessEnv;
+
+/** Where `sudo omnirush sandbox enable` (the CLI) puts OmniRush's bwrap (root-owned, profiled). */
+export const ENABLED_BWRAP = "/usr/local/lib/omnirush/bwrap";
+export const APPARMOR_PROFILE = "/etc/apparmor.d/omnirush-bwrap";
+/** boxd exits (and the box with it) after this long with no request. */
+export const IDLE_MINUTES = 120;
+
+export function bwrapHome(home: string): string {
+ return path.join(home, "bwrap");
+}
+const storeDir = (home: string) => path.join(bwrapHome(home), "store");
+const boxDir = (home: string, key: string) => path.join(bwrapHome(home), "boxes", key);
+const metaFile = (home: string, key: string) => path.join(bwrapHome(home), "boxes", `${key}.json`);
+
+/** A box's own record (boxes/<key>.json under the backend's folder). */
+export type BoxMeta = {
+ v: 1; key: string; root: string; croot: string; image: string; arch: string; ref: string; pull: string; digest: string | null;
+ config?: string; stack: string; token: string; instance: string; created_at: string; mounts?: string[];
+};
+
+/** boxrun for this machine's architecture (inside a box: linux/<arch>); null when this install has none. */
+export function boxrunPath({ env = process.env, arch = process.arch }: { env?: Env; arch?: string } = {}): string | null {
+ return helperPath("boxrun", { goos: "linux", goarch: GOARCH[arch] || "amd64", env });
+}
+
+/**
+ * The bwrap to use, best first: OMNIRUSH_BOX_BWRAP, the profiled copy
+ * `sandbox enable` installed, the one shipped with OmniRush (static, for
+ * systems without bubblewrap). Null: boxrun looks for the system's.
+ */
+export function bwrapPath({ env = process.env, arch = process.arch, exists = existsSync }: { env?: Env; arch?: string; exists?: (file: string) => boolean } = {}): string | null {
+ const asked = String(env.OMNIRUSH_BOX_BWRAP || "").trim();
+ if (asked) return asked;
+ if (exists(ENABLED_BWRAP)) return ENABLED_BWRAP;
+ const shipped = helperPath("bwrap", { goos: "linux", goarch: GOARCH[arch] || "amd64", env });
+ return shipped && exists(shipped) ? shipped : null;
+}
+
+/** One line for each reason boxrun's probe gives. */
+export function explainProbe(out: Record<string, unknown> | null): string {
+ const reason = str(out?.reason) || "bubblewrap could not start";
+ switch (out?.code) {
+ case "apparmor":
+ return `${reason}; one-time admin fix: \`sudo omnirush sandbox enable\` (OmniRush CLI)`;
+ case "no_bwrap":
+ return `${reason} (\`sudo apt install bubblewrap\` or your system's package)`;
+ case "userns_off":
+ return `${reason}; an admin can allow them, or use Podman or Docker`;
+ default:
+ return reason;
+ }
+}
+
+/** Can boxes run here with bubblewrap? A real start (5–20 ms), never a guess from the distro. */
+export async function probeBwrap({ env = process.env, boxHome, run = runCommand, timeoutMs = 6_000, arch = process.arch, exists = existsSync, platform = process.platform }: { env?: Env; boxHome: string; run?: RunCommand; timeoutMs?: number; arch?: string; exists?: (file: string) => boolean; platform?: NodeJS.Platform }): Promise<RuntimeResult> {
+ const base = { name: "bwrap", backend: "bwrap" };
+ if (platform !== "linux") return { ...base, ok: false, reason: "bubblewrap is Linux only" };
+ const bin = boxrunPath({ env, arch });
+ if (!bin || !exists(bin)) return { ...base, ok: false, ...(bin ? { bin } : {}), reason: "the sandbox helper boxrun is missing from this install" };
+ try { mkdirSync(boxHome, { recursive: true }); } catch { /* the probe says */ }
+ const args = ["probe", "--dir", boxHome];
+ const bw = bwrapPath({ env, arch, exists });
+ if (bw) args.push("--bwrap", bw);
+ const res = await run(bin, args, { env: { PATH: env.PATH || "/usr/bin:/bin", USER: env.USER || "" }, timeoutMs });
+ const out = parseOut(res.stdout);
+ if (!out) return { ...base, ok: false, bin, reason: res.error === "timeout" ? "the bubblewrap probe did not answer in time" : `boxrun probe failed: ${String(res.stderr || "").trim().slice(0, 200)}` };
+ if (!out.ok) return { ...base, ok: false, bin, code: str(out.code), reason: explainProbe(out) };
+ return {
+ ...base, ok: true, bin, bwrap: str(out.bwrap) || bw || null,
+ version: str(out.bwrap_version),
+ os: "linux", arch: GOARCH[arch] || arch,
+ flavor: out.overlay === "fuse" ? "fuse-overlayfs" : "overlayfs",
+ idmap: str(out.idmap) || "single", launcher: str(out.launcher) || "bwrap",
+ rootless: !out.root, vm: false, kernel: str(out.kernel) || os.release(),
+ };
+}
+
+function storeArgs(home: string): string[] {
+ return ["--store", storeDir(home)];
+}
+
+function presentOf(out: Record<string, unknown> | null): PresentImage | null {
+ if (!out?.present) return null;
+ return { id: str(out.id), digest: str(out.digest) || null, arch: str(out.arch), config: str(out.config) };
+}
+
+async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, home = "" }: { run?: RunCommand; home?: string } = {}): Promise<PresentImage | null> {
+ const res = await run(runtime.bin, ["image", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"], { timeoutMs: 15_000 });
+ return presentOf(parseOut(res.stdout));
+}
+
+async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, home = "" }: { run?: RunCommand; home?: string } = {}): Promise<{ ok: true } | { ok: false; error: string }> {
+ const res = await run(runtime.bin, ["pull", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"], { timeoutMs: 60 * 60_000 });
+ const out = parseOut(res.stdout);
+ return out?.ok ? { ok: true } : { ok: false, error: String(out?.error || res.stderr || `boxrun pull exited ${res.code}`).slice(0, 300) };
+}
+
+/** boxd's environment in a box (what `docker create -e` gives the containers). */
+export function boxdEnv({ token, croot, idleMinutes = IDLE_MINUTES, listen = "127.0.0.1:0" }: { token: string; croot: string; idleMinutes?: number; listen?: string }): string[] {
+ return [
+ `BOXD_TOKEN=${token}`, "BOXD_UID=0", "BOXD_GID=0", "BOXD_HOME=/root", `BOXD_ROOT=${croot}`,
+ `BOXD_ENV_FILE=${RUN_DIR}/env`, `BOXD_LISTEN=${listen}`, `BOXD_PORT_FILE=${RUN_DIR}/boxd.port`, `BOXD_IDLE_EXIT=${idleMinutes}`,
+ "LANG=C.UTF-8", "DEBIAN_FRONTEND=noninteractive",
+ ];
+}
+
+/** `boxrun up` arguments for a project's box. */
+export function upArgs({ box, store, image, boxd, portFile, root, croot, runFolder, shims = null, pkglog = null, token, bwrap = null, idleMinutes = IDLE_MINUTES, listen, platform = "linux", mapPath = (p: string) => p }: { box: string; store: string; image: string; boxd: string; portFile: string; root: string; croot: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; bwrap?: string | null; idleMinutes?: number; listen?: string; platform?: NodeJS.Platform; mapPath?: (p: string) => string }): string[] {
+ const args = ["up", "--box", box, "--store", store, "--image", image, "--boxd", boxd, "--port-file", portFile,
+ "--bind", `${mapPath(root)}=${croot}`, "--bind", `${mapPath(runFolder)}=${RUN_DIR}`];
+ if (shims) args.push("--ro-bind", `${mapPath(shims)}=${SHIMS_DIR}-src`);
+ if (pkglog) args.push("--bind", `${mapPath(pkglog.root)}=${containerRoot(pkglog.root, platform)}`);
+ for (const kv of boxdEnv({ token, croot, idleMinutes, ...(listen ? { listen } : {}) })) args.push("--env", kv);
+ if (bwrap) args.push("--bwrap", bwrap);
+ return args;
+}
+
+/** A new box's own record. */
+export function newMeta({ key, root, croot, present, image }: { key: string; root: string; croot: string; present: PresentImage; image: { ref: string; pull: string; digest: string | null; stack: string } }): BoxMeta {
+ return { v: 1, key, root, croot, image: present.id, arch: present.arch, ref: image.ref, pull: image.pull, digest: image.digest || present.digest, ...(present.config ? { config: present.config } : {}), stack: image.stack, token: newToken(), instance: newToken().slice(0, 12), created_at: new Date().toISOString() };
+}
+
+async function open(ctx: OpenContext): Promise<Opened> {
+ const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling } = ctx;
+ const file = metaFile(home, key);
+ let meta = readJson<BoxMeta>(file);
+ if (meta && meta.root !== root) return { ok: false, error: `box ${key} belongs to another folder` };
+ let created = null;
+ if (!meta || !existsSync(boxDir(home, key))) {
+ let present = await imagePresent(runtime, image, { run, home });
+ if (!present) {
+ if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };
+ onPulling();
+ const pulled = await pull(runtime, image, { run, home });
+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };
+ present = await imagePresent(runtime, image, { run, home });
+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };
+ }
+ meta = newMeta({ key, root, croot, present, image });
+ mkdirSync(path.dirname(file), { recursive: true });
+ writeJson(file, meta);
+ created = { ref: image.ref, pull: image.pull, digest: meta.digest, id: present.config || present.id, stack: image.stack };
+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "bwrap" });
+ }
+ const boxd = helperPath("boxd", { goos: "linux", goarch: GOARCH[meta.arch] || runtime.arch || "amd64", env });
+ if (!boxd) return { ok: false, error: "the sandbox helper boxd is missing from this install" };
+ const portFile = path.join(runFolder, "boxd.port");
+ const idle = Number(env.OMNIRUSH_BOX_IDLE_MIN) > 0 ? Number(env.OMNIRUSH_BOX_IDLE_MIN) : IDLE_MINUTES;
+ const args = upArgs({ box: boxDir(home, key), store: storeDir(home), image: meta.image, boxd, portFile, root, croot, runFolder, shims, pkglog, token: meta.token, bwrap: runtime.bwrap ?? null, idleMinutes: idle });
+ const res = await run(runtime.bin, args, { timeoutMs: 45_000, env: { PATH: env.PATH || "/usr/bin:/bin", USER: env.USER || "" } });
+ const out = parseOut(res.stdout);
+ const port = num(out?.port);
+ if (!out?.ok || !port) return { ok: false, error: `could not start the sandbox: ${String(out?.error || res.stderr || res.error || res.code).slice(0, 300)}` };
+ // The folders this running box was started with (a box another session
+ // started keeps its own until it stops).
+ const mounts = [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root)] : [])];
+ if (!out.reused) writeJson(file, { ...meta, mounts, started_at: new Date().toISOString(), launcher: out.launcher, idmap: out.idmap, overlay: out.overlay });
+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token: meta.token }, uid: 0, gid: 0, containerId: `bwrap_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: out.reused ? (meta.mounts ?? mounts) : mounts, timing: { ...(num(out.ms) !== null ? { ms: num(out.ms) ?? 0 } : {}), reused: Boolean(out.reused) } };
+}
+
+function pidAlive(pid: unknown): boolean {
+ if (typeof pid !== "number" || !pid) return false;
+ try { process.kill(pid, 0); return true; } catch (error) { return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM"; }
+}
+
+async function list(_runtime: BoxRuntime, { home = "" }: { home?: string } = {}): Promise<ListedBox[]> {
+ const dir = path.join(bwrapHome(home), "boxes");
+ let names: string[] = [];
+ try { names = readdirSync(dir).filter((name) => name.endsWith(".json")); } catch { return []; }
+ const out: ListedBox[] = [];
+ for (const name of names) {
+ const meta = readJson<BoxMeta>(path.join(dir, name));
+ if (!meta?.key) continue;
+ let running = false;
+ try { running = pidAlive(JSON.parse(readFileSync(path.join(boxDir(home, meta.key), "state.json"), "utf8")).pid); } catch { /* stopped */ }
+ out.push({ key: meta.key, name: containerName(meta.key), root: meta.root, running, image: meta.pull || meta.ref || meta.image, created: meta.created_at || "" });
+ }
+ return out;
+}
+
+export const bwrapDriver: BoxDriver = {
+ kind: "bwrap",
+ execFallback: false,
+ imagePresent,
+ pull,
+ pullCommand(runtime, image, home) {
+ return { bin: runtime.bin, args: ["pull", ...storeArgs(home), "--ref", image.pull, "--arch", runtime.arch || GOARCH[process.arch] || "amd64"] };
+ },
+ async exists(_runtime, key, { home = "" } = {}) {
+ return existsSync(metaFile(home, key)) && existsSync(boxDir(home, key));
+ },
+ open,
+ list,
+ async remove(runtime, key, { run = runCommand, home = "" } = {}) {
+ const res = await run(runtime.bin, ["rm", "--box", boxDir(home, key), ...(runtime.bwrap ? ["--bwrap", runtime.bwrap] : [])], { timeoutMs: 120_000 });
+ const had = existsSync(metaFile(home, key));
+ rmSync(metaFile(home, key), { force: true });
+ return { removed: had && Boolean(parseOut(res.stdout)?.ok) };
+ },
+ async stop(runtime, key, { run = runCommand, home = "" } = {}) {
+ const res = await run(runtime.bin, ["stop", "--box", boxDir(home, key)], { timeoutMs: 60_000 });
+ return { stopped: Boolean(parseOut(res.stdout)?.ok) };
+ },
+ async gcImages(runtime, { run = runCommand, home = "", current, used }) {
+ const removed: Removed[] = [];
+ const dir = path.join(storeDir(home), "images");
+ let ids: string[] = [];
+ try { ids = readdirSync(dir); } catch { return removed; }
+ const usedIds = new Set<string>();
+ for (const box of await list(runtime, { home })) {
+ const meta = readJson<BoxMeta>(metaFile(home, box.key));
+ if (meta?.image) usedIds.add(meta.image);
+ }
+ const plain = (ref: unknown) => String(ref || "").replace(/@sha256:[0-9a-f]{64}$/, "").replace(/^docker\.io\//, "");
+ const currentPlain = new Set([...current].map(plain));
+ for (const id of ids) {
+ const img = readJson<{ ref?: string }>(path.join(dir, id, "image.json"));
+ if (!img || usedIds.has(id) || used.has(String(img.ref)) || currentPlain.has(plain(img.ref))) continue;
+ if (!/(^|\/)omnirush-ai\/box-[a-z]+:/.test(String(img.ref))) continue;
+ const res = await run(runtime.bin, ["rmimage", ...storeArgs(home), "--id", id], { timeoutMs: 120_000 });
+ if (parseOut(res.stdout)?.ok) removed.push({ kind: "image", name: String(img.ref), reason: "not current" });
+ }
+ return removed;
+ },
+ async upperBytes(runtime, key, { run = runCommand, home = "" } = {}) {
+ const res = await run(runtime.bin, ["status", "--box", boxDir(home, key)], { timeoutMs: 60_000 });
+ return num(parseOut(res.stdout)?.upper_bytes);
+ },
+ shellCommand(runtime, { key, croot, home }) {
+ return { bin: runtime.bin, args: ["enter", "--box", boxDir(home, key), "--wd", croot, "--", "/bin/bash", "-l"] };
+ },
+ execCommand: (_runtime, { key, home }) => boxshExec({ key, home }),
+};
+
+/** The AppArmor profile `sudo omnirush sandbox enable` (the CLI) installs for OmniRush's own bwrap copy. */
+export function apparmorProfile(bwrap = ENABLED_BWRAP): string {
+ return `# OmniRush sandbox: lets OmniRush's own bubblewrap copy (root-owned) create
+# user namespaces on systems that restrict them (Ubuntu 23.10+). Written by
+# \`sudo omnirush sandbox enable\`; \`sudo omnirush sandbox enable --undo\` removes it.
+abi <abi/4.0>,
+include <tunables/global>
+
+profile omnirush-bwrap ${bwrap} flags=(unconfined) {
+ userns,
+
+ include if exists <local/omnirush-bwrap>
+}
+`;
+}
diff --git a/apps/server/src/box/backends/container.ts b/apps/server/src/box/backends/container.ts
new file mode 100644
index 00000000..9576a94e
--- /dev/null
+++ b/apps/server/src/box/backends/container.ts
@@ -0,0 +1,304 @@
+// Ported from the CLI (omnirush-cli src/box/backends/container.js,
+// feat/local-box-backends); keep the two in step. Desktop differences:
+// types; the container-name prefix (containerName's env).
+//
+// Container engines as box backends: Docker (and what speaks its CLI:
+// Docker Desktop, OrbStack, colima, Rancher Desktop, a Docker engine in
+// WSL 2) and Podman (rootless on Linux, Podman machine elsewhere). One
+// persistent container per project; boxd is copied in and published on
+// this machine's loopback.
+
+import { readFileSync } from "node:fs";
+import os from "node:os";
+
+import { BOX_PORT, GOARCH, HOME_IN_BOX, LABEL, RUN_DIR, SHIMS_DIR, containerName, containerRoot, firstLine, helperPath, newToken, wslPath, type BoxInstallLog, type BoxRuntime } from "../common.js";
+import { runCommand, type RunCommand, type RunOptions } from "../run.js";
+import type { BoxDriver, ListedBox, OpenContext, Opened } from "./types.js";
+
+type Env = NodeJS.ProcessEnv;
+
+/**
+ * A tar with one executable file at `name` (and its folders), for `cp - <c>:/`:
+ * `cp <file> <c>:<path>` needs the folder to exist in the image already.
+ */
+export function singleFileTar(name: string, data: Buffer, mode = 0o755): Buffer {
+ const blocks: Buffer[] = [];
+ const header = (entry: string, type: string, size: number, entryMode: number) => {
+ const h = Buffer.alloc(512);
+ h.write(entry, 0, 100, "utf8");
+ h.write(`${entryMode.toString(8).padStart(7, "0")}\0`, 100);
+ h.write("0000000\0", 108);
+ h.write("0000000\0", 116);
+ h.write(`${size.toString(8).padStart(11, "0")}\0`, 124);
+ h.write(`${Math.floor(Date.now() / 1000).toString(8).padStart(11, "0")}\0`, 136);
+ h.write(" ", 148);
+ h.write(type, 156);
+ h.write("ustar\0", 257);
+ h.write("00", 263);
+ let sum = 0;
+ for (const byte of h) sum += byte;
+ h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
+ return h;
+ };
+ const parts = name.split("/");
+ for (let i = 1; i < parts.length; i += 1) blocks.push(header(`${parts.slice(0, i).join("/")}/`, "5", 0, 0o755));
+ blocks.push(header(name, "0", data.length, mode));
+ blocks.push(data, Buffer.alloc((512 - (data.length % 512)) % 512), Buffer.alloc(1024));
+ return Buffer.concat(blocks);
+}
+
+// --- the runtime CLI ------------------------------------------------------------
+
+/** Runs the runtime's CLI (`wsl.exe -e docker ...` for a WSL engine, `docker --context x ...`). */
+export function rt(runtime: BoxRuntime, run: RunCommand = runCommand) {
+ const prefix = Array.isArray(runtime.prefix) ? runtime.prefix : [];
+ return (args: string[], opts: RunOptions = {}) => run(runtime.bin, [...prefix, ...args], { timeoutMs: 60_000, ...opts });
+}
+
+/** Where the runtime finds a folder of this machine (a WSL engine sees Windows drives under /mnt). */
+function source(runtime: BoxRuntime, p: string): string {
+ return runtime.wsl ? wslPath(p) : p;
+}
+
+/** Whether `image` is present locally; its id and repo digest when it is. */
+export async function inspectImage(runtime: BoxRuntime, image: string, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ id: string; digest: string | null; arch: string; size: number } | null> {
+ const res = await rt(runtime, run)(["image", "inspect", image, "--format", "{{json .}}"], { timeoutMs: 20_000 });
+ if (res.code !== 0) return null;
+ try {
+ const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");
+ const digests: unknown[] = Array.isArray(info.RepoDigests) ? info.RepoDigests : [];
+ const digest = digests.map((entry) => String(entry).split("@")[1]).find((d) => /^sha256:[0-9a-f]{64}$/.test(d || "")) || null;
+ return { id: String(info.Id || ""), digest, arch: String(info.Architecture || ""), size: Number(info.Size || 0) };
+ } catch {
+ return null;
+ }
+}
+
+/** `pull` with retries (a flaky link picks up where it stopped). */
+export async function pullImage(runtime: BoxRuntime, image: string, { run = runCommand, pauses = [2_000, 8_000], timeoutMs = 60 * 60_000, sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)) }: { run?: RunCommand; pauses?: number[]; timeoutMs?: number; sleep?: (ms: number) => Promise<unknown> } = {}): Promise<{ ok: true; attempts: number } | { ok: false; error: string }> {
+ let last = null;
+ for (let attempt = 0; attempt <= pauses.length; attempt += 1) {
+ last = await rt(runtime, run)(["pull", image], { timeoutMs });
+ if (last.code === 0) return { ok: true, attempts: attempt + 1 };
+ if (attempt < pauses.length) await sleep(pauses[attempt]!);
+ }
+ const said = String(last?.stderr || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) || `pull exited with ${last?.code}`;
+ return { ok: false, error: said.slice(0, 300) };
+}
+
+type ContainerInfo = { id: string; running: boolean; image: string; labels: Record<string, string>; env: string[]; mounts: string[] };
+
+async function inspectContainer(runtime: BoxRuntime, name: string, run: RunCommand): Promise<ContainerInfo | null> {
+ const res = await rt(runtime, run)(["container", "inspect", name, "--format", "{{json .}}"], { timeoutMs: 20_000 });
+ if (res.code !== 0) return null;
+ try {
+ const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");
+ return {
+ id: String(info.Id || ""),
+ running: Boolean(info.State?.Running),
+ image: String(info.Image || ""),
+ labels: info.Config?.Labels ?? {},
+ env: Array.isArray(info.Config?.Env) ? info.Config.Env : [],
+ mounts: Array.isArray(info.Mounts) ? info.Mounts.map((mount: { Destination?: unknown }) => String(mount.Destination ?? "")) : [],
+ };
+ } catch {
+ return null;
+ }
+}
+
+/** The host port boxd is published on. */
+async function publishedPort(runtime: BoxRuntime, name: string, run: RunCommand): Promise<number | null> {
+ const res = await rt(runtime, run)(["port", name, `${BOX_PORT}/tcp`], { timeoutMs: 15_000 });
+ if (res.code !== 0) return null;
+ for (const line of res.stdout.split("\n")) {
+ const match = /:(\d+)\s*$/.exec(line.trim());
+ if (match) return Number(match[1]);
+ }
+ return null;
+}
+
+/** Resource limits a new box gets (a VM runtime has its own; only the process cap then). */
+export function resourceArgs({ runtime, env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { runtime: BoxRuntime; env?: Env; cpus?: number; memory?: number }): string[] {
+ const args = ["--pids-limit", String(Number(env.OMNIRUSH_BOX_PIDS) || 4096)];
+ const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);
+ const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();
+ if (askedCpus > 0) args.push("--cpus", String(askedCpus));
+ else if (!runtime.vm) args.push("--cpus", String(Math.max(1, Math.min(8, cpus - 1))));
+ if (askedMem) args.push("--memory", askedMem);
+ else if (!runtime.vm) {
+ const gib = Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)));
+ args.push("--memory", `${gib}g`);
+ }
+ return args;
+}
+
+/** Who commands run as: root where root maps to the user (rootless, VMs), else the user's own uid. */
+export function commandUser(runtime: BoxRuntime, { platform = process.platform, uid = process.getuid?.(), gid = process.getgid?.() }: { platform?: NodeJS.Platform; uid?: number; gid?: number } = {}): { uid: number; gid: number } {
+ if (platform !== "linux" || runtime.rootless || runtime.vm || uid === undefined || gid === undefined || uid === 0) return { uid: 0, gid: 0 };
+ return { uid, gid };
+}
+
+/**
+ * Create a box container (not started): the project folder at `croot`, the
+ * launcher's run folder at /run/omnirush, the package-manager wrappers (when
+ * there are) read-only, boxd published on this machine's loopback only.
+ * Nothing else of this machine goes in: no home folder, no credentials, no
+ * docker socket.
+ */
+export function createArgs({ name, key, root, croot, image, runtime, run: runFolder, shims, pkglog = null, token, user, env = process.env, platform = process.platform }: { name: string; key: string; root: string; croot: string; image: string; runtime: BoxRuntime; run: string; shims: string | null; pkglog?: BoxInstallLog | null; token: string; user: { uid: number; gid: number }; env?: Env; platform?: NodeJS.Platform }): string[] {
+ return [
+ "create", "--name", name, "--hostname", "omnirush-box", "--init",
+ "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`,
+ "--mount", `type=bind,source=${source(runtime, root)},target=${croot}`,
+ "--mount", `type=bind,source=${source(runtime, runFolder)},target=${RUN_DIR}`,
+ ...(shims ? ["--mount", `type=bind,source=${source(runtime, shims)},target=${SHIMS_DIR}-src,readonly`] : []),
+ // The install log's folder (phase 1: its wrappers, pip hook and the per-run folders the
+ // wrappers note calls in), at the path the launcher reads it at.
+ ...(pkglog ? ["--mount", `type=bind,source=${source(runtime, pkglog.root)},target=${containerRoot(pkglog.root, platform)}`] : []),
+ "-p", `127.0.0.1::${BOX_PORT}`,
+ "-e", `BOXD_TOKEN=${token}`, "-e", `BOXD_UID=${user.uid}`, "-e", `BOXD_GID=${user.gid}`,
+ "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,
+ "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",
+ "-w", croot,
+ ...resourceArgs({ runtime, env }),
+ ...(runtime.name === "podman" ? ["--security-opt", "label=disable"] : []),
+ ...(user.uid === 0 ? ["--security-opt", "no-new-privileges"] : []),
+ "--entrypoint", "/opt/omnirush/bin/boxd",
+ image,
+ ];
+}
+
+/** "57.2MB (virtual 1.1GB)" -> bytes of the first number. */
+export function parseSize(text: unknown): number | null {
+ const match = /([\d.]+)\s*([kKMGT]?i?B)/.exec(String(text));
+ if (!match) return null;
+ const unit = match[2]!.replace(/i/, "").toUpperCase();
+ const mult = ({ B: 1, KB: 1e3, MB: 1e6, GB: 1e9, TB: 1e12 } satisfies Record<string, number>)[unit] ?? 1;
+ return Math.round(Number(match[1]) * mult);
+}
+
+// --- the driver ------------------------------------------------------------------
+
+/** Create (or start) the project's container; boxd answers on a published loopback port. */
+async function open(ctx: OpenContext): Promise<Opened> {
+ const { key, name, root, croot, runtime, run, runFolder, image, pull, shims, pkglog, env, platform, log, onPulling } = ctx;
+ let info = await inspectContainer(runtime, name, run);
+ if (info && info.labels?.[`${LABEL}.root`] && info.labels[`${LABEL}.root`] !== root) {
+ return { ok: false, error: `container ${name} belongs to another folder` };
+ }
+ let created = null;
+ if (!info) {
+ let present = await inspectImage(runtime, image.pull, { run });
+ if (!present) {
+ if (!pull) return { ok: false, error: "the sandbox image is not downloaded yet" };
+ onPulling();
+ const pulled = await pullImage(runtime, image.pull, { run });
+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };
+ present = await inspectImage(runtime, image.pull, { run });
+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };
+ }
+ const goarch = GOARCH[present.arch] || GOARCH[runtime.arch ?? ""] || "amd64";
+ const boxd = helperPath("boxd", { goos: "linux", goarch, env });
+ if (!boxd) return { ok: false, error: `the sandbox helper is missing (linux-${goarch}/boxd)` };
+ const user = commandUser(runtime, { platform });
+ const made = await rt(runtime, run)(createArgs({ name, key, root, croot, image: image.pull, runtime, run: runFolder, shims, pkglog, token: newToken(), user, env, platform }), { timeoutMs: 120_000 });
+ if (made.code !== 0) return { ok: false, error: `could not create the sandbox: ${firstLine(made.stderr)}` };
+ const copied = await rt(runtime, run)(["cp", "-", `${name}:/`], { timeoutMs: 60_000, input: singleFileTar("opt/omnirush/bin/boxd", readFileSync(boxd)) });
+ if (copied.code !== 0) {
+ await rt(runtime, run)(["rm", "-f", name], { timeoutMs: 30_000 });
+ return { ok: false, error: `could not copy the sandbox helper in: ${firstLine(copied.stderr)}` };
+ }
+ created = { ref: image.ref, pull: image.pull, digest: image.digest || present.digest, id: present.id, stack: image.stack };
+ info = await inspectContainer(runtime, name, run);
+ if (!info) return { ok: false, error: "the sandbox was not there after it was created" };
+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: runtime.backend ?? runtime.name });
+ }
+ if (!info.running) {
+ const started = await rt(runtime, run)(["start", name], { timeoutMs: 60_000 });
+ if (started.code !== 0) return { ok: false, error: `could not start the sandbox: ${firstLine(started.stderr)}` };
+ }
+ const env0 = info.env;
+ const envOf = (k: string, d = "") => (env0.find((kv) => kv.startsWith(`${k}=`)) || `${k}=${d}`).slice(k.length + 1);
+ const port = await publishedPort(runtime, name, run);
+ const token = envOf("BOXD_TOKEN");
+ if (!port || !token) return { ok: false, error: "the sandbox started without its port" };
+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token }, uid: Number(envOf("BOXD_UID", "0")), gid: Number(envOf("BOXD_GID", "0")), containerId: info.id, imageId: info.image, mounts: info.mounts };
+}
+
+/** Boxes on this machine: { key, name, root, running, image, created }[] */
+export async function listContainers(runtime: BoxRuntime, { run = runCommand }: { run?: RunCommand } = {}): Promise<ListedBox[]> {
+ const res = await rt(runtime, run)(["ps", "-a", "--filter", `label=${LABEL}=1`, "--format", "{{json .}}"], { timeoutMs: 30_000 });
+ if (res.code !== 0) return [];
+ const out: ListedBox[] = [];
+ for (const line of res.stdout.split("\n")) {
+ if (!line.trim()) continue;
+ try {
+ const row = JSON.parse(line);
+ const labels: Record<string, string> = typeof row.Labels === "string"
+ ? Object.fromEntries(row.Labels.split(",").map((kv: string) => { const i = kv.indexOf("="); return [kv.slice(0, i), kv.slice(i + 1)]; }))
+ : (row.Labels ?? {});
+ const name = Array.isArray(row.Names) ? row.Names[0] : String(row.Names ?? "");
+ out.push({ key: labels[`${LABEL}.key`] ?? "", name, root: labels[`${LABEL}.root`] ?? "", running: /^up|running/i.test(String(row.Status ?? row.State ?? "")), image: String(row.Image ?? ""), created: String(row.CreatedAt ?? row.Created ?? "") });
+ } catch { /* skip */ }
+ }
+ return out;
+}
+
+export const containerDriver: BoxDriver = {
+ kind: "container",
+ /** `docker exec` works when boxd is down (boxsh's fallback). */
+ execFallback: true,
+ async imagePresent(runtime, image, { run = runCommand } = {}) {
+ const found = await inspectImage(runtime, image.pull, { run });
+ return found ? { id: found.id, digest: found.digest, arch: found.arch } : null;
+ },
+ pull(runtime, image, { run = runCommand } = {}) {
+ return pullImage(runtime, image.pull, { run });
+ },
+ /** The detached download (the app keeps no handle on it). */
+ pullCommand(runtime, image) {
+ return { bin: runtime.bin, args: [...(runtime.prefix ?? []), "pull", image.pull] };
+ },
+ async exists(runtime, key, { run = runCommand, env = process.env, timeoutMs = 20_000 } = {}) {
+ const res = await rt(runtime, run)(["container", "inspect", containerName(key, env), "--format", "{{.Id}}"], { timeoutMs });
+ return res.code === 0;
+ },
+ open,
+ list: (runtime, { run = runCommand } = {}) => listContainers(runtime, { run }),
+ async remove(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await rt(runtime, run)(["rm", "-f", containerName(key, env)], { timeoutMs: 60_000 });
+ return { removed: res.code === 0 };
+ },
+ /** Box images that no box uses and that are not the current pins (`omnirush-ai/box-*` only; never a prune). */
+ async gcImages(runtime, { run = runCommand, current, used }) {
+ const removed = [];
+ const images = await rt(runtime, run)(["images", "--format", "{{.Repository}}:{{.Tag}} {{.ID}}"], { timeoutMs: 30_000 });
+ for (const line of images.stdout.split("\n")) {
+ const [ref, id] = line.trim().split(/\s+/);
+ if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref) || (id && used.has(id))) continue;
+ const res = await rt(runtime, run)(["rmi", ref], { timeoutMs: 60_000 });
+ if (res.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });
+ }
+ return removed;
+ },
+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await rt(runtime, run)(["stop", "-t", "1", containerName(key, env)], { timeoutMs: 60_000 });
+ return { stopped: res.code === 0 };
+ },
+ async upperBytes(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await rt(runtime, run)(["ps", "-a", "-s", "--filter", `name=^/?${containerName(key, env)}$`, "--format", "{{.Size}}"], { timeoutMs: 30_000 });
+ return parseSize(res.stdout);
+ },
+ diff(runtime, key, { run = runCommand, env = process.env } = {}) {
+ return rt(runtime, run)(["diff", containerName(key, env)], { timeoutMs: 120_000, maxBytes: 256 << 20 });
+ },
+ /** An interactive shell in the box. */
+ shellCommand(runtime, { key, croot, uid, gid, env = process.env }) {
+ const user = uid ? ["-u", `${uid}:${gid ?? uid}`] : [];
+ return { bin: runtime.bin, args: [...(runtime.prefix ?? []), "exec", "-it", ...user, "-e", `HOME=${HOME_IN_BOX}`, "-w", croot, containerName(key, env), "/bin/bash"] };
+ },
+ /** How to run a program in the box with stdin open (files-used reads). */
+ execCommand(runtime, { key, env = process.env }) {
+ return { bin: runtime.bin, args: [...(runtime.prefix ?? []), "exec", "-i", containerName(key, env)], env: {} };
+ },
+};
diff --git a/apps/server/src/box/backends/index.ts b/apps/server/src/box/backends/index.ts
new file mode 100644
index 00000000..8b56a7f3
--- /dev/null
+++ b/apps/server/src/box/backends/index.ts
@@ -0,0 +1,282 @@
+// Ported from the CLI (omnirush-cli src/box/backends/index.js,
+// feat/local-box-backends); keep the two in step. Desktop differences: types;
+// the "asked" reason names the desktop setting.
+//
+// Which backend runs this machine's boxes: the best one that works, in a
+// ranked order per OS, unless the user (the desktop setting,
+// OMNIRUSH_BOX_BACKEND) or the server (its allowlist) says otherwise. Every
+// backend gives the same thing: a persistent Linux box per project from the
+// same pinned image, boxd inside, per-turn snapshots in the same
+// `__sandbox__` format, so the converter and the rebuild do not change.
+//
+// Linux: bwrap (no daemon, no root) > rootless Podman > Docker
+// macOS: Apple container (macOS 26+) > OrbStack > colima > Docker Desktop > Rancher > Podman machine
+// Windows: WSL containers (wslc, WSL 3.0.1+) > OmniRush's WSL distro > Docker Desktop > Podman machine
+// > Docker in the default WSL distro
+//
+// Nothing found: the project runs on this machine with one line saying why
+// (never an install, never a wait).
+
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { runCommand, type RunCommand } from "../run.js";
+import { CACHE_FAIL_MS, CACHE_OK_MS, candidates, isWsl, probe as probeContainer, probeWsl, wslLauncher, type BackendAlternative, type DetectOptions, type RuntimeFailure, type RuntimeInfo, type RuntimeResult, type RuntimeTried } from "../runtime.js";
+import { appleDriver, probeApple } from "./apple.js";
+import { bwrapDriver, probeBwrap } from "./bwrap.js";
+import { containerDriver } from "./container.js";
+import type { BoxDriver } from "./types.js";
+import { probeWslDistro, wslDriver } from "./wsl.js";
+import { probeWslc, wslcDriver } from "./wslc.js";
+
+type Env = NodeJS.ProcessEnv;
+
+export const ORDER: Record<"linux" | "darwin" | "win32", string[]> = {
+ linux: ["bwrap", "podman", "docker"],
+ darwin: ["apple", "orbstack", "colima", "docker-desktop", "rancher", "podman", "docker"],
+ win32: ["wslc", "wsl", "docker-desktop", "podman", "docker", "wsl-engine"],
+};
+
+/** What the backend setting takes (and what uploads record as sandbox.backend). */
+export const BACKENDS = ["bwrap", "apple", "wslc", "wsl", "orbstack", "colima", "docker-desktop", "rancher", "docker", "podman", "wsl-engine"] as const;
+export type BackendId = (typeof BACKENDS)[number];
+export const LABELS: Record<string, string> = {
+ bwrap: "bubblewrap (no daemon)", apple: "Apple container", wslc: "WSL containers (wslc)", wsl: "OmniRush WSL distro", orbstack: "OrbStack", colima: "colima",
+ "docker-desktop": "Docker Desktop", rancher: "Rancher Desktop", docker: "Docker", podman: "Podman", "wsl-engine": "Docker/Podman in WSL",
+};
+
+/** The ranked backends of a platform (the setting's choices there). */
+export function backendsFor(platform: NodeJS.Platform = process.platform): string[] {
+ return platform === "darwin" ? ORDER.darwin : platform === "win32" ? ORDER.win32 : ORDER.linux;
+}
+
+/** The driver (image, open, list, remove, ...) for a detected runtime. */
+export function driverFor(runtime: { backend?: string } | null | undefined): BoxDriver {
+ switch (runtime?.backend) {
+ case "bwrap": return bwrapDriver;
+ case "apple": return appleDriver;
+ case "wsl": return wslDriver;
+ case "wslc": return wslcDriver;
+ default: return containerDriver;
+ }
+}
+
+/** The backend id of a probed container runtime (from what answered `info`). */
+export function containerBackendId(runtime: Pick<RuntimeInfo, "name" | "wsl" | "prefix" | "flavor">): string {
+ if (runtime.name === "podman") return "podman";
+ if (runtime.wsl && runtime.prefix?.[0] === "-e") return "wsl-engine";
+ switch (runtime.flavor) {
+ case "desktop": return "docker-desktop";
+ case "orbstack": return "orbstack";
+ case "colima": return "colima";
+ case "rancher": return "rancher";
+ default: return "docker";
+ }
+}
+
+/** The backend an OMNIRUSH_BOX_RUNTIME path names when it is not a Docker/Podman CLI. */
+export function runtimeBackend(value: unknown, platform: NodeJS.Platform = process.platform): string | null {
+ const base = String(value || "").split(/[\\/]/).pop()?.toLowerCase().replace(/\.exe$/, "") ?? "";
+ if (base === "wslc") return "wslc";
+ if (base === "container" && platform !== "win32") return "apple";
+ if (base === "boxrun" || base === "bwrap") return "bwrap";
+ const lower = String(value || "").toLowerCase();
+ if (["bwrap", "apple", "wslc", "wsl"].includes(lower)) return lower;
+ return null;
+}
+
+function isBackendId(value: string): value is BackendId {
+ return BACKENDS.some((id) => id === value);
+}
+
+/** The backend setting's value: a backend id, "auto", or "native" (no box). Aliases accepted; null: unknown. */
+export function normalizeBackend(value: unknown): BackendId | "auto" | "native" | null {
+ const v = String(value ?? "").trim().toLowerCase();
+ if (!v || v === "auto" || v === "default") return "auto";
+ const alias: Record<string, string> = { bubblewrap: "bwrap", "apple-container": "apple", container: "apple", "wsl-containers": "wslc", "wsl-container": "wslc", desktop: "docker-desktop", "docker desktop": "docker-desktop", "podman-machine": "podman", off: "native", none: "native", host: "native" };
+ const id = alias[v] ?? v;
+ if (id === "native") return "native";
+ return isBackendId(id) ? id : null;
+}
+
+/** Docker contexts (macOS, Windows): OrbStack, colima, Docker Desktop and Rancher each register one. */
+export async function dockerContexts(bin: string, { run = runCommand, env = process.env, timeoutMs = 5_000 }: { run?: RunCommand; env?: Env; timeoutMs?: number } = {}): Promise<Array<{ name: string; endpoint: string; current: boolean }>> {
+ const res = await run(bin, ["context", "ls", "--format", "{{json .}}"], { env, timeoutMs });
+ if (res.code !== 0) return [];
+ const out = [];
+ for (const line of String(res.stdout).split("\n")) {
+ try {
+ const row = JSON.parse(line);
+ if (row && typeof row.Name === "string" && row.Name) out.push({ name: row.Name, endpoint: String(row.DockerEndpoint ?? ""), current: Boolean(row.Current) });
+ } catch { /* skip */ }
+ }
+ return out;
+}
+
+type Probed = RuntimeResult & { backend: string };
+
+function contextBackendGuess(name: string): string {
+ if (/orbstack/i.test(name)) return "orbstack";
+ if (/colima/i.test(name)) return "colima";
+ if (/desktop/i.test(name)) return "docker-desktop";
+ if (/rancher/i.test(name)) return "rancher";
+ return "docker";
+}
+
+/** Every container runtime here, probed, each with its backend id. */
+export async function probeContainers({ platform, env, home, exists, run, wsl, timeoutMs }: { platform: NodeJS.Platform; env: Env; home: string; exists: (file: string) => boolean; run: RunCommand; wsl: boolean; timeoutMs?: number | undefined }): Promise<Probed[]> {
+ const out: Probed[] = [];
+ const seen = new Set<string>();
+ const limit = timeoutMs ? { timeoutMs } : {};
+ for (const candidate of candidates({ platform, home, env, exists, wsl })) {
+ // /bin/docker and /usr/bin/docker are one program on merged-/usr systems.
+ let real = candidate.bin;
+ try { real = realpathSync(candidate.bin); } catch { /* keep */ }
+ if (seen.has(real)) continue;
+ seen.add(real);
+ if (candidate.name === "docker" && platform !== "linux" && !env.DOCKER_HOST && !env.DOCKER_CONTEXT && !candidate.skipped) {
+ const contexts = await dockerContexts(candidate.bin, { run, env });
+ const named = contexts.filter((c) => c.name !== "default");
+ if (named.length) {
+ for (const ctx of [...named, ...contexts.filter((c) => c.name === "default")]) {
+ const prefix = ["--context", ctx.name];
+ const probed = await probeContainer({ ...candidate, prefix }, { run, env, platform, wsl, ...limit });
+ out.push(probed.ok
+ ? { ...probed, prefix, context: ctx.name, backend: containerBackendId(probed) }
+ : { ...probed, context: ctx.name, backend: contextBackendGuess(ctx.name) });
+ }
+ continue;
+ }
+ }
+ const probed = await probeContainer(candidate, { run, env, platform, wsl, ...limit });
+ out.push({ ...probed, backend: probed.ok ? containerBackendId(probed) : candidate.name });
+ }
+ return out;
+}
+
+function cacheFile(boxHome: string): string {
+ return path.join(boxHome, "runtime.json");
+}
+
+function readCache(boxHome: string, now: number, key: string): RuntimeResult | null {
+ try {
+ const cached = JSON.parse(readFileSync(cacheFile(boxHome), "utf8"));
+ if (cached?.key !== key) return null;
+ const age = now - Number(cached.at);
+ if (!(age >= 0)) return null;
+ if (cached.result?.ok ? age < CACHE_OK_MS : age < CACHE_FAIL_MS) return cached.result;
+ } catch { /* none */ }
+ return null;
+}
+
+function writeCache(boxHome: string, key: string, result: RuntimeResult, now: number): void {
+ try {
+ mkdirSync(boxHome, { recursive: true });
+ const file = cacheFile(boxHome);
+ const tmp = `${file}.${process.pid}.tmp`;
+ writeFileSync(tmp, JSON.stringify({ key, at: now, result }), { mode: 0o600 });
+ renameSync(tmp, file);
+ } catch { /* best effort */ }
+}
+
+/** One line when nothing works, with the free option to install. */
+export function noneReason(platform: NodeJS.Platform): string {
+ if (platform === "linux") return "no sandbox backend works here (install bubblewrap, Podman or Docker)";
+ if (platform === "darwin") return "no container runtime found (free: `brew install colima docker && colima start`; also Apple container on macOS 26, OrbStack, Docker Desktop, Podman)";
+ return "no sandbox backend found (turn on WSL 2: `wsl --install --no-distribution` as administrator, then `wsl --update` for WSL containers; or Docker Desktop, Podman)";
+}
+
+function alternative(r: Probed | { backend: string; name: string; ok: false; reason: string }): BackendAlternative {
+ const version = "version" in r && typeof r.version === "string" ? r.version : null;
+ const flavor = r.ok ? r.flavor : null;
+ const reason = r.ok ? null : r.reason;
+ const context = "context" in r && typeof r.context === "string" ? r.context : undefined;
+ return { backend: r.backend, name: r.name ?? r.backend, ok: r.ok, version, flavor, reason, ...(context ? { context } : {}) };
+}
+
+/**
+ * The backend for boxes on this machine (cached; `fresh` skips the cache;
+ * `all` probes every backend and lists them as `alternatives`, for the
+ * status). Returns the runtime ({ ok: true, backend, name, bin, version,
+ * flavor, ..., why }) or { ok: false, reason, tried }. `asked`: a backend id
+ * or "auto" (the setting); `allow`: the server's allowlist (null: any).
+ */
+export async function detectBackend({ boxHome, env = process.env, platform = process.platform, home = os.homedir(), exists = existsSync, run = runCommand, wsl = platform === "linux" && isWsl(env), now = Date.now(), fresh = false, all = false, timeoutMs, asked = env.OMNIRUSH_BOX_BACKEND, allow = null, arch = process.arch, release = os.release() }: DetectOptions = {}): Promise<RuntimeResult> {
+ let wanted = normalizeBackend(asked);
+ let legacyRuntime = String(env.OMNIRUSH_BOX_RUNTIME || "").trim();
+ // OMNIRUSH_BOX_RUNTIME naming a backend's own program picks that backend (the host kits do).
+ const named = runtimeBackend(legacyRuntime, platform);
+ if (named && wanted === "auto") { wanted = normalizeBackend(named); legacyRuntime = ""; }
+ const allowList = Array.isArray(allow) ? allow.map(normalizeBackend).filter((id): id is BackendId | "auto" | "native" => Boolean(id)) : null;
+ const key = JSON.stringify([2, platform, wanted, allowList, legacyRuntime, env.DOCKER_HOST || "", env.PATH || env.Path || "", env.OMNIRUSH_BOX_BWRAP || ""]);
+ if (boxHome && !fresh && !all) {
+ const cached = readCache(boxHome, now, key);
+ if (cached) return { ...cached, cached: true };
+ }
+ if (wanted === null) return { ok: false, reason: `unknown sandbox backend "${asked}" (one of: auto, ${BACKENDS.join(", ")}, native)`, tried: [] };
+ if (wanted === "native") return { ok: false, reason: "the sandbox backend is set to native (this machine)", tried: [], native: true };
+ let order: string[] = backendsFor(platform);
+ // OMNIRUSH_BOX_RUNTIME (docker, podman or a path) keeps meaning "this container CLI".
+ if (legacyRuntime) order = order.filter((id) => !["bwrap", "apple", "wslc", "wsl", "wsl-engine"].includes(id));
+ let why = `the first that works here, in order: ${order.join(" > ")}`;
+ if (wanted !== "auto") {
+ order = [wanted];
+ why = "chosen in Settings (sandbox backend)";
+ }
+ const skipped: Array<{ backend: string; name: string; ok: false; reason: string }> = [];
+ if (allowList) {
+ for (const id of order) if (!allowList.some((allowed) => allowed === id)) skipped.push({ backend: id, name: id, ok: false, reason: "not allowed by the server" });
+ order = order.filter((id) => allowList.some((allowed) => allowed === id));
+ why += `; the server allows ${allowList.join(", ")}`;
+ }
+ const limit = timeoutMs ? { timeoutMs } : {};
+ let containers: Probed[] | null = null;
+ const containerList = async () => (containers ??= await probeContainers({ platform, env, home, exists, run, wsl, timeoutMs }));
+ const results: Array<Probed | { backend: string; name: string; ok: false; reason: string }> = [];
+ let chosen: (RuntimeInfo & { backend: string }) | null = null;
+ for (const id of order) {
+ let found: Probed[];
+ if (id === "bwrap") found = [{ backend: "bwrap", ...(await probeBwrap({ env, boxHome: boxHome ?? path.join(home, ".omnirush", "box"), run, exists, platform, arch, ...limit })) }];
+ else if (id === "apple") found = [{ backend: "apple", ...(await probeApple({ env, platform, arch, release, run, exists, ...limit })) }];
+ else if (id === "wsl") found = [{ backend: "wsl", ...(await probeWslDistro({ env, platform, run, exists, arch, ...limit })) }];
+ else if (id === "wslc") found = [{ backend: "wslc", ...(await probeWslc({ env, platform, run, exists, arch, ...limit })) }];
+ else if (id === "wsl-engine") {
+ if (platform !== "win32" || env.OMNIRUSH_BOX_WSL === "0") continue;
+ const bin = wslLauncher({ env, exists });
+ if (!bin) continue;
+ const probed = await probeWsl(bin, { run, env, ...limit });
+ found = [{ ...probed, backend: "wsl-engine" }];
+ } else {
+ const list = await containerList();
+ found = list.filter((r) => r.backend === id || (wanted === id && id === "docker" && r.name === "docker"));
+ // A runtime that failed before its flavor was known (a stopped colima) shows up once, under its guess.
+ if (!found.length) {
+ if (all) results.push({ backend: id, name: id, ok: false, reason: "not found" });
+ continue;
+ }
+ }
+ for (const result of found) {
+ results.push(result);
+ if (result.ok && !chosen) chosen = result;
+ }
+ if (chosen && !all) break;
+ }
+ if (all && containers === null) await containerList();
+ const probedContainers: Probed[] = containers ?? [];
+ if (all) for (const r of probedContainers) if (!results.some((x) => "bin" in x && x.bin === r.bin && ("context" in x ? x.context : undefined) === r.context && x.name === r.name)) results.push(r);
+ const failed = [...skipped, ...results.filter((r) => !r.ok)];
+ const tried: RuntimeTried[] = failed.map((r) => ({ backend: r.backend, ...(r.name ? { name: r.name } : {}), ...("bin" in r && r.bin ? { bin: r.bin } : {}), reason: r.ok ? "" : r.reason }));
+ let result: RuntimeResult;
+ if (chosen) {
+ result = { ...chosen, why };
+ } else {
+ const reasons = tried.filter((t) => t.reason).map((t) => `${t.backend}: ${t.reason}`);
+ const failure: RuntimeFailure = { ok: false, reason: reasons.length ? reasons.join("; ") : noneReason(platform), tried };
+ if (platform === "darwin" && !results.some((r) => r.ok)) failure.hint = "colima";
+ result = failure;
+ }
+ if (all) result.alternatives = [...skipped, ...results].map(alternative);
+ if (boxHome && !all) writeCache(boxHome, key, result, now);
+ return result;
+}
diff --git a/apps/server/src/box/backends/shared.ts b/apps/server/src/box/backends/shared.ts
new file mode 100644
index 00000000..5d58b0fb
--- /dev/null
+++ b/apps/server/src/box/backends/shared.ts
@@ -0,0 +1,54 @@
+// Ported from the CLI (omnirush-cli src/box/backends/shared.js,
+// feat/local-box-backends); keep the two in step. Desktop: the shell link is
+// in <home>/shell-desktop (common.ts shellDir).
+//
+// What every backend without a container CLI shares.
+
+import path from "node:path";
+
+import { shellDir } from "../common.js";
+import type { BoxExec } from "./types.js";
+
+/**
+ * Run a program in the box with stdin open (the files-used reader) through
+ * boxsh, the engine's shell: `bash -c 'exec "$0" "$@"' prog args...`.
+ */
+export function boxshExec({ key, home, platform = process.platform }: { key: string; home: string; platform?: NodeJS.Platform }): BoxExec {
+ return {
+ bin: path.join(shellDir(home), platform === "win32" ? "bash.exe" : "bash"),
+ args: ["-c", 'exec "$0" "$@"'],
+ env: { OMNIRUSH_BOX_KEY: key, OMNIRUSH_BOX_HOME: home },
+ };
+}
+
+/** "1.4.1" >= "1.0.0"; non-numeric parts count as 0. */
+export function versionAtLeast(version: unknown, min: string): boolean {
+ const a = String(version).split(/[.+-]/).map((x) => Number.parseInt(x, 10) || 0);
+ const b = String(min).split(".").map((x) => Number.parseInt(x, 10) || 0);
+ for (let i = 0; i < Math.max(a.length, b.length); i += 1) {
+ if ((a[i] ?? 0) !== (b[i] ?? 0)) return (a[i] ?? 0) > (b[i] ?? 0);
+ }
+ return true;
+}
+
+/** The last JSON object a helper printed (boxrun prints one line per answer). */
+export function parseOut(stdout: unknown): Record<string, unknown> | null {
+ const lines = String(stdout ?? "").split("\n").map((line) => line.trim()).filter((line) => line.startsWith("{"));
+ for (let i = lines.length - 1; i >= 0; i -= 1) {
+ try {
+ const value: unknown = JSON.parse(lines[i]!);
+ if (value && typeof value === "object" && !Array.isArray(value)) return Object.fromEntries(Object.entries(value));
+ } catch { /* next */ }
+ }
+ return null;
+}
+
+/** A field of a helper's answer as a string ("" when absent). */
+export function str(value: unknown): string {
+ return typeof value === "string" ? value : value === undefined || value === null ? "" : String(value);
+}
+
+/** A field of a helper's answer as a number (null when not one). */
+export function num(value: unknown): number | null {
+ return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
diff --git a/apps/server/src/box/backends/types.ts b/apps/server/src/box/backends/types.ts
new file mode 100644
index 00000000..45c17c25
--- /dev/null
+++ b/apps/server/src/box/backends/types.ts
@@ -0,0 +1,81 @@
+// The shape every box backend's driver has (the CLI's drivers are plain
+// objects of the same functions: src/box/backends/*.js).
+
+import type { ChildProcess, SpawnOptions } from "node:child_process";
+
+import type { BoxEndpoint } from "../client.js";
+import type { BoxInstallLog, BoxLog, BoxRuntime } from "../common.js";
+import type { BoxImage } from "../images.js";
+import type { RunCommand, RunResult } from "../run.js";
+
+type Env = NodeJS.ProcessEnv;
+
+export type SpawnLike = (command: string, args: string[], options: SpawnOptions) => ChildProcess;
+
+/** How to run a program in the box with stdin open (files-used reads) when it is not `docker exec`. */
+export type BoxExec = { bin: string; args: string[]; env?: Record<string, string> };
+
+export type CreatedImage = { ref: string; pull: string; digest: string | null; id: string; stack: string };
+
+export type OpenContext = {
+ key: string;
+ name: string;
+ root: string;
+ croot: string;
+ runtime: BoxRuntime;
+ run: RunCommand;
+ home: string;
+ runFolder: string;
+ image: BoxImage;
+ pull: boolean;
+ shims: string | null;
+ pkglog: BoxInstallLog | null;
+ env: Env;
+ platform: NodeJS.Platform;
+ log: BoxLog;
+ onPulling: () => void;
+ spawnImpl?: SpawnLike;
+};
+
+export type Opened =
+ | {
+ ok: true;
+ created: CreatedImage | null;
+ endpoint: BoxEndpoint;
+ /** Other ways to boxd, tried in turn when the first does not answer (Apple: the container's own address). */
+ alternates?: BoxEndpoint[];
+ uid: number;
+ gid: number;
+ containerId: string;
+ imageId: string;
+ mounts: string[];
+ timing?: { ms?: number; reused: boolean };
+ }
+ | { ok: false; error: string };
+
+export type PresentImage = { id: string; digest: string | null; arch: string; config?: string };
+export type ListedBox = { key: string; name: string; root: string; running: boolean; image: string; created: string };
+export type Removed = { kind: string; name: string; reason: string };
+export type DriverOptions = { run?: RunCommand; env?: Env; home?: string; timeoutMs?: number; log?: BoxLog };
+
+export type BoxDriver = {
+ kind: "container" | "bwrap" | "apple" | "wsl" | "wslc";
+ /** boxsh may fall back to `<runtime> exec` when boxd does not answer (container engines and wslc). */
+ execFallback: boolean;
+ imagePresent: (runtime: BoxRuntime, image: BoxImage, opts?: DriverOptions) => Promise<PresentImage | null>;
+ pull: (runtime: BoxRuntime, image: BoxImage, opts?: DriverOptions) => Promise<{ ok: true } | { ok: false; error: string }>;
+ /** The detached download; null: the download runs in this process (Desktop: the WSL distro). */
+ pullCommand: (runtime: BoxRuntime, image: BoxImage, home: string) => { bin: string; args: string[] } | null;
+ exists: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<boolean>;
+ open: (ctx: OpenContext) => Promise<Opened>;
+ list: (runtime: BoxRuntime, opts?: DriverOptions) => Promise<ListedBox[]>;
+ remove: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<{ removed: boolean }>;
+ stop: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<{ stopped: boolean }>;
+ gcImages: (runtime: BoxRuntime, opts: DriverOptions & { current: Set<string>; used: Set<string> }) => Promise<Removed[]>;
+ upperBytes: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<number | null>;
+ /** `<runtime> diff` (container engines only): the snapshot fallback when boxd cannot walk. */
+ diff?: (runtime: BoxRuntime, key: string, opts?: DriverOptions) => Promise<RunResult>;
+ /** An interactive shell in the box. */
+ shellCommand: (runtime: BoxRuntime, opts: { key: string; croot: string; home: string; uid?: number; gid?: number; env?: Env }) => { bin: string; args: string[] };
+ execCommand: (runtime: BoxRuntime, opts: { key: string; home: string; env?: Env }) => BoxExec;
+};
diff --git a/apps/server/src/box/backends/wsl.ts b/apps/server/src/box/backends/wsl.ts
new file mode 100644
index 00000000..7d0f012c
--- /dev/null
+++ b/apps/server/src/box/backends/wsl.ts
@@ -0,0 +1,425 @@
+// Ported from the CLI (omnirush-cli src/box/backends/wsl.js + wsl.json,
+// feat/local-box-backends); keep the two in step. Desktop differences: types;
+// wsl.json is a copy of the CLI's; the download (the distro, the helpers,
+// the image) runs in the app's own process (pullCommand null: there is no
+// `omnirush sandbox pull` to start detached).
+//
+// Windows: OmniRush's own WSL 2 distro as the box backend, so no Docker
+// Desktop is needed. The distro ("OmniRushBox") is a small pinned root
+// filesystem built FROM the same Debian base as the box images, with boxrun
+// and boxd in /opt/omnirush and a wsl.conf that keeps Windows out (no
+// Windows PATH, no interop: the 2.2.x "npm is the Windows npm" failure). It
+// is imported per user with `wsl --import` (no admin once WSL is on). Each
+// project's box runs inside it exactly like the Linux bubblewrap backend
+// (boxrun, as root in the distro: unshare + overlay), from the same pinned
+// images, so a Windows box is the same environment as a Linux one.
+//
+// The distro stays up while the app runs: a `wsl.exe ... boxrun up
+// --foreground` keeper is this process's child (its stdin open). boxd
+// listens on the distro's loopback; WSL forwards it to Windows' 127.0.0.1
+// (NAT mode's localhost forwarding, or mirrored networking). With
+// OMNIRUSH_BOX_WSL_LISTEN=any it listens on every address and the distro's
+// own address is the second way in.
+//
+// WSL that is not enabled is never installed from here (`wsl --install`
+// needs admin and a restart): one line gives the command, and the project
+// runs on this machine meanwhile.
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { createHash } from "node:crypto";
+import { createReadStream, createWriteStream, existsSync, mkdirSync, readdirSync, renameSync, rmSync, statSync } from "node:fs";
+import https from "node:https";
+import path from "node:path";
+
+import { GOARCH, containerName, containerRoot, firstLine, helperPath, readJson, writeJson, wslPath, type BoxLog, type BoxRuntime } from "../common.js";
+import { runCommand, type RunCommand, type RunResult } from "../run.js";
+import type { RuntimeResult } from "../runtime.js";
+import bundledPins from "../wsl.json" with { type: "json" };
+import { IDLE_MINUTES, newMeta, upArgs, type BoxMeta } from "./bwrap.js";
+import { boxshExec, num, parseOut, str } from "./shared.js";
+import type { BoxDriver, OpenContext, Opened, PresentImage, SpawnLike } from "./types.js";
+
+type Env = NodeJS.ProcessEnv;
+type WslRuntime = Pick<BoxRuntime, "bin" | "distro" | "arch" | "installed">;
+
+export const DEFAULT_DISTRO = "OmniRushBox";
+export const STORE = "/var/lib/omnirush/store";
+export const BOXES = "/var/lib/omnirush/boxes";
+export const ENABLE_HINT = "WSL 2 is not enabled on this Windows. One time, in an administrator terminal: `wsl --install --no-distribution`, then restart Windows";
+
+export type WslAsset = { url: string | null; sha256: string | null; bytes?: number | null };
+export type WslPins = { version?: string; distro?: string; base?: string; assets?: Record<string, WslAsset | undefined> };
+
+export function loadWslPins(): WslPins {
+ return bundledPins;
+}
+
+export function distroName(env: Env = process.env): string {
+ return String(env.OMNIRUSH_BOX_WSL_DISTRO || "").trim() || DEFAULT_DISTRO;
+}
+
+/** wsl.exe, when Windows has it (System32). */
+export function wslExe({ env = process.env, exists = existsSync }: { env?: Env; exists?: (file: string) => boolean } = {}): string | null {
+ const root = env.SystemRoot || env.SYSTEMROOT || "C:\\Windows";
+ const file = path.win32.join(root, "System32", "wsl.exe");
+ return exists(file) ? file : null;
+}
+
+/**
+ * wsl.exe's own output is UTF-16LE (with a BOM sometimes) unless WSL_UTF8=1
+ * is honoured; read either way.
+ */
+export function decodeWsl(data: unknown): string {
+ let text: string;
+ if (Buffer.isBuffer(data)) {
+ const nuls = data.subarray(0, 200).filter((b) => b === 0).length;
+ const utf16 = nuls > 0 && nuls >= Math.min(data.length, 200) / 4;
+ text = utf16 ? data.toString("utf16le") : data.toString("utf8");
+ } else {
+ text = String(data ?? "");
+ }
+ return text.replace(/^\uFEFF/, "").replace(/\uFEFF/g, "").replace(/\u0000/g, "").replace(/\r/g, "");
+}
+
+export type WslRow = { name: string; state: string; version: string; isDefault: boolean };
+
+/** `wsl --list --verbose`: [{ name, state, version, isDefault }] (the header line is skipped). */
+export function parseWslList(text: unknown): WslRow[] {
+ const rows: WslRow[] = [];
+ for (const raw of decodeWsl(text).split("\n")) {
+ const line = raw.trimEnd();
+ if (!line.trim() || /^\s*\*?\s*NAME\s+STATE\s+VERSION/i.test(line)) continue;
+ const isDefault = /^\s*\*/.test(line);
+ const parts = line.replace(/^\s*\*?\s*/, "").split(/\s{2,}|\t+/).map((p) => p.trim()).filter(Boolean);
+ if (parts.length < 3 || !/^[12]$/.test(parts[parts.length - 1]!)) continue;
+ rows.push({ name: parts.slice(0, parts.length - 2).join(" "), state: parts[parts.length - 2]!, version: parts[parts.length - 1]!, isDefault });
+ }
+ return rows;
+}
+
+const NOT_ENABLED = /not installed|is not enabled|optional component|virtual machine platform|HCS_E_HYPERV_NOT_INSTALLED|WSL_E_WSL_OPTIONAL_COMPONENT_REQUIRED|0x8007019e|0x80370102|wsl\.exe --install|enable the .*feature/i;
+const NO_DISTROS = /no installed distributions|WSL_E_DEFAULT_DISTRO_NOT_FOUND|has no installed distributions/i;
+
+/** Run wsl.exe; its output decoded (UTF-16 or UTF-8). */
+export async function wslCall(bin: string, args: string[], { run = runCommand, env = process.env, timeoutMs = 20_000, input }: { run?: RunCommand; env?: Env; timeoutMs?: number; input?: string | Buffer } = {}): Promise<RunResult> {
+ const res = await run(bin, args, { env: { ...env, WSL_UTF8: "1" }, timeoutMs, ...(input !== undefined ? { input } : {}) });
+ return { ...res, stdout: decodeWsl(res.stdout), stderr: decodeWsl(res.stderr) };
+}
+
+/** A command inside the distro, as root, no shell in between. */
+export function inDistro(runtime: Pick<BoxRuntime, "distro">, argv: string[]): string[] {
+ return ["-d", runtime.distro ?? DEFAULT_DISTRO, "-u", "root", "--cd", "/", "--exec", ...argv];
+}
+
+function assetFor(pins: WslPins | null, arch: string): WslAsset | null {
+ const asset = pins?.assets?.[GOARCH[arch] || "amd64"];
+ return asset?.url && /^[0-9a-f]{64}$/.test(String(asset.sha256 || "")) ? asset : null;
+}
+
+export async function probeWslDistro({ env = process.env, platform = process.platform, run = runCommand, exists = existsSync, timeoutMs = 15_000, arch = process.arch }: { env?: Env; platform?: NodeJS.Platform; run?: RunCommand; exists?: (file: string) => boolean; timeoutMs?: number; arch?: string } = {}): Promise<RuntimeResult> {
+ const base = { name: "wsl", backend: "wsl" };
+ if (platform !== "win32") return { ...base, ok: false, reason: "the OmniRush WSL distro is for Windows" };
+ if (env.OMNIRUSH_BOX_WSL === "0") return { ...base, ok: false, reason: "turned off (OMNIRUSH_BOX_WSL=0)" };
+ const bin = wslExe({ env, exists });
+ if (!bin) return { ...base, ok: false, reason: ENABLE_HINT };
+ const status = await wslCall(bin, ["--status"], { run, env, timeoutMs });
+ const said = `${status.stdout}\n${status.stderr}`;
+ if (NOT_ENABLED.test(said) || (status.code !== 0 && !NO_DISTROS.test(said))) {
+ return { ...base, ok: false, bin, reason: NOT_ENABLED.test(said) || status.error === "ENOENT" ? ENABLE_HINT : `\`wsl --status\` failed: ${firstLine(said) || status.code}` };
+ }
+ if (/default version:\s*1\b/i.test(said) && /wsl 2 is not supported|requires an update/i.test(said)) {
+ return { ...base, ok: false, bin, reason: ENABLE_HINT };
+ }
+ const listed = await wslCall(bin, ["--list", "--verbose"], { run, env, timeoutMs });
+ const rows = listed.code === 0 ? parseWslList(listed.stdout) : [];
+ const distro = distroName(env);
+ const mine = rows.find((row) => row.name.toLowerCase() === distro.toLowerCase());
+ if (mine && mine.version === "1") return { ...base, ok: false, bin, reason: `the ${distro} distro runs as WSL 1 (\`wsl --set-version ${distro} 2\`)` };
+ if (!mine && !String(env.OMNIRUSH_BOX_WSL_ROOTFS || "").trim() && !assetFor(loadWslPins(), arch)) {
+ return { ...base, ok: false, bin, reason: "the OmniRush WSL image is not published yet (OMNIRUSH_BOX_WSL_ROOTFS=<built tar> to use one)" };
+ }
+ const ver = await wslCall(bin, ["--version"], { run, env, timeoutMs });
+ const version = (/(\d+\.\d+\.\d+(?:\.\d+)?)/.exec(ver.code === 0 ? ver.stdout : "") ?? [])[1] ?? "";
+ return { ...base, ok: true, bin, distro, installed: Boolean(mine), state: mine?.state ?? null, version, flavor: "omnirush-distro", os: "linux", arch: GOARCH[arch] || "amd64", rootless: false, vm: true };
+}
+
+// --- the distro ----------------------------------------------------------------------
+
+/** Where the distro's disk lives (per user, no admin). */
+export function installDir(env: Env = process.env, distro = DEFAULT_DISTRO): string {
+ const local = env.LOCALAPPDATA || path.win32.join(env.USERPROFILE || "C:\\Users\\Default", "AppData", "Local");
+ return path.win32.join(local, "OmniRush", "wsl", distro);
+}
+
+/** sha256 of a file. */
+export function sha256File(file: string): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const hash = createHash("sha256");
+ createReadStream(file).on("error", reject).on("data", (chunk) => hash.update(chunk)).on("end", () => resolve(hash.digest("hex")));
+ });
+}
+
+/** Download over https (redirects followed) to `dest`, checked against `sha256`. */
+export async function download(url: string, dest: string, sha256: string | null, { maxRedirects = 5 }: { maxRedirects?: number } = {}): Promise<string> {
+ mkdirSync(path.dirname(dest), { recursive: true });
+ const tmp = `${dest}.${process.pid}.part`;
+ await new Promise<void>((resolve, reject) => {
+ const fetch = (u: string, left: number) => {
+ https.get(u, { headers: { "user-agent": "omnirush" } }, (res) => {
+ if ([301, 302, 303, 307, 308].includes(res.statusCode ?? 0) && res.headers.location && left > 0) {
+ res.resume();
+ fetch(new URL(res.headers.location, u).toString(), left - 1);
+ return;
+ }
+ if (res.statusCode !== 200) { res.resume(); reject(new Error(`download: HTTP ${res.statusCode}`)); return; }
+ const out = createWriteStream(tmp);
+ res.pipe(out);
+ out.on("finish", () => resolve());
+ out.on("error", reject);
+ res.on("error", reject);
+ }).on("error", reject);
+ };
+ if (!/^https:\/\//.test(url)) { reject(new Error("download: https only")); return; }
+ fetch(url, maxRedirects);
+ });
+ const got = await sha256File(tmp);
+ if (sha256 && got !== sha256) { rmSync(tmp, { force: true }); throw new Error(`download: sha256 mismatch (${got.slice(0, 12)}…)`); }
+ renameSync(tmp, dest);
+ return dest;
+}
+
+/** The pinned root filesystem tarball: OMNIRUSH_BOX_WSL_ROOTFS (a local file), else the pinned release asset. */
+export async function rootfsTarball({ env = process.env, home, arch = process.arch, pins = loadWslPins(), fetchFile = download }: { env?: Env; home: string; arch?: string; pins?: WslPins; fetchFile?: typeof download }): Promise<string> {
+ const asked = String(env.OMNIRUSH_BOX_WSL_ROOTFS || "").trim();
+ if (asked) {
+ if (!existsSync(asked)) throw new Error(`OMNIRUSH_BOX_WSL_ROOTFS: ${asked} is missing`);
+ return asked;
+ }
+ const asset = assetFor(pins, arch);
+ if (!asset?.url || !asset.sha256) throw new Error("the OmniRush WSL image is not published yet (set OMNIRUSH_BOX_WSL_ROOTFS to a built one)");
+ const dest = path.join(home, "wsl", "cache", `${asset.sha256}.tar.gz`);
+ if (existsSync(dest) && (await sha256File(dest)) === asset.sha256) return dest;
+ return fetchFile(asset.url, dest, asset.sha256);
+}
+
+/** Import the distro when it is not there yet (`wsl --import <name> <dir> <tar> --version 2`). */
+export async function ensureDistro(runtime: WslRuntime, { env = process.env, home, run = runCommand, log = () => {}, tarball = rootfsTarball }: { env?: Env; home: string; run?: RunCommand; log?: BoxLog; tarball?: typeof rootfsTarball }): Promise<{ ok: true; imported: boolean } | { ok: false; error: string }> {
+ const distro = runtime.distro ?? DEFAULT_DISTRO;
+ const listed = await wslCall(runtime.bin, ["--list", "--verbose"], { run, env });
+ if (parseWslList(listed.stdout).some((row) => row.name.toLowerCase() === distro.toLowerCase())) return { ok: true, imported: false };
+ let tar;
+ try { tar = await tarball({ env, home }); } catch (error) { return { ok: false, error: error instanceof Error ? error.message : String(error) }; }
+ const dir = installDir(env, distro);
+ mkdirSync(dir, { recursive: true });
+ const res = await wslCall(runtime.bin, ["--import", distro, dir, tar, "--version", "2"], { run, env, timeoutMs: 20 * 60_000 });
+ if (res.code !== 0) return { ok: false, error: `wsl --import failed: ${firstLine(res.stderr) || firstLine(res.stdout) || res.code}` };
+ log("info", "box wsl distro imported", { distro });
+ return { ok: true, imported: true };
+}
+
+/** A stamp of the helpers this install ships (copied into the distro when it changes). */
+function helperStamp(files: string[]): string {
+ return files.map((f) => { try { const s = statSync(f); return `${s.size}-${Math.floor(s.mtimeMs)}`; } catch { return "0"; } }).join("_");
+}
+
+/** Copy boxrun and boxd into /opt/omnirush when this install's differ (cheap: one stamp file). */
+export async function syncHelpers(runtime: WslRuntime, { env = process.env, run = runCommand }: { env?: Env; run?: RunCommand } = {}): Promise<{ ok: true } | { ok: false; error: string }> {
+ const goarch = runtime.arch || "amd64";
+ const boxrun = helperPath("boxrun", { goos: "linux", goarch, env });
+ const boxd = helperPath("boxd", { goos: "linux", goarch, env });
+ if (!boxrun || !boxd) return { ok: false, error: "the sandbox helpers (linux boxrun, boxd) are missing from this install" };
+ const stamp = helperStamp([boxrun, boxd]);
+ const script = 'set -e; [ "$(cat /opt/omnirush/helpers.stamp 2>/dev/null)" = "$3" ] && exit 0; mkdir -p /opt/omnirush; install -m 0755 "$1" /opt/omnirush/boxrun.new; install -m 0755 "$2" /opt/omnirush/boxd.new; mv /opt/omnirush/boxrun.new /opt/omnirush/boxrun; mv /opt/omnirush/boxd.new /opt/omnirush/boxd; echo "$3" > /opt/omnirush/helpers.stamp';
+ const res = await wslCall(runtime.bin, inDistro(runtime, ["/bin/sh", "-c", script, "sh", wslPath(boxrun), wslPath(boxd), stamp]), { run, env, timeoutMs: 120_000 });
+ return res.code === 0 ? { ok: true } : { ok: false, error: `could not update the helpers in WSL: ${firstLine(res.stderr) || res.code}` };
+}
+
+async function boxrun(runtime: WslRuntime, args: string[], { run = runCommand, env = process.env, timeoutMs = 60_000 }: { run?: RunCommand; env?: Env; timeoutMs?: number } = {}) {
+ const res = await wslCall(runtime.bin, inDistro(runtime, ["/opt/omnirush/boxrun", ...args]), { run, env, timeoutMs });
+ return { res, out: parseOut(res.stdout) };
+}
+
+const metaFile = (home: string, key: string) => path.join(home, "wsl", "boxes", `${key}.json`);
+
+/** An image reference as boxrun in the distro reads it: a local archive's Windows path through /mnt. */
+export function distroRef(ref: string): string {
+ const m = /^(docker-archive|oci-archive):(.+)$/.exec(String(ref));
+ return m ? `${m[1]}:${wslPath(m[2]!)}` : String(ref);
+}
+const boxPath = (key: string) => `${BOXES}/${key}`;
+
+async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, env = process.env }: { run?: RunCommand; env?: Env } = {}): Promise<PresentImage | null> {
+ if (!runtime.installed) {
+ const listed = await wslCall(runtime.bin, ["--list", "--verbose"], { run, env });
+ const distro = (runtime.distro ?? DEFAULT_DISTRO).toLowerCase();
+ if (!parseWslList(listed.stdout).some((row) => row.name.toLowerCase() === distro)) return null;
+ }
+ const { out } = await boxrun(runtime, ["image", "--store", STORE, "--ref", distroRef(image.pull), "--arch", runtime.arch || "amd64"], { run, env, timeoutMs: 60_000 });
+ return out?.present ? { id: str(out.id), digest: str(out.digest) || null, arch: str(out.arch), config: str(out.config) } : null;
+}
+
+/** "Download": the distro (once), the helpers, then the image inside it. */
+async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand, env = process.env, home = "", log = () => {} }: { run?: RunCommand; env?: Env; home?: string; log?: BoxLog } = {}): Promise<{ ok: true } | { ok: false; error: string }> {
+ const distro = await ensureDistro(runtime, { env, home, run, log });
+ if (!distro.ok) return { ok: false, error: distro.error };
+ const synced = await syncHelpers(runtime, { env, run });
+ if (!synced.ok) return { ok: false, error: synced.error };
+ const { res, out } = await boxrun(runtime, ["pull", "--store", STORE, "--ref", distroRef(image.pull), "--arch", runtime.arch || "amd64"], { run, env, timeoutMs: 60 * 60_000 });
+ return out?.ok ? { ok: true } : { ok: false, error: String(out?.error || firstLine(res.stderr) || res.code).slice(0, 300) };
+}
+
+type Keeper = { child: ChildProcess; endpoint: { host: string; port: number; token: string }; alternates: Array<{ host: string; port: number; token: string }> };
+
+/** Keepers (wsl.exe boxrun up --foreground) of this process, per box. */
+const keepers = new Map<string, Keeper>();
+
+export type KeeperResult = { ok: true; out: Record<string, unknown>; child: ChildProcess } | { ok: false; error: string };
+
+/** Start the keeper and read boxrun's first JSON line (the port). */
+export function startKeeper(runtime: WslRuntime, args: string[], { env = process.env, spawnImpl = spawn, timeoutMs = 180_000 }: { env?: Env; spawnImpl?: SpawnLike; timeoutMs?: number } = {}): Promise<KeeperResult> {
+ return new Promise((resolve) => {
+ let child: ChildProcess;
+ try {
+ child = spawnImpl(runtime.bin, inDistro(runtime, ["/opt/omnirush/boxrun", ...args, "--foreground"]), { env: { ...env, WSL_UTF8: "1" }, stdio: ["pipe", "pipe", "pipe"], windowsHide: true });
+ } catch (error) {
+ resolve({ ok: false, error: error instanceof Error ? error.message : String(error) });
+ return;
+ }
+ let buffered = "";
+ let errText = "";
+ let done = false;
+ const finish = (value: { ok: true; out: Record<string, unknown> } | { ok: false; error: string }) => {
+ if (done) return;
+ done = true;
+ clearTimeout(timer);
+ if (value.ok) {
+ // Keep it running for this process's lifetime, without holding the process open.
+ child.stdout?.removeAllListeners("data");
+ child.stdout?.resume();
+ child.unref();
+ for (const handle of [child.stdin, child.stdout, child.stderr]) {
+ if (handle && "unref" in handle && typeof handle.unref === "function") handle.unref();
+ }
+ resolve({ ...value, child });
+ } else {
+ try { child.kill(); } catch { /* gone */ }
+ resolve(value);
+ }
+ };
+ const timer = setTimeout(() => finish({ ok: false, error: `WSL did not start the box in ${Math.round(timeoutMs / 1000)} s` }), timeoutMs);
+ child.stdout?.on("data", (chunk: Buffer) => {
+ buffered += decodeWsl(chunk);
+ const out = parseOut(buffered.split("\n").filter((line) => line.trim().startsWith("{")).join("\n"));
+ if (out) finish(out.ok ? { ok: true, out } : { ok: false, error: str(out.error) || "boxrun up failed" });
+ });
+ child.stderr?.on("data", (chunk: Buffer) => { if (errText.length < 4000) errText += decodeWsl(chunk); });
+ child.on("error", (error) => finish({ ok: false, error: error.message }));
+ child.on("close", (code) => finish({ ok: false, error: `the WSL keeper exited (${code}): ${firstLine(errText)}` }));
+ });
+}
+
+type WslMeta = BoxMeta & { mounts?: string[] };
+
+async function open(ctx: OpenContext): Promise<Opened> {
+ const { key, root, croot, runtime, run, home, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling, spawnImpl } = ctx;
+ const file = metaFile(home, key);
+ let meta = readJson<WslMeta>(file);
+ if (meta && meta.root !== root) return { ok: false, error: `box ${key} belongs to another folder` };
+ const live = keepers.get(key);
+ if (live && live.child.exitCode === null && meta) {
+ return { ok: true, created: null, endpoint: live.endpoint, alternates: live.alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: meta.mounts ?? [] };
+ }
+ let present = await imagePresent(runtime, image, { run, env });
+ if (!present && !meta) {
+ if (!mayPull) return { ok: false, error: runtime.installed ? "the sandbox image is not downloaded yet" : "the OmniRush WSL distro is not set up yet" };
+ onPulling();
+ const pulled = await pull(runtime, image, { run, env, home, log });
+ if (!pulled.ok) return { ok: false, error: `could not set up the sandbox: ${pulled.error}` };
+ present = await imagePresent(runtime, image, { run, env });
+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };
+ } else {
+ const synced = await syncHelpers(runtime, { env, run });
+ if (!synced.ok) return { ok: false, error: synced.error };
+ }
+ let created = null;
+ if (!meta) {
+ if (!present) return { ok: false, error: "the sandbox image is not downloaded yet" };
+ meta = newMeta({ key, root, croot, present, image });
+ mkdirSync(path.dirname(file), { recursive: true });
+ writeJson(file, meta);
+ created = { ref: image.ref, pull: image.pull, digest: meta.digest, id: present.config || present.id, stack: image.stack };
+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "wsl" });
+ }
+ const listenAny = String(env.OMNIRUSH_BOX_WSL_LISTEN || "").toLowerCase() === "any";
+ const idle = Number(env.OMNIRUSH_BOX_IDLE_MIN) > 0 ? Number(env.OMNIRUSH_BOX_IDLE_MIN) : IDLE_MINUTES;
+ const args = upArgs({
+ box: boxPath(key), store: STORE, image: meta.image, boxd: "/opt/omnirush/boxd", portFile: `${wslPath(runFolder)}/boxd.port`,
+ root, croot, runFolder, shims, pkglog, token: meta.token, idleMinutes: idle, listen: listenAny ? "0.0.0.0:0" : "127.0.0.1:0",
+ platform: "win32", mapPath: wslPath,
+ });
+ const kept = await startKeeper(runtime, args, { env, ...(spawnImpl ? { spawnImpl } : {}) });
+ if (!kept.ok) return { ok: false, error: `could not start the sandbox: ${kept.error}` };
+ const port = num(kept.out.port) ?? 0;
+ const endpoint = { host: "127.0.0.1", port, token: meta.token };
+ const alternates: Keeper["alternates"] = [];
+ if (listenAny) {
+ const ip = await wslCall(runtime.bin, inDistro(runtime, ["/bin/sh", "-c", "hostname -I"]), { run, env });
+ const addr = String(ip.stdout).split(/\s+/).find((a) => /^\d+\.\d+\.\d+\.\d+$/.test(a));
+ if (addr) alternates.push({ host: addr, port, token: meta.token });
+ }
+ const mounts = [croot, "/run/omnirush", ...(shims ? ["/opt/omnirush/pkglog-src"] : []), ...(pkglog ? [containerRoot(pkglog.root, "win32")] : [])];
+ if (!kept.out.reused) writeJson(file, { ...meta, mounts, started_at: new Date().toISOString() });
+ keepers.set(key, { child: kept.child, endpoint, alternates });
+ return { ok: true, created, endpoint, alternates, uid: 0, gid: 0, containerId: `wsl_${key}_${meta.instance}`, imageId: meta.config || meta.image, mounts: kept.out.reused ? (meta.mounts ?? mounts) : mounts };
+}
+
+function keeperAlive(key: string): boolean {
+ const live = keepers.get(key);
+ return Boolean(live && live.child.exitCode === null);
+}
+
+export const wslDriver: BoxDriver = {
+ kind: "wsl",
+ execFallback: false,
+ imagePresent,
+ pull,
+ /** Desktop: the distro import, the helpers and the image download run in this process (launch.ts pullInBackground). */
+ pullCommand() {
+ return null;
+ },
+ async exists(_runtime, key, { home = "" } = {}) {
+ return existsSync(metaFile(home, key));
+ },
+ open,
+ async list(_runtime, { home = "" } = {}) {
+ const dir = path.join(home, "wsl", "boxes");
+ let names: string[] = [];
+ try { names = readdirSync(dir).filter((n) => n.endsWith(".json")); } catch { return []; }
+ return names.map((n) => readJson<WslMeta>(path.join(dir, n))).filter((m): m is WslMeta => Boolean(m?.key)).map((m) => ({ key: m.key, name: containerName(m.key), root: m.root, running: keeperAlive(m.key), image: m.pull || m.ref, created: m.created_at || "" }));
+ },
+ async remove(runtime, key, { run = runCommand, env = process.env, home = "" } = {}) {
+ keepers.get(key)?.child.kill();
+ keepers.delete(key);
+ const { out } = await boxrun(runtime, ["rm", "--box", boxPath(key)], { run, env, timeoutMs: 120_000 });
+ const had = existsSync(metaFile(home, key));
+ rmSync(metaFile(home, key), { force: true });
+ return { removed: had && Boolean(out?.ok) };
+ },
+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {
+ keepers.get(key)?.child.kill();
+ keepers.delete(key);
+ const { out } = await boxrun(runtime, ["stop", "--box", boxPath(key)], { run, env });
+ return { stopped: Boolean(out?.ok) };
+ },
+ async gcImages() {
+ return [];
+ },
+ async upperBytes(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const { out } = await boxrun(runtime, ["status", "--box", boxPath(key)], { run, env });
+ return num(out?.upper_bytes);
+ },
+ shellCommand(runtime, { key, croot }) {
+ return { bin: runtime.bin, args: inDistro(runtime, ["/opt/omnirush/boxrun", "enter", "--box", boxPath(key), "--wd", croot, "--", "/bin/bash", "-l"]) };
+ },
+ execCommand: (_runtime, { key, home }) => boxshExec({ key, home, platform: "win32" }),
+};
diff --git a/apps/server/src/box/backends/wslc.ts b/apps/server/src/box/backends/wslc.ts
new file mode 100644
index 00000000..9eb45fdc
--- /dev/null
+++ b/apps/server/src/box/backends/wslc.ts
@@ -0,0 +1,275 @@
+// Ported from the CLI (omnirush-cli src/box/backends/wslc.js,
+// feat/local-box-backends); keep the two in step. Desktop differences: types;
+// the container-name prefix (containerName's env); boxd missing from the
+// sidecars is a reason.
+//
+// Windows: WSL containers (`wslc.exe`, alias `container.exe`), the container
+// engine built into WSL since 3.0.1 (GA 2026-09-29; preview from 2.9.3).
+// Containers share WSL 2's kernel; bind mounts take Windows paths and go
+// over VirtioFS; `-p` publishes on Windows' loopback. One persistent
+// container per project, like the Docker backend, with boxd mounted in from
+// the run folder (there is no `cp -` from a tar stream) and published on a
+// port chosen here. Snapshots are boxd's index walk (wslc has no `diff`).
+//
+// Written to wslc's real CLI (microsoft/WSL src/windows/wslc, Oct 2026:
+// arguments/ArgumentDefinitions.h, commands/ContainerCreateCommand.cpp,
+// VersionCommand.cpp, common/MountSpecParsing.cpp):
+// wslc version --format json {"Client":{"Version":"3.0.1.0"}}
+// wslc container create --name --label k=v --mount type=bind,source=C:\..,target=/..[,readonly]
+// -p [ip:]host:container -e K=V -w DIR --entrypoint CMD --cpus N -m 4G IMAGE
+// wslc container start|inspect|remove --force|list --all [--size] --format json
+// wslc image pull|inspect|list|remove; wslc exec -i [-t] [-u] [-w] [-e] NAME CMD...
+// No --init: boxd is PID 1 and reaps itself (boxd's init mode).
+
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { BOX_PORT, HOME_IN_BOX, LABEL, RUN_DIR, SHIMS_DIR, containerName, containerRoot, firstLine, freePort, helperPath, newToken, type BoxInstallLog, type BoxRuntime } from "../common.js";
+import { runCommand, type RunCommand, type RunResult } from "../run.js";
+import type { RuntimeResult } from "../runtime.js";
+import { parseSize } from "./container.js";
+import { versionAtLeast } from "./shared.js";
+import type { BoxDriver, OpenContext, Opened, PresentImage } from "./types.js";
+import { ENABLE_HINT, decodeWsl, wslCall, wslExe } from "./wsl.js";
+
+type Env = NodeJS.ProcessEnv;
+type Row = Record<string, unknown>;
+
+/** WSL containers went GA in WSL 3.0.1; earlier previews (2.9.x) changed their CLI. */
+export const SUPPORTED = { min: "3.0.1" };
+export const UPDATE_HINT = "WSL is older than 3.0.1, which brings WSL containers (`wsl --update`, once)";
+
+export function findWslc({ env = process.env, exists = existsSync }: { env?: Env; exists?: (file: string) => boolean } = {}): string | null {
+ const asked = String(env.OMNIRUSH_BOX_WSLC_BIN || "").trim();
+ if (asked) return exists(asked) ? asked : null;
+ const dirs = String(env.Path || env.PATH || "").split(";").filter(Boolean);
+ const pf = env.ProgramFiles || "C:\\Program Files";
+ const local = env.LOCALAPPDATA || "";
+ for (const dir of [...dirs, path.win32.join(pf, "WSL"), ...(local ? [path.win32.join(local, "Microsoft", "WindowsApps")] : [])]) {
+ const file = path.win32.join(dir, "wslc.exe");
+ if (exists(file)) return file;
+ }
+ return null;
+}
+
+/** `wslc version` (json or text): "3.0.1.0". */
+export function parseWslcVersion(text: unknown): string {
+ const s = decodeWsl(text).trim();
+ try {
+ const v: unknown = JSON.parse(s)?.Client?.Version;
+ if (typeof v === "string" && v) return v;
+ } catch { /* text */ }
+ return (/(\d+\.\d+\.\d+(?:\.\d+)?)/.exec(s) ?? [])[1] ?? "";
+}
+
+export async function probeWslc({ env = process.env, platform = process.platform, run = runCommand, exists = existsSync, timeoutMs = 15_000, arch = process.arch }: { env?: Env; platform?: NodeJS.Platform; run?: RunCommand; exists?: (file: string) => boolean; timeoutMs?: number; arch?: string } = {}): Promise<RuntimeResult> {
+ const base = { name: "wslc", backend: "wslc" };
+ if (platform !== "win32") return { ...base, ok: false, reason: "WSL containers are Windows only" };
+ if (env.OMNIRUSH_BOX_WSL === "0") return { ...base, ok: false, reason: "turned off (OMNIRUSH_BOX_WSL=0)" };
+ const bin = findWslc({ env, exists });
+ if (!bin) {
+ // Tell "WSL is old" (one `wsl --update`) from "WSL is off" (admin, restart).
+ const wsl = wslExe({ env, exists });
+ if (!wsl) return { ...base, ok: false, reason: ENABLE_HINT };
+ const ver = await wslCall(wsl, ["--version"], { run, env, timeoutMs });
+ const version = (/(\d+\.\d+\.\d+(?:\.\d+)?)/.exec(ver.code === 0 ? ver.stdout : "") ?? [])[1] ?? "";
+ if (!version) return { ...base, ok: false, reason: ver.code === 0 ? UPDATE_HINT : ENABLE_HINT };
+ return { ...base, ok: false, reason: versionAtLeast(version, SUPPORTED.min) ? "wslc.exe is missing although WSL is 3.0.1 or later (`wsl --update`)" : `${UPDATE_HINT}; this is WSL ${version}` };
+ }
+ const res = await run(bin, ["version", "--format", "json"], { env, timeoutMs });
+ let version = res.code === 0 ? parseWslcVersion(res.stdout) : "";
+ if (!version) version = parseWslcVersion((await run(bin, ["version"], { env, timeoutMs })).stdout);
+ if (!version) return { ...base, ok: false, bin, reason: `\`wslc version\` failed: ${firstLine(decodeWsl(res.stderr)) || res.code}` };
+ if (!versionAtLeast(version, SUPPORTED.min)) return { ...base, ok: false, bin, version, reason: `${UPDATE_HINT}; wslc is ${version}` };
+ return { ...base, ok: true, bin, version, os: "linux", arch: arch === "arm64" ? "arm64" : "amd64", flavor: "wslc", rootless: false, vm: true };
+}
+
+function rowOf(value: unknown): Row {
+ return value && typeof value === "object" && !Array.isArray(value) ? Object.fromEntries(Object.entries(value)) : {};
+}
+
+/** `container list --format json`: an array, or one object per line. */
+export function parseJsonRows(text: unknown): Row[] {
+ const s = decodeWsl(text).trim();
+ if (!s) return [];
+ try {
+ const parsed: unknown = JSON.parse(s);
+ return (Array.isArray(parsed) ? parsed : [parsed]).map(rowOf);
+ } catch { /* lines */ }
+ const out: Row[] = [];
+ for (const line of s.split("\n")) {
+ try { out.push(rowOf(JSON.parse(line))); } catch { /* skip */ }
+ }
+ return out;
+}
+
+/** Labels as a map (an object, or docker's "k=v,k=v"). */
+export function labelsOf(value: unknown): Record<string, string> {
+ if (value && typeof value === "object" && !Array.isArray(value)) return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, String(v)]));
+ if (typeof value !== "string") return {};
+ return Object.fromEntries(value.split(",").filter(Boolean).map((kv) => { const i = kv.indexOf("="); return i < 0 ? [kv, ""] : [kv.slice(0, i), kv.slice(i + 1)]; }));
+}
+
+export function wslcResources({ env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { env?: Env; cpus?: number; memory?: number } = {}): string[] {
+ const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);
+ const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();
+ const c = askedCpus > 0 ? Math.round(askedCpus) : Math.max(1, Math.min(8, cpus - 1));
+ // wslc takes upper-case units only (512M, 4G).
+ const m = askedMem ? askedMem.toUpperCase() : `${Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)))}G`;
+ return ["--cpus", String(c), "-m", m];
+}
+
+export function createWslcArgs({ name, key, root, croot, image, runFolder, shims = null, pkglog = null, token, port, env = process.env }: { name: string; key: string; root: string; croot: string; image: string; runFolder: string; shims?: string | null; pkglog?: Pick<BoxInstallLog, "root"> | null; token: string; port: number; env?: Env }): string[] {
+ return [
+ "container", "create", "--name", name,
+ "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`, "--label", `${LABEL}.port=${port}`,
+ "--hostname", "omnirush-box",
+ "--mount", `type=bind,source=${root},target=${croot}`,
+ "--mount", `type=bind,source=${runFolder},target=${RUN_DIR}`,
+ "--mount", `type=bind,source=${path.win32.join(runFolder, "bin")},target=/opt/omnirush/bin,readonly`,
+ ...(shims ? ["--mount", `type=bind,source=${shims},target=${SHIMS_DIR}-src,readonly`] : []),
+ ...(pkglog ? ["--mount", `type=bind,source=${pkglog.root},target=${containerRoot(pkglog.root, "win32")}`] : []),
+ "-p", `127.0.0.1:${port}:${BOX_PORT}`,
+ "-e", `BOXD_TOKEN=${token}`, "-e", "BOXD_UID=0", "-e", "BOXD_GID=0", "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,
+ "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",
+ "-w", croot,
+ ...wslcResources({ env }),
+ "--entrypoint", "/opt/omnirush/bin/boxd",
+ image,
+ ];
+}
+
+function placeBoxd(runFolder: string, env: Env, goarch: string): string | null {
+ const source = helperPath("boxd", { goos: "linux", goarch, env });
+ if (!source) return `the sandbox helper boxd (linux-${goarch}) is missing from this install`;
+ const dir = path.join(runFolder, "bin");
+ mkdirSync(dir, { recursive: true });
+ const target = path.join(dir, "boxd");
+ let same = false;
+ try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }
+ if (!same) {
+ copyFileSync(source, target);
+ try { chmodSync(target, 0o755); } catch { /* Windows */ }
+ }
+ return null;
+}
+
+async function wslc(runtime: BoxRuntime, args: string[], { run = runCommand, timeoutMs = 60_000, env }: { run?: RunCommand; timeoutMs?: number; env?: Env } = {}): Promise<RunResult> {
+ const res = await run(runtime.bin, args, { timeoutMs, ...(env ? { env } : {}) });
+ return { ...res, stdout: decodeWsl(res.stdout), stderr: decodeWsl(res.stderr) };
+}
+
+const nameOf = (r: Row) => String(r.Names ?? r.Name ?? "").replace(/^\//, "");
+
+async function row(runtime: BoxRuntime, name: string, { run, size = false }: { run: RunCommand; size?: boolean }): Promise<Row | null> {
+ const res = await wslc(runtime, ["container", "list", "--all", ...(size ? ["--size"] : []), "--no-trunc", "--format", "json"], { run, timeoutMs: 30_000 });
+ if (res.code !== 0) return null;
+ return parseJsonRows(res.stdout).find((r) => nameOf(r) === name) ?? null;
+}
+
+async function imagePresent(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<PresentImage | null> {
+ const res = await wslc(runtime, ["image", "inspect", image.pull], { run, timeoutMs: 20_000 });
+ if (res.code !== 0) return null;
+ const info = parseJsonRows(res.stdout)[0] ?? {};
+ const digest = (Array.isArray(info.RepoDigests) ? info.RepoDigests : []).map((d) => String(d).split("@")[1]).find((d) => /^sha256:[0-9a-f]{64}$/.test(d || "")) ?? null;
+ return { id: String(info.Id ?? info.ID ?? image.pull), digest, arch: String(info.Architecture ?? "") };
+}
+
+async function pull(runtime: BoxRuntime, image: { pull: string }, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ ok: true } | { ok: false; error: string }> {
+ const res = await wslc(runtime, ["image", "pull", image.pull], { run, timeoutMs: 60 * 60_000 });
+ return res.code === 0 ? { ok: true } : { ok: false, error: firstLine(res.stderr) || firstLine(res.stdout) || `image pull exited ${res.code}` };
+}
+
+async function open(ctx: OpenContext): Promise<Opened> {
+ const { key, name, root, croot, runtime, run, runFolder, image, pull: mayPull, shims, pkglog, env, log, onPulling } = ctx;
+ let info = await row(runtime, name, { run });
+ const labels = labelsOf(info?.Labels);
+ if (info && labels[`${LABEL}.root`] && labels[`${LABEL}.root`] !== root) return { ok: false, error: `container ${name} belongs to another folder` };
+ const placed = placeBoxd(runFolder, env, runtime.arch || "amd64");
+ if (placed) return { ok: false, error: placed };
+ const tokenFile = path.join(runFolder, "box-token");
+ let created = null;
+ if (!info) {
+ let present = await imagePresent(runtime, image, { run });
+ if (!present) {
+ if (!mayPull) return { ok: false, error: "the sandbox image is not downloaded yet" };
+ onPulling();
+ const pulled = await pull(runtime, image, { run });
+ if (!pulled.ok) return { ok: false, error: `could not download the sandbox image: ${pulled.error}` };
+ present = await imagePresent(runtime, image, { run });
+ if (!present) return { ok: false, error: "the sandbox image is not there after the download" };
+ }
+ const token = newToken();
+ writeFileSync(tokenFile, token, { mode: 0o600 });
+ const port = await freePort();
+ const made = await wslc(runtime, createWslcArgs({ name, key, root, croot, image: image.pull, runFolder, shims, pkglog, token, port, env }), { run, timeoutMs: 120_000 });
+ if (made.code !== 0) return { ok: false, error: `could not create the sandbox: ${firstLine(made.stderr) || firstLine(made.stdout)}` };
+ created = { ref: image.ref, pull: image.pull, digest: image.digest || present.digest, id: present.id, stack: image.stack };
+ log("info", "box created", { key, image: image.pull, stack: image.stack, backend: "wslc" });
+ info = await row(runtime, name, { run });
+ if (!info) return { ok: false, error: "the sandbox was created but is not listed" };
+ }
+ if (!/running/i.test(String(info.State ?? ""))) {
+ const started = await wslc(runtime, ["container", "start", name], { run, timeoutMs: 120_000 });
+ if (started.code !== 0) return { ok: false, error: `could not start the sandbox: ${firstLine(started.stderr) || firstLine(started.stdout)}` };
+ }
+ let token = "";
+ try { token = readFileSync(tokenFile, "utf8").trim(); } catch { /* none */ }
+ const port = Number(labelsOf(info.Labels)[`${LABEL}.port`]) || 0;
+ if (!token || !port) return { ok: false, error: "the sandbox has no port or token (Reset sandbox makes a new one)" };
+ return { ok: true, created, endpoint: { host: "127.0.0.1", port, token }, uid: 0, gid: 0, containerId: String(info.ID ?? info.Id ?? name), imageId: String(info.Image ?? ""), mounts: [croot, RUN_DIR, ...(shims ? [`${SHIMS_DIR}-src`] : []), ...(pkglog ? [containerRoot(pkglog.root, "win32")] : [])] };
+}
+
+export const wslcDriver: BoxDriver = {
+ kind: "wslc",
+ /** boxsh's fallback `<runtime> exec -i -w -u -e` matches wslc exec's flags. */
+ execFallback: true,
+ imagePresent,
+ pull,
+ pullCommand(runtime, image) {
+ return { bin: runtime.bin, args: ["image", "pull", image.pull] };
+ },
+ async exists(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await wslc(runtime, ["container", "inspect", containerName(key, env)], { run, timeoutMs: 20_000 });
+ return res.code === 0 && parseJsonRows(res.stdout).length > 0;
+ },
+ open,
+ async list(runtime, { run = runCommand } = {}) {
+ const res = await wslc(runtime, ["container", "list", "--all", "--no-trunc", "--format", "json"], { run, timeoutMs: 30_000 });
+ if (res.code !== 0) return [];
+ return parseJsonRows(res.stdout).map((r) => ({ r, labels: labelsOf(r.Labels) })).filter(({ labels }) => labels[LABEL] === "1").map(({ r, labels }) => ({
+ key: labels[`${LABEL}.key`] ?? "", name: nameOf(r), root: labels[`${LABEL}.root`] ?? "",
+ running: /running/i.test(String(r.State ?? "")), image: String(r.Image ?? ""), created: String(r.CreatedAt ?? ""),
+ }));
+ },
+ async remove(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await wslc(runtime, ["container", "remove", "--force", containerName(key, env)], { run, timeoutMs: 60_000 });
+ return { removed: res.code === 0 };
+ },
+ async gcImages(runtime, { run = runCommand, current, used }) {
+ const removed = [];
+ const res = await wslc(runtime, ["image", "list", "--format", "json"], { run, timeoutMs: 30_000 });
+ for (const img of parseJsonRows(res.stdout)) {
+ const ref = img.Repository && img.Tag ? `${img.Repository}:${img.Tag}` : String(img.Name ?? img.Reference ?? "");
+ if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref)) continue;
+ const del = await wslc(runtime, ["image", "remove", ref], { run, timeoutMs: 60_000 });
+ if (del.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });
+ }
+ return removed;
+ },
+ async stop(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const res = await wslc(runtime, ["container", "stop", "-t", "1", containerName(key, env)], { run, timeoutMs: 60_000 });
+ return { stopped: res.code === 0 };
+ },
+ async upperBytes(runtime, key, { run = runCommand, env = process.env } = {}) {
+ const r = await row(runtime, containerName(key, env), { run, size: true });
+ return r ? parseSize(r.Size) : null;
+ },
+ shellCommand(runtime, { key, croot, env = process.env }) {
+ return { bin: runtime.bin, args: ["exec", "-it", "-w", croot, containerName(key, env), "/bin/bash", "-l"] };
+ },
+ execCommand(runtime, { key, env = process.env }) {
+ return { bin: runtime.bin, args: ["exec", "-i", containerName(key, env)], env: {} };
+ },
+};
diff --git a/apps/server/src/box/box-backends.test.ts b/apps/server/src/box/box-backends.test.ts
new file mode 100644
index 00000000..877b4a9d
--- /dev/null
+++ b/apps/server/src/box/box-backends.test.ts
@@ -0,0 +1,444 @@
+// Ported from the CLI (omnirush-cli test/box-backends.test.js,
+// feat/local-box-backends): the ranked choice per OS and each backend against
+// its real CLI's output, mocked (no runtime on the test machine is touched):
+// bubblewrap (boxrun's JSON), Apple `container` (1.x JSON), the OmniRush WSL
+// distro (wsl.exe's UTF-16 output), WSL containers (wslc 3.0.1 JSON), and the
+// overrides (the backend setting, the server's allowlist). Desktop additions:
+// the service's status and setting, files-used through a non-container box.
+import { afterEach, describe, expect, test } from "bun:test";
+import { ChildProcess } from "node:child_process";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { PassThrough } from "node:stream";
+
+import { BACKENDS, backendsFor, detectBackend, driverFor, normalizeBackend, ORDER } from "./backends/index.js";
+import { apparmorProfile, boxdEnv, boxrunPath, explainProbe, parseOut, probeBwrap, upArgs } from "./backends/bwrap.js";
+import { createAppleArgs, findDigest, macosMajor, parseVersions, probeApple, snapshotInfo, SUPPORTED as APPLE } from "./backends/apple.js";
+import { versionAtLeast } from "./backends/shared.js";
+import { decodeWsl, ENABLE_HINT, inDistro, parseWslList, probeWslDistro, startKeeper } from "./backends/wsl.js";
+import { createWslcArgs, labelsOf, parseJsonRows, parseWslcVersion, probeWslc, UPDATE_HINT } from "./backends/wslc.js";
+import { Box, setToolsRoot } from "./box.js";
+import { askedBackend, readBackend, rememberServerDefault, saveBackend, serverBackends } from "./launch.js";
+import type { RunCommand, RunResult } from "./run.js";
+import { BoxService, backendChoices, type BoxWorkspace } from "./service.js";
+import { sandboxFilesUsed } from "../session-archive/files-used-sandbox.js";
+
+const dirs: string[] = [];
+const tmp = () => {
+ const dir = mkdtempSync(path.join(os.tmpdir(), "box-be-"));
+ dirs.push(dir);
+ return dir;
+};
+afterEach(() => {
+ setToolsRoot(null);
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+const set = (...files: Array<string | null>) => (file: string) => files.includes(file);
+const ok = (stdout: unknown): RunResult => ({ code: 0, stdout: typeof stdout === "string" ? stdout : JSON.stringify(stdout), stderr: "" });
+const fail = (stderr: string, code = 1): RunResult => ({ code, stdout: "", stderr });
+
+/** A helpers folder with linux boxrun and boxd (empty stand-ins): the desktop finds helpers only where they are. */
+function helperBin(): string {
+ const dir = tmp();
+ for (const arch of ["amd64", "arm64"]) {
+ mkdirSync(path.join(dir, `linux-${arch}`), { recursive: true });
+ for (const name of ["boxrun", "boxd"]) writeFileSync(path.join(dir, `linux-${arch}`, name), "");
+ }
+ return dir;
+}
+
+// --- ranking and overrides ---------------------------------------------------------------
+
+describe("box backends: ranking and overrides", () => {
+ test("the ranked order per OS", () => {
+ expect(ORDER.linux).toEqual(["bwrap", "podman", "docker"]);
+ expect(ORDER.darwin).toEqual(["apple", "orbstack", "colima", "docker-desktop", "rancher", "podman", "docker"]);
+ expect(ORDER.win32).toEqual(["wslc", "wsl", "docker-desktop", "podman", "docker", "wsl-engine"]);
+ for (const list of Object.values(ORDER)) for (const id of list) expect(BACKENDS.some((b) => b === id)).toBe(true);
+ expect(backendsFor("linux")).toEqual(ORDER.linux);
+ expect(backendChoices("win32").map((c) => c.id)).toEqual(["auto", ...ORDER.win32, "native"]);
+ });
+
+ test("setting values: ids, aliases, auto, native; anything else is refused", () => {
+ expect(normalizeBackend("")).toBe("auto");
+ expect(normalizeBackend("Bubblewrap")).toBe("bwrap");
+ expect(normalizeBackend("container")).toBe("apple");
+ expect(normalizeBackend("wsl-containers")).toBe("wslc");
+ expect(normalizeBackend("desktop")).toBe("docker-desktop");
+ expect(normalizeBackend("off")).toBe("native");
+ expect(normalizeBackend("lxc")).toBeNull();
+ });
+});
+
+// --- Linux: bubblewrap ------------------------------------------------------------------------
+
+const BWRAP_OK = { ok: true, launcher: "bwrap", bwrap: "/usr/bin/bwrap", bwrap_version: "0.9.0", overlay: "kernel", idmap: "subuid", kernel: "6.8.0", apparmor_restrict_unprivileged_userns: 0, root: false, ms: 9 };
+const BWRAP_AA = { ok: false, launcher: "bwrap", bwrap: "/usr/bin/bwrap", bwrap_version: "0.9.0", kernel: "6.8.0", apparmor_restrict_unprivileged_userns: 1, code: "apparmor", reason: "AppArmor blocks unprivileged user namespaces (kernel.apparmor_restrict_unprivileged_userns=1, Ubuntu 23.10+)", detail: "bwrap: setting up uid map: Permission denied" };
+const podmanInfo = { host: { arch: "amd64", os: "linux", security: { rootless: true } }, version: { Version: "4.9.3" } };
+
+function linuxRun(bwrapAnswer: unknown, { podman = true }: { podman?: boolean } = {}) {
+ const calls: string[] = [];
+ const run: RunCommand = async (bin, args) => {
+ calls.push([path.basename(bin), ...args].join(" "));
+ if (bin.endsWith("boxrun")) return ok(bwrapAnswer);
+ if (bin.endsWith("podman")) return podman ? ok(podmanInfo) : fail("podman: not found", 127);
+ return fail("Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?");
+ };
+ return { run, calls };
+}
+
+describe("box backends: Linux", () => {
+ test("bubblewrap first when its probe starts a namespace", async () => {
+ const home = tmp();
+ const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };
+ const { run } = linuxRun(BWRAP_OK);
+ const found = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, wsl: false });
+ expect(found).toMatchObject({ ok: true, backend: "bwrap", flavor: "overlayfs", idmap: "subuid", version: "0.9.0" });
+ if (found.ok) expect(found.why).toMatch(/bwrap > podman > docker/);
+ expect(driverFor(found.ok ? found : null).kind).toBe("bwrap");
+ });
+
+ test("AppArmor's userns restriction: one-line reason with the admin fix, rootless Podman is used", async () => {
+ const home = tmp();
+ const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };
+ const found = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run: linuxRun(BWRAP_AA).run, fresh: true, all: true, wsl: false });
+ expect(found).toMatchObject({ ok: true, backend: "podman" });
+ const bw = found.alternatives?.find((a) => a.backend === "bwrap");
+ expect(bw?.ok).toBe(false);
+ expect(bw?.reason).toMatch(/AppArmor .*sudo omnirush sandbox enable/);
+ expect(bw?.reason).not.toMatch(/\n/);
+ // Nothing else either: the project runs natively and says why in one line.
+ const none = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env })), run: linuxRun(BWRAP_AA, { podman: false }).run, fresh: true, wsl: false });
+ expect(none.ok).toBe(false);
+ if (!none.ok) expect(none.reason).toMatch(/^bwrap: AppArmor/);
+ });
+
+ test("bwrap probe reasons: no bwrap, userns off, helper missing, garbage", async () => {
+ expect(explainProbe({ code: "no_bwrap", reason: "bubblewrap (bwrap) is not installed" })).toMatch(/apt install bubblewrap/);
+ expect(explainProbe({ code: "userns_off", reason: "x" })).toMatch(/Podman or Docker/);
+ const home = tmp();
+ const missing = await probeBwrap({ env: { OMNIRUSH_BOX_BIN_DIR: "/nope" }, boxHome: home, exists: () => false, platform: "linux" });
+ expect(missing.ok ? "" : missing.reason).toMatch(/boxrun is missing/);
+ const garbage = await probeBwrap({ env: { OMNIRUSH_BOX_BIN_DIR: helperBin() }, boxHome: home, exists: () => true, platform: "linux", run: async () => ({ code: 1, stdout: "", stderr: "segfault" }) });
+ expect(garbage.ok).toBe(false);
+ expect(parseOut('noise\n{"a":1}\n{"ok":true,"port":5}\n')).toEqual({ ok: true, port: 5 });
+ });
+
+ test("the setting picks one backend; native turns the box off; the server's allowlist skips the rest", async () => {
+ const home = tmp();
+ const env = { PATH: "/usr/bin", OMNIRUSH_BOX_BIN_DIR: helperBin() };
+ const { run, calls } = linuxRun(BWRAP_OK);
+ const asked = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, asked: "podman", wsl: false });
+ expect(asked).toMatchObject({ ok: true, backend: "podman" });
+ if (asked.ok) expect(asked.why).toMatch(/chosen in Settings/);
+ expect(calls.some((c) => c.startsWith("boxrun"))).toBe(false);
+ const native = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: () => true, run, fresh: true, asked: "native" });
+ expect(native).toMatchObject({ ok: false, native: true });
+ const unknown = await detectBackend({ boxHome: home, platform: "linux", home, env, run, fresh: true, asked: "lxc" });
+ expect(unknown.ok ? "" : unknown.reason).toMatch(/unknown sandbox backend "lxc"/);
+ const allowed = await detectBackend({ boxHome: home, platform: "linux", home, env, exists: set(boxrunPath({ env }), "/usr/bin/podman"), run, fresh: true, all: true, allow: ["podman", "docker"], wsl: false });
+ expect(allowed).toMatchObject({ ok: true, backend: "podman" });
+ expect(allowed.alternatives?.find((a) => a.backend === "bwrap")?.reason).toBe("not allowed by the server");
+ });
+
+ test("the backend setting and the server's allowlist are remembered", () => {
+ const state = tmp();
+ expect(readBackend(state)).toBe("auto");
+ expect(saveBackend(state, "Bubblewrap")).toBe("bwrap");
+ expect(askedBackend({ env: {}, stateDir: state })).toEqual({ backend: "bwrap", source: "setting" });
+ expect(askedBackend({ env: { OMNIRUSH_BOX_BACKEND: "docker" }, stateDir: state })).toEqual({ backend: "docker", source: "env" });
+ expect(() => saveBackend(state, "nope")).toThrow();
+ expect(JSON.parse(readFileSync(path.join(state, "box.json"), "utf8"))).toEqual({ backend: "bwrap" });
+ expect(rememberServerDefault(state, { local_box: { default: "offer", backends: ["bwrap", "docker", 3] } })).toBe(true);
+ expect(serverBackends(state)).toEqual(["bwrap", "docker"]);
+ expect(rememberServerDefault(state, { local_box: { default: "offer", backends: ["bwrap", "docker"] } })).toBe(false);
+ rememberServerDefault(state, { local_box: { default: "off" } });
+ expect(serverBackends(state)).toBeNull();
+ });
+
+ test("bwrap box start: the project at its path, the run folder, boxd on loopback with a port file, nothing of $HOME", () => {
+ const args = upArgs({ box: "/h/.omnirush/box/bwrap/boxes/k", store: "/h/.omnirush/box/bwrap/store", image: "abc-amd64", boxd: "/pkg/boxd", portFile: "/h/.omnirush/box/projects/k/boxd.port", root: "/home/u/proj", croot: "/home/u/proj", runFolder: "/h/.omnirush/box/projects/k", pkglog: { root: "/h/.omnirush/pkglog" }, token: "t0k", idleMinutes: 90 });
+ const binds = args.flatMap((a, i) => (a === "--bind" || a === "--ro-bind" ? [args[i + 1]] : []));
+ expect(binds).toEqual(["/home/u/proj=/home/u/proj", "/h/.omnirush/box/projects/k=/run/omnirush", "/h/.omnirush/pkglog=/h/.omnirush/pkglog"]);
+ const env = args.flatMap((a, i) => (a === "--env" ? [args[i + 1]] : []));
+ expect(env).toContain("BOXD_LISTEN=127.0.0.1:0");
+ expect(env).toContain("BOXD_PORT_FILE=/run/omnirush/boxd.port");
+ expect(env).toContain("BOXD_IDLE_EXIT=90");
+ expect(env).toContain("BOXD_TOKEN=t0k");
+ expect(binds.some((b) => b?.startsWith("/h=") || b?.includes(".ssh"))).toBe(false);
+ expect(boxdEnv({ token: "x", croot: "/c" }).filter((kv) => kv.startsWith("BOXD_UID") || kv.startsWith("BOXD_HOME"))).toEqual(["BOXD_UID=0", "BOXD_HOME=/root"]);
+ });
+
+ test("the AppArmor profile the CLI installs covers OmniRush's own bwrap only (userns), never the sysctl", () => {
+ const profile = apparmorProfile("/usr/local/lib/omnirush/bwrap");
+ expect(profile).toMatch(/profile omnirush-bwrap \/usr\/local\/lib\/omnirush\/bwrap flags=\(unconfined\) \{\n userns,/);
+ expect(/sysctl|apparmor_restrict/.test(profile.replace(/^#.*$/gm, ""))).toBe(false);
+ });
+});
+
+// --- macOS: Apple container -----------------------------------------------------------------
+
+const APPLE_BIN = "/usr/local/bin/container";
+const appleVersions = [{ appName: "container", version: "1.5.0", buildType: "release", commit: "abc" }, { appName: "container-apiserver", version: "1.5.0", buildType: "release", commit: "abc" }];
+
+describe("box backends: macOS", () => {
+ test("Apple container: macOS 26 on Apple silicon, the 1.x line, its service running", async () => {
+ expect(macosMajor("25.0.0")).toBe(26);
+ expect(macosMajor("24.6.0")).toBe(25);
+ expect(parseVersions(JSON.stringify(appleVersions))).toEqual({ version: "1.5.0", server: "1.5.0" });
+ expect(parseVersions("container CLI version 0.5.0 (build: release, commit: 1234)").version).toBe("0.5.0");
+ const base = { platform: "darwin" as const, arch: "arm64", release: "25.1.0", env: { PATH: "/usr/bin" }, exists: set(APPLE_BIN) };
+ const good: RunCommand = async (_bin, args) => (args[1] === "version" ? ok(appleVersions) : ok("apiserver is running"));
+ expect(await probeApple({ ...base, run: good })).toMatchObject({ ok: true, version: "1.5.0", arch: "arm64", vm: true });
+ const reason = async (run: RunCommand, extra: Record<string, unknown> = {}) => {
+ const r = await probeApple({ ...base, ...extra, run });
+ return r.ok ? "" : r.reason;
+ };
+ expect(await reason(good, { arch: "x64" })).toMatch(/Apple silicon/);
+ expect(await reason(good, { release: "24.6.0" })).toMatch(/macOS 26 or later \(this is macOS 25\)/);
+ expect(await reason(good, { exists: () => false })).toMatch(/not installed/);
+ expect(await reason(async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "0.11.0" }]) : ok("")))).toMatch(/0\.11\.0 is outside the supported 1\.x line/);
+ expect((await probeApple({ ...base, run: async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "2.0.0" }]) : ok("")) })).ok).toBe(false);
+ expect(await reason(async (_b, args) => (args[1] === "version" ? ok([{ appName: "container", version: "1.4.1" }]) : fail("apiserver is not running and not registered with launchd")))).toMatch(/container system start/);
+ expect(versionAtLeast("1.4.1", APPLE.min) && !versionAtLeast("1.4.1", APPLE.below)).toBe(true);
+ });
+
+ test("Apple container: create args, list/inspect JSON, image digest", () => {
+ const args = createAppleArgs({ name: "omnirush-box-k", key: "k", root: "/Users/sam/proj", croot: "/Users/sam/proj", image: `ghcr.io/omnirush-ai/box-base@sha256:${"a".repeat(64)}`, runFolder: "/Users/sam/.omnirush/box/projects/k", token: "t", port: 50123, env: { OMNIRUSH_BOX_MEMORY: "6G" } });
+ expect(args).toContain("type=bind,source=/Users/sam/proj,target=/Users/sam/proj");
+ expect(args).toContain("type=bind,source=/Users/sam/.omnirush/box/projects/k/bin,target=/opt/omnirush/bin,readonly");
+ expect(args.slice(args.indexOf("-p"), args.indexOf("-p") + 2)).toEqual(["-p", "127.0.0.1:50123:7777"]);
+ expect(args[args.indexOf("--memory") + 1]).toBe("6G");
+ expect(args[args.indexOf("--entrypoint") + 1]).toBe("/opt/omnirush/bin/boxd");
+ expect(args).toContain("--init");
+ expect(args).toContain("ai.omnirush.box.port=50123");
+ const snap = { configuration: { id: "omnirush-box-k", image: { reference: "ghcr.io/omnirush-ai/box-base:1", descriptor: { digest: `sha256:${"b".repeat(64)}` } }, labels: { "ai.omnirush.box": "1", "ai.omnirush.box.key": "k" } }, status: "running", networks: [{ network: "default", hostname: "omnirush-box-k", ipv4Address: "192.168.64.7/24", ipv4Gateway: "192.168.64.1" }] };
+ expect(snapshotInfo(snap)).toMatchObject({ running: true, address: "192.168.64.7", digest: `sha256:${"b".repeat(64)}` });
+ expect(snapshotInfo({ ...snap, networks: [{ address: "192.168.64.9/24" }] }).address).toBe("192.168.64.9");
+ expect(findDigest([{ name: "x", index: { digest: `sha256:${"c".repeat(64)}` } }])).toBe(`sha256:${"c".repeat(64)}`);
+ expect(findDigest({ variants: [{ config: { digest: `sha256:${"d".repeat(64)}` } }] })).toBe(`sha256:${"d".repeat(64)}`);
+ });
+
+ test("ranking: Apple container first, then OrbStack, colima, Docker Desktop through docker contexts", async () => {
+ const docker = "/usr/local/bin/docker";
+ const infos: Record<string, unknown> = { orbstack: { OperatingSystem: "OrbStack", Name: "orbstack", ServerVersion: "27.0", OSType: "linux", Architecture: "aarch64" }, colima: { OperatingSystem: "Ubuntu 24.04", Name: "colima", ServerVersion: "27.1", OSType: "linux" }, "desktop-linux": { OperatingSystem: "Docker Desktop", ServerVersion: "28.0", OSType: "linux" } };
+ const contexts = ["desktop-linux", "colima", "default"].map((Name) => JSON.stringify({ Name, DockerEndpoint: `unix:///x/${Name}.sock` })).join("\n");
+ const run: RunCommand = async (bin, args) => {
+ if (bin === APPLE_BIN) return fail("not installed", 127);
+ if (args[0] === "context") return ok(contexts);
+ if (args[0] === "--context") return infos[args[1] ?? ""] ? ok(infos[args[1] ?? ""]) : fail("Cannot connect to the Docker daemon");
+ return fail("no");
+ };
+ const home = tmp();
+ const found = await detectBackend({ boxHome: home, platform: "darwin", arch: "arm64", release: "24.0.0", home: "/Users/sam", env: { PATH: "/usr/local/bin" }, exists: set(docker), run, fresh: true, all: true });
+ expect(found).toMatchObject({ ok: true, backend: "colima", prefix: ["--context", "colima"] });
+ expect(found.alternatives?.find((a) => a.backend === "apple")?.reason).toMatch(/macOS 26/);
+ expect(found.alternatives?.some((a) => a.backend === "docker-desktop" && a.ok)).toBe(true);
+ const none = await detectBackend({ boxHome: home, platform: "darwin", home: "/Users/sam", env: { PATH: "/usr/bin" }, exists: () => false, run, fresh: true });
+ expect(none).toMatchObject({ ok: false, hint: "colima" });
+ });
+});
+
+// --- Windows: the OmniRush WSL distro --------------------------------------------------------
+
+const WSL = "C:\\Windows\\System32\\wsl.exe";
+const winEnv = { Path: "C:\\Windows\\System32", SystemRoot: "C:\\Windows", ProgramFiles: "C:\\Program Files", LOCALAPPDATA: "C:\\Users\\sam\\AppData\\Local" };
+const utf16 = (text: string) => Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(text, "utf16le")]);
+
+function wslRun({ status = ok("Default Version: 2\r\n"), list = ok(" NAME STATE VERSION\r\n"), version = ok("WSL version: 2.6.1.0\r\nKernel version: 6.6.87.2-1\r\n") }: { status?: RunResult; list?: RunResult; version?: RunResult } = {}): RunCommand {
+ return async (_bin, args) => {
+ if (args[0] === "--status") return status;
+ if (args[0] === "--list") return list;
+ if (args[0] === "--version") return version;
+ return fail("unexpected");
+ };
+}
+
+/** A child process with pipes and no process behind it (the WSL keeper's stand-in). */
+class FakeChild extends ChildProcess {
+ override stdout = new PassThrough();
+ override stderr = new PassThrough();
+ override stdin = new PassThrough();
+}
+const fakeChild = () => new FakeChild();
+
+describe("box backends: Windows", () => {
+ test("wsl.exe output: UTF-16LE with a BOM or UTF-8, the verbose list with its default marker", () => {
+ const list = " NAME STATE VERSION\r\n* Ubuntu-24.04 Running 2\r\n OmniRushBox Stopped 2\r\n Legacy Distro Stopped 1\r\n";
+ expect(decodeWsl(utf16(list))).toBe(decodeWsl(Buffer.from(list)));
+ expect(parseWslList(utf16(list))).toEqual([
+ { name: "Ubuntu-24.04", state: "Running", version: "2", isDefault: true },
+ { name: "OmniRushBox", state: "Stopped", version: "2", isDefault: false },
+ { name: "Legacy Distro", state: "Stopped", version: "1", isDefault: false },
+ ]);
+ // What runCommand hands over when it read UTF-16 as UTF-8: NULs between letters.
+ expect(decodeWsl("W\u0000S\u0000L\u0000")).toBe("WSL");
+ });
+
+ test("distro probe: not enabled is the one-time admin hint (never an install); WSL 1 and unpublished images say so", async () => {
+ const reason = (r: Awaited<ReturnType<typeof probeWslDistro>>) => (r.ok ? "" : r.reason);
+ const off = await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun({ status: fail(Buffer.from("Windows Subsystem for Linux is not installed. You can install by running 'wsl.exe --install'.", "utf16le").toString("utf8")) }) });
+ expect(reason(off)).toBe(ENABLE_HINT);
+ expect(ENABLE_HINT).toMatch(/administrator terminal: `wsl --install --no-distribution`, then restart/);
+ expect(reason(await probeWslDistro({ platform: "win32", env: winEnv, exists: () => false, run: wslRun() }))).toBe(ENABLE_HINT);
+ const v1 = await probeWslDistro({ platform: "win32", env: { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" }, exists: set(WSL), run: wslRun({ list: ok(" NAME STATE VERSION\r\n OmniRushBox Stopped 1\r\n") }) });
+ expect(reason(v1)).toMatch(/WSL 1/);
+ expect(reason(await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun() }))).toMatch(/not published yet/);
+ const ready = await probeWslDistro({ platform: "win32", env: { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" }, exists: set(WSL), run: wslRun() });
+ expect(ready).toMatchObject({ ok: true, installed: false, distro: "OmniRushBox", version: "2.6.1.0" });
+ const installed = await probeWslDistro({ platform: "win32", env: winEnv, exists: set(WSL), run: wslRun({ list: ok(utf16(" NAME STATE VERSION\r\n OmniRushBox Running 2\r\n").toString("latin1")) }) });
+ expect(installed.ok).toBe(true);
+ });
+
+ test("distro box: Windows paths bound as /mnt/c into /c, commands as root without a shell", () => {
+ expect(inDistro({ distro: "OmniRushBox" }, ["/opt/omnirush/boxrun", "status"])).toEqual(["-d", "OmniRushBox", "-u", "root", "--cd", "/", "--exec", "/opt/omnirush/boxrun", "status"]);
+ const wslPath = (p: string) => `/mnt/${p[0]!.toLowerCase()}/${p.slice(3).replace(/\\/g, "/")}`;
+ const args = upArgs({ box: "/var/lib/omnirush/boxes/k", store: "/var/lib/omnirush/store", image: "id", boxd: "/opt/omnirush/boxd", portFile: "/mnt/c/Users/Sam/.omnirush/box/projects/k/boxd.port", root: "C:\\Users\\Sam\\proj", croot: "/c/Users/Sam/proj", runFolder: "C:\\Users\\Sam\\.omnirush\\box\\projects\\k", token: "t", platform: "win32", mapPath: wslPath });
+ expect(args).toContain("/mnt/c/Users/Sam/proj=/c/Users/Sam/proj");
+ expect(args).toContain("/mnt/c/Users/Sam/.omnirush/box/projects/k=/run/omnirush");
+ });
+
+ test("keeper: the first JSON line (UTF-16 or not) gives the port; the keeper stays as a child", async () => {
+ let spawnedArgs: string[] = [];
+ const kept = await startKeeper({ bin: WSL, distro: "OmniRushBox" }, ["up", "--box", "/var/lib/omnirush/boxes/k"], {
+ timeoutMs: 2_000,
+ spawnImpl: (_bin, args) => {
+ spawnedArgs = args;
+ const child = fakeChild();
+ setTimeout(() => child.stdout.emit("data", utf16('{"ok":true,"reused":false,"pid":41,"port":40123,"launcher":"unshare","overlay":"kernel"}\n')), 5);
+ return child;
+ },
+ });
+ expect(kept.ok).toBe(true);
+ if (kept.ok) expect(kept.out.port).toBe(40123);
+ expect(spawnedArgs.at(-1)).toBe("--foreground");
+ const bad = await startKeeper({ bin: WSL, distro: "OmniRushBox" }, ["up"], {
+ timeoutMs: 2_000,
+ spawnImpl: () => {
+ const child = fakeChild();
+ setTimeout(() => child.emit("close", 1), 5);
+ return child;
+ },
+ });
+ expect(bad.ok).toBe(false);
+ });
+
+ const WSLC = "C:\\Program Files\\WSL\\wslc.exe";
+
+ test("wslc: `wslc version` JSON or text; 3.0.1+ only; an older WSL gets the `wsl --update` hint, a missing one the enable hint", async () => {
+ expect(parseWslcVersion('{"Client":{"Version":"3.0.1.0"}}')).toBe("3.0.1.0");
+ expect(parseWslcVersion(utf16("wslc 3.0.2.0\r\n"))).toBe("3.0.2.0");
+ const good = await probeWslc({ platform: "win32", env: winEnv, exists: set(WSLC), run: async () => ok('{"Client":{"Version":"3.0.1.0"}}') });
+ expect(good).toMatchObject({ ok: true, version: "3.0.1.0", backend: "wslc", flavor: "wslc" });
+ const reason = (r: Awaited<ReturnType<typeof probeWslc>>) => (r.ok ? "" : r.reason);
+ expect(reason(await probeWslc({ platform: "win32", env: winEnv, exists: set(WSLC), run: async () => ok('{"Client":{"Version":"2.9.4.0"}}') }))).toMatch(/wsl --update/);
+ const oldWsl = await probeWslc({ platform: "win32", env: winEnv, exists: set(WSL), run: async (_bin, args) => (args[0] === "--version" ? ok(utf16("WSL version: 2.6.1.0\r\n").toString("latin1")) : fail("x")) });
+ expect(reason(oldWsl)).toBe(`${UPDATE_HINT}; this is WSL 2.6.1.0`);
+ expect(reason(await probeWslc({ platform: "win32", env: winEnv, exists: () => false, run: async () => fail("x") }))).toBe(ENABLE_HINT);
+ });
+
+ test("wslc: create args take the Windows path as the bind source, publish boxd on loopback, upper-case memory, no --init", () => {
+ const args = createWslcArgs({ name: "omnirush-box-k", key: "k", root: "C:\\Users\\Sam\\proj", croot: "/c/Users/Sam/proj", image: "ghcr.io/omnirush-ai/box-base:1", runFolder: "C:\\Users\\Sam\\.omnirush\\box\\projects\\k", token: "t", port: 50999, env: { OMNIRUSH_BOX_MEMORY: "4g" } });
+ expect(args.slice(0, 2)).toEqual(["container", "create"]);
+ expect(args).toContain("type=bind,source=C:\\Users\\Sam\\proj,target=/c/Users/Sam/proj");
+ expect(args).toContain("type=bind,source=C:\\Users\\Sam\\.omnirush\\box\\projects\\k\\bin,target=/opt/omnirush/bin,readonly");
+ expect(args).toContain("127.0.0.1:50999:7777");
+ expect(args[args.indexOf("-m") + 1]).toBe("4G");
+ expect(args).not.toContain("--init");
+ expect(args.at(-1)).toBe("ghcr.io/omnirush-ai/box-base:1");
+ });
+
+ test("wslc: list JSON (an array or one object per line), labels as a map or docker's string", () => {
+ const rows = [{ ID: "abc", Names: "omnirush-box-k", Image: "ghcr.io/omnirush-ai/box-base:1", State: "running", Labels: { "ai.omnirush.box": "1", "ai.omnirush.box.key": "k" }, Size: "57.2MB (virtual 1.1GB)" }];
+ expect(parseJsonRows(JSON.stringify(rows))).toEqual(rows);
+ expect(parseJsonRows(rows.map((r) => JSON.stringify(r)).join("\n"))).toEqual(rows);
+ expect(labelsOf("a=1,b=x=y")).toEqual({ a: "1", b: "x=y" });
+ });
+
+ test("ranking: wslc, then the OmniRush distro, then Docker Desktop", async () => {
+ const docker = "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe";
+ const desktop = { ServerVersion: "27.3.1", OSType: "linux", OperatingSystem: "Docker Desktop" };
+ const run: RunCommand = async (bin, args) => {
+ if (bin === WSLC) return ok('{"Client":{"Version":"3.0.1.0"}}');
+ if (bin === WSL) return wslRun()(bin, args);
+ if (args[0] === "context") return ok("");
+ return ok(desktop);
+ };
+ const env = { ...winEnv, OMNIRUSH_BOX_WSL_ROOTFS: "C:\\x.tar.gz" };
+ expect(await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSLC, WSL, docker), run, fresh: true })).toMatchObject({ backend: "wslc" });
+ const noWslc = await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSL, docker), run, fresh: true, all: true });
+ expect(noWslc).toMatchObject({ ok: true, backend: "wsl" });
+ expect(noWslc.alternatives?.find((a) => a.backend === "wslc")?.reason).toMatch(/wsl --update/);
+ expect(await detectBackend({ platform: "win32", home: "C:\\Users\\sam", env, exists: set(WSLC, WSL, docker), run, fresh: true, asked: "docker-desktop" })).toMatchObject({ backend: "docker-desktop" });
+ });
+});
+
+// --- the record, the upload label, the desktop status ----------------------------------------
+
+describe("box backends: record, label, status", () => {
+ test("record and label: the backend is named; boxsh gets no exec fallback where there is no exec", () => {
+ const home = tmp();
+ const runFolder = path.join(home, "projects", "k");
+ mkdirSync(runFolder, { recursive: true });
+ const run: RunCommand = async () => ok("");
+ const box = new Box({ key: "k", name: "omnirush-box-k", root: "/p", croot: "/p", runtime: { name: "bwrap", backend: "bwrap", bin: "/pkg/boxrun", version: "0.9.0", flavor: "overlayfs", rootless: true, arch: "amd64" }, home, runFolder, run, log: () => {}, platform: "linux", env: {} });
+ box.connect({ port: 5, token: "t", uid: 0, gid: 0, containerId: "bwrap_k_1", imageId: `sha256:${"e".repeat(64)}` });
+ box.writeRecord();
+ const rec = JSON.parse(readFileSync(path.join(home, "boxes", "k.json"), "utf8"));
+ expect({ backend: rec.backend, runtime: rec.runtime, args: rec.runtime_args }).toEqual({ backend: "bwrap", runtime: "", args: [] });
+ mkdirSync(path.join(home, "chains", "k"), { recursive: true });
+ writeFileSync(path.join(home, "chains", "k", "image.json"), JSON.stringify({ ref: "ghcr.io/omnirush-ai/box-base:2026.10.1", digest: `sha256:${"f".repeat(64)}`, stack: "base" }));
+ const label = box.label();
+ expect(label.backend).toBe("bwrap");
+ expect(label.image.digest).toBe(`sha256:${"f".repeat(64)}`);
+ const docker = new Box({ key: "d", name: "omnirush-box-d", root: "/p", croot: "/p", runtime: { name: "docker", backend: "docker-desktop", bin: "/usr/bin/docker", prefix: ["--context", "desktop-linux"] }, home, runFolder, run, log: () => {}, platform: "linux", env: {} });
+ docker.connect({ port: 6, token: "t", uid: 0, gid: 0, containerId: "c", imageId: "i" });
+ docker.writeRecord();
+ const drec = JSON.parse(readFileSync(path.join(home, "boxes", "d.json"), "utf8"));
+ expect({ backend: drec.backend, runtime: drec.runtime, args: drec.runtime_args }).toEqual({ backend: "docker-desktop", runtime: "/usr/bin/docker", args: ["--context", "desktop-linux"] });
+ });
+
+ test("files used read a non-container box through its exec (boxsh), not `docker exec`", async () => {
+ if (process.platform === "win32") return;
+ const dir = tmp();
+ const file = path.join(dir, "note.txt");
+ writeFileSync(file, "hello");
+ const view = sandboxFilesUsed({ container: "omnirush-box-k", manifest: { home: "/root", workspaces: [] }, cwd: dir, hostHome: null, docker: "/nonexistent/docker", exec: { bin: "/bin/sh", args: ["-c", 'exec "$0" "$@"'], env: { OMNIRUSH_BOX_KEY: "k" } } });
+ const facts = await view?.view.inspect([file], 1024);
+ expect(facts?.get(file)).toMatchObject({ kind: "file", size: 5 });
+ });
+
+ test("the settings card's status: the backend, its version and why, the others, the setting and its choices", async () => {
+ const stateDir = tmp();
+ const home = tmp();
+ const root = tmp();
+ const workspace: BoxWorkspace = { id: "ws_1", path: root, workspaceType: "local" };
+ const settings = new Map<string, { mode: "on" | "off" | null; offered: boolean }>([["ws_1", { mode: "on", offered: true }]]);
+ const env = { OMNIRUSH_BOX_HOME: home, OMNIRUSH_BOX_BIN_DIR: tmp(), PATH: "", OMNIRUSH_BOX_RUNTIME: "/nonexistent/docker" };
+ const boxes = new BoxService({
+ stateDir,
+ readSettings: async (id) => settings.get(id) ?? { mode: null, offered: false },
+ writeSettings: async () => {},
+ workspaces: () => [workspace],
+ pluginPath: () => "/plugins/omnirush-box.js",
+ env,
+ });
+ const status = await boxes.status(workspace, { fresh: true });
+ expect(status.backendSetting).toMatchObject({ value: "auto", source: "auto" });
+ expect(status.backendSetting.choices[0]).toEqual({ id: "auto", label: "Automatic" });
+ expect(status.backendSetting.choices.at(-1)?.id).toBe("native");
+ expect(status.backend).toMatchObject({ id: null, allowed: null });
+ expect(status.backend?.why).toBeTruthy();
+ expect(status.backend?.alternatives.every((alt) => typeof alt.id === "string" && typeof alt.ok === "boolean")).toBe(true);
+ expect(await boxes.setBackend("native")).toBe("native");
+ const native = await boxes.status(workspace, { fresh: true });
+ expect(native.backendSetting).toMatchObject({ value: "native", source: "setting" });
+ expect(native.state).toBe("unavailable");
+ await expect(boxes.setBackend("lxc")).rejects.toThrow(/unknown sandbox backend/);
+ rememberServerDefault(stateDir, { local_box: { default: "off", backends: ["podman"] } });
+ await boxes.setBackend("auto");
+ expect((await boxes.status(workspace, { fresh: true })).backend?.allowed).toEqual(["podman"]);
+ });
+});
diff --git a/apps/server/src/box/box-server.test.ts b/apps/server/src/box/box-server.test.ts
index fc1e586d..bf59dd97 100644
--- a/apps/server/src/box/box-server.test.ts
+++ b/apps/server/src/box/box-server.test.ts
@@ -133,7 +133,7 @@ describe("Linux sandbox through the server", () => {
expect(names).toEqual(expect.arrayContaining(["app.py", `__sandbox__/${sessionId}/record.json`, `__sandbox__/${sessionId}/turn-1.json`, `__sandbox__/${sessionId}/turn-1.tar`]));
expect(names).not.toContain(`__sandbox__/${sessionId}/.chain.json`);
- const label: BoxLabel = { kind: "omnirush-box", box_id: "box_abc", runtime: { name: "docker", flavor: "desktop", version: "27", rootless: false }, image: { ref: "r", digest: null, stack: "base" }, host_os: "darwin", host_arch: "arm64" };
+ const label: BoxLabel = { kind: "omnirush-box", box_id: "box_abc", backend: "docker-desktop", runtime: { name: "docker", flavor: "desktop", version: "27", rootless: false }, image: { ref: "r", digest: null, stack: "base" }, host_os: "darwin", host_arch: "arm64" };
const environment: UploadEnvironment = { os: "darwin", os_version: "24.0.0", arch: "arm64", app_version: "1", engine_version: "e", harness: { ...BUNDLED_HARNESS }, node_version: "24", shell: "zsh", locale: null, timezone: null, git_version: null };
expect(boxEnvironment(environment, label)).toEqual({ os: "linux", host_os: "darwin", host_arch: "arm64", host_os_version: "24.0.0", shell: "bash" });
expect(boxEnvironment(environment, null)).toEqual({});
diff --git a/apps/server/src/box/box.test.ts b/apps/server/src/box/box.test.ts
index 1458cee1..4be1368b 100644
--- a/apps/server/src/box/box.test.ts
+++ b/apps/server/src/box/box.test.ts
@@ -80,7 +80,8 @@ describe("box runtime", () => {
let calls = 0;
const run: RunCommand = async () => { calls += 1; return { code: 0, stdout: "{}", stderr: "" }; };
const result = await detectRuntime({ boxHome: home, platform: "linux", env: { PATH: "" }, exists: () => false, run, now: 1_000 });
- expect(result).toMatchObject({ ok: false, reason: "no container runtime found (install Podman or Docker)" });
+ // Linux ranks bubblewrap first: without boxrun it says so, and no container CLI is there either.
+ expect(result).toMatchObject({ ok: false, reason: "bwrap: the sandbox helper boxrun is missing from this install" });
expect(await detectRuntime({ boxHome: home, platform: "linux", env: { PATH: "" }, exists: () => false, run, now: 2_000 })).toMatchObject({ ok: false, cached: true });
expect(calls).toBe(0);
});
@@ -276,12 +277,16 @@ describe("box on Windows: a WSL engine (detected, never installed)", () => {
const winEnv = { Path: "C:\\Windows\\System32", SystemRoot: "C:\\Windows", ProgramFiles: "C:\\Program Files", LOCALAPPDATA: "C:\\Users\\sam\\AppData\\Local" };
const has = (...files: string[]) => (file: string) => files.includes(file);
- test("Docker Desktop is used when it is there (the WSL engine is not even asked)", async () => {
+ test("Docker Desktop is used when WSL is off (the WSL engine is not even asked)", async () => {
const asked: string[] = [];
- const run: RunCommand = async (bin, args) => { asked.push([bin, ...args].join(" ")); return { code: 0, stdout: JSON.stringify({ ServerVersion: "27.3.1", OSType: "linux", Architecture: "x86_64", OperatingSystem: "Docker Desktop" }), stderr: "" }; };
+ const run: RunCommand = async (bin, args) => {
+ asked.push([bin, ...args].join(" "));
+ if (bin === WSL) return { code: 1, stdout: "", stderr: "Windows Subsystem for Linux is not installed. You can install by running 'wsl.exe --install'." };
+ return { code: 0, stdout: JSON.stringify({ ServerVersion: "27.3.1", OSType: "linux", Architecture: "x86_64", OperatingSystem: "Docker Desktop" }), stderr: "" };
+ };
const found = await detectRuntime({ platform: "win32", home: "C:\\Users\\sam", env: winEnv, exists: has("C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe", WSL), run, fresh: true });
- expect(found).toMatchObject({ ok: true, flavor: "desktop" });
- expect(asked.some((line) => line.startsWith(WSL))).toBe(false);
+ expect(found).toMatchObject({ ok: true, flavor: "desktop", backend: "docker-desktop" });
+ expect(asked.some((line) => line.startsWith(`${WSL} -e`))).toBe(false);
});
test("without Docker Desktop: Docker in the default WSL distro, through wsl.exe", async () => {
diff --git a/apps/server/src/box/box.ts b/apps/server/src/box/box.ts
index 3aff65cd..1bc080e9 100644
--- a/apps/server/src/box/box.ts
+++ b/apps/server/src/box/box.ts
@@ -1,339 +1,53 @@
-// Ported from the CLI (omnirush-cli src/box/box.js, feat/local-box); keep the
-// two in step. Desktop differences, each marked "Desktop:": types; the
-// helpers' folder is the desktop's sidecars (setToolsRoot) and there is no
-// checkout box/bin fallback beyond OMNIRUSH_BOX_BIN_DIR; the shell link lives
-// in <home>/shell-desktop (the CLI's own is <home>/shell); a container-name
-// prefix override for test rigs (OMNIRUSH_BOX_CONTAINER_PREFIX).
+// Ported from the CLI (omnirush-cli src/box/box.js, feat/local-box-backends);
+// keep the two in step. Desktop differences, each marked "Desktop:": types;
+// what common.ts lists (the sidecars' helpers, the shell-desktop link, the
+// container-name prefix).
//
-// OmniRush box: one persistent Linux container per project, opt-in. The
-// engine, the app and the model calls stay on this machine; the engine's
-// shell tool runs in the box (boxsh -> boxd). The project folder is
-// bind-mounted at the same path (Windows: /c/Users/...), so the user's
-// editor, git and files stay as they are, and chat history stays in the
-// engine's one store. Installs live in the container, which survives
-// resume, restarts and new sessions until the user resets it.
+// OmniRush box: one persistent Linux box per project, opt-in. The engine,
+// the app and the model calls stay on this machine; the engine's shell tool
+// runs in the box (boxsh -> boxd). The project folder is mounted at the same
+// path (Windows: /c/Users/...), so the user's editor, git and files stay as
+// they are, and chat history stays in the engine's one store. Installs live
+// in the box, which survives resume, restarts and new sessions until the
+// user resets it.
//
-// Each turn's starting environment is a checkpoint of what the container
-// changed (`docker diff` against the image, then only what changed since
-// the session's previous checkpoint), written where the project archive
-// picks it up (<state>/sandbox/snapshots/<session>/turn-N.{json,tar}, the
-// same transport the 2.2.3 sandbox used; record schema 2).
+// What runs the box is a backend (backends/: bubblewrap, Apple container,
+// WSL containers, OmniRush's WSL distro, Docker, Podman and what speaks
+// their CLIs), chosen per machine by backends/index.ts. Every backend runs
+// the same boxd from the same pinned image, so a box is the same
+// environment everywhere.
+//
+// Each turn's starting environment is a checkpoint of what the box changed
+// (boxd's walk against the image index it took at the first start; a
+// container's `diff` as the fallback), then only what changed since the
+// session's previous checkpoint, written where the project archive picks it
+// up (<state>/sandbox/snapshots/<session>/turn-N.{json,tar}, the same
+// transport the 2.2.3 sandbox used; record schema 2).
import { createHash, randomBytes } from "node:crypto";
-import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import * as client from "./client.js";
import type { BoxEndpoint, BoxStat } from "./client.js";
+import { DEPS_MAX_BYTES, FILE_MAX_BYTES, HOME_IN_BOX, RECORD_SCHEMA, RUN_DIR, SHIMS_DIR, TAR_MAX_BYTES, boxHome, boxKey, containerName, containerRoot, firstLine, readJson, readRecord, recordFile, runDir, writeJson, type BoxInstallLog, type BoxLog, type BoxRecord, type BoxRuntime } from "./common.js";
+import { driverFor } from "./backends/index.js";
+import type { ListedBox, SpawnLike } from "./backends/types.js";
import { detectStack, imageFor, type BoxImage, type ImagePins } from "./images.js";
-import { runCommand, type RunCommand, type RunOptions, type RuntimeInfo } from "./runtime.js";
+import { runCommand, type RunCommand } from "./run.js";
type Env = NodeJS.ProcessEnv;
-export type BoxLog = (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
-
-export const RECORD_SCHEMA = 2;
-export const LABEL = "ai.omnirush.box";
-export const BOX_PORT = 7777;
-export const RUN_DIR = "/run/omnirush";
-export const SHIMS_DIR = "/opt/omnirush/pkglog";
-export const HOME_IN_BOX = "/root";
-/** One snapshot tar past this is cut (system paths first, then dependency folders). */
-export const TAR_MAX_BYTES = 256 * 1024 * 1024;
-/** A single file past this is left out of a snapshot (listed with its size). */
-export const FILE_MAX_BYTES = 128 * 1024 * 1024;
-/** Project dependency folders (node_modules, .venv) go into a turn's snapshot up to this. */
-export const DEPS_MAX_BYTES = 128 * 1024 * 1024;
-
-// --- where things are ------------------------------------------------------
-
-export function boxHome(env: Env = process.env, home = os.homedir()): string {
- return path.resolve(String(env.OMNIRUSH_BOX_HOME || "").trim() || path.join(home, ".omnirush", "box"));
-}
-
-/** The canonical form of a project folder (the box key hashes it). */
-export function canonicalRoot(root: string, { platform = process.platform, realpath = realpathSync.native }: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {
- let resolved = path.resolve(root);
- try { resolved = realpath(resolved); } catch { /* keep */ }
- return platform === "win32" ? resolved.toLowerCase() : resolved;
-}
-export function boxKey(root: string, opts: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {
- return createHash("sha256").update(canonicalRoot(root, opts)).digest("hex").slice(0, 12);
-}
-
-/** Desktop: OMNIRUSH_BOX_CONTAINER_PREFIX renames the containers (test rigs on shared machines). */
-export function containerName(key: string, env: Env = process.env): string {
- const prefix = String(env.OMNIRUSH_BOX_CONTAINER_PREFIX || "").trim();
- return `${/^[a-z0-9][a-z0-9_.-]*$/.test(prefix) ? prefix : "omnirush-box-"}${key}`;
-}
-
-/** Where the project folder is inside: the same path; on Windows C:\x\y -> /c/x/y. */
-export function containerRoot(root: string, platform: NodeJS.Platform = process.platform): string {
- if (platform !== "win32") return root;
- const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(root);
- if (!match) return `/w/${root.replace(/[\\]+/g, "/").replace(/^\/+/, "")}`;
- return `/${match[1]!.toLowerCase()}/${match[2]!.replace(/[\\]+/g, "/")}`.replace(/\/+$/, "") || "/";
-}
+export { BOX_PORT, DEPS_MAX_BYTES, FILE_MAX_BYTES, GOARCH, GOOS, HOME_IN_BOX, LABEL, RECORD_SCHEMA, RUN_DIR, SHIMS_DIR, TAR_MAX_BYTES, boxHome, boxKey, canonicalRoot, containerName, containerRoot, helperDirs, helperPath, installShell, readRecord, recordFile, runDir, setToolsRoot, wslPath, type BoxInstallLog, type BoxLog, type BoxRecord, type BoxRuntime } from "./common.js";
+export { commandUser, createArgs, inspectImage, parseSize, pullImage, resourceArgs, rt, singleFileTar } from "./backends/container.js";
+export type { ListedBox } from "./backends/types.js";
/** Where the server saves each chat's turn checkpoints (the project archive carries them: session-archive/index.ts). */
export function boxSnapshotsDir(stateDir: string): string {
return path.join(stateDir, "sandbox", "snapshots");
}
-export function recordFile(home: string, key: string): string {
- return path.join(home, "boxes", `${key}.json`);
-}
-
-export function runDir(home: string, key: string): string {
- return path.join(home, "projects", key);
-}
-
-function writeJson(file: string, value: unknown, mode = 0o600): void {
- mkdirSync(path.dirname(file), { recursive: true });
- const tmp = `${file}.${process.pid}.${randomBytes(3).toString("hex")}.tmp`;
- writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });
- renameSync(tmp, file);
-}
-
-function readJson<T = Record<string, unknown>>(file: string): T | null {
- try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
-}
-
-/** The record boxsh reads (boxes/<key>.json). */
-export type BoxRecord = {
- v: 1; key: string; root: string; croot: string; container: string; runtime: string; runtime_args: string[];
- host: string; port: number; token: string; state: string; error: string; uid: number; gid: number;
- home: string; shell: string; path_prefix: string; env_file: string; updated: number; pid: number;
-};
-
-export function readRecord(home: string, key: string): BoxRecord | null {
- return readJson<BoxRecord>(recordFile(home, key));
-}
-
-// --- helper binaries ---------------------------------------------------------
-
-export const GOOS: Partial<Record<string, string>> = { linux: "linux", darwin: "darwin", win32: "windows" };
-export const GOARCH: Partial<Record<string, string>> = { x64: "amd64", arm64: "arm64", amd64: "amd64", aarch64: "arm64" };
-
-/**
- * Folders holding the helpers, best first: OMNIRUSH_BOX_BIN_DIR, then the
- * desktop's sidecars folder's box/ (setToolsRoot). Each has
- * <goos>-<goarch>/boxsh and linux-<arch>/boxd.
- */
-export function helperDirs({ env = process.env, toolsRoot = null }: { env?: Env; toolsRoot?: string | null } = {}): string[] {
- const asked = String(env.OMNIRUSH_BOX_BIN_DIR || "").trim();
- return [...(asked ? [asked] : []), ...(toolsRoot ? [path.join(toolsRoot, "box")] : [])];
-}
-
-// Desktop: the sidecars folder (the engine binary's folder), set by the server at start.
-let platformTools: string | null = null;
-export function setToolsRoot(dir: string | null | undefined): void {
- platformTools = dir || null;
-}
-
-/** The helper's file, or null when no folder has it (the box is then unavailable). */
-export function helperPath(name: string, { goos, goarch, env = process.env, toolsRoot = platformTools }: { goos: string | undefined; goarch: string | undefined; env?: Env; toolsRoot?: string | null }): string | null {
- if (!goos || !goarch) return null;
- const ext = goos === "windows" && name === "boxsh" ? ".exe" : "";
- const rel = path.join(`${goos}-${goarch}`, name + ext);
- return helperDirs({ env, toolsRoot }).map((dir) => path.join(dir, rel)).find((file) => existsSync(file)) ?? null;
-}
-
-/**
- * The shell file the engine is given: a link (Windows: a copy) named `bash`
- * to boxsh, so the engine describes its shell tool as bash.
- */
-export function installShell(home: string, { platform = process.platform, arch = process.arch, env = process.env }: { platform?: NodeJS.Platform; arch?: string; env?: Env } = {}): string {
- const source = helperPath("boxsh", { goos: GOOS[platform], goarch: GOARCH[arch], env });
- if (!source) throw new Error(`the sandbox shell helper is missing (${GOOS[platform] ?? platform}-${GOARCH[arch] ?? arch}/boxsh)`);
- const dir = path.join(home, "shell-desktop");
- mkdirSync(dir, { recursive: true });
- const target = path.join(dir, platform === "win32" ? "bash.exe" : "bash");
- if (platform === "win32") {
- let same = false;
- try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }
- if (!same) {
- const tmp = `${target}.${process.pid}.tmp`;
- copyFileSync(source, tmp);
- try { renameSync(tmp, target); } catch { rmSync(tmp, { force: true }); }
- }
- return target;
- }
- let current: string | null = null;
- try { current = lstatSync(target).isSymbolicLink() ? path.resolve(dir, readlinkSync(target)) : null; } catch { /* missing */ }
- if (current !== source) {
- const tmp = `${target}.${process.pid}.tmp`;
- rmSync(tmp, { force: true });
- symlinkSync(source, tmp);
- renameSync(tmp, target);
- }
- return target;
-}
-
-/**
- * A tar with one executable file at `name` (and its folders), for `cp - <c>:/`:
- * `cp <file> <c>:<path>` needs the folder to exist in the image already.
- */
-export function singleFileTar(name: string, data: Buffer, mode = 0o755): Buffer {
- const blocks: Buffer[] = [];
- const header = (entry: string, type: string, size: number, entryMode: number) => {
- const h = Buffer.alloc(512);
- h.write(entry, 0, 100, "utf8");
- h.write(`${entryMode.toString(8).padStart(7, "0")}\0`, 100);
- h.write("0000000\0", 108);
- h.write("0000000\0", 116);
- h.write(`${size.toString(8).padStart(11, "0")}\0`, 124);
- h.write(`${Math.floor(Date.now() / 1000).toString(8).padStart(11, "0")}\0`, 136);
- h.write(" ", 148);
- h.write(type, 156);
- h.write("ustar\0", 257);
- h.write("00", 263);
- let sum = 0;
- for (const byte of h) sum += byte;
- h.write(`${sum.toString(8).padStart(6, "0")}\0 `, 148);
- return h;
- };
- const parts = name.split("/");
- for (let i = 1; i < parts.length; i += 1) blocks.push(header(`${parts.slice(0, i).join("/")}/`, "5", 0, 0o755));
- blocks.push(header(name, "0", data.length, mode));
- blocks.push(data, Buffer.alloc((512 - (data.length % 512)) % 512), Buffer.alloc(1024));
- return Buffer.concat(blocks);
-}
-
-// --- the runtime CLI ------------------------------------------------------------
-
-export type BoxRuntime = Pick<RuntimeInfo, "name" | "bin"> & Partial<Pick<RuntimeInfo, "version" | "flavor" | "rootless" | "arch" | "vm" | "prefix" | "wsl">>;
-
-/** Runs the runtime's CLI (`wsl.exe -e docker ...` for a WSL engine). */
-export function rt(runtime: BoxRuntime, run: RunCommand = runCommand) {
- const prefix = Array.isArray(runtime.prefix) ? runtime.prefix : [];
- return (args: string[], opts: RunOptions = {}) => run(runtime.bin, [...prefix, ...args], { timeoutMs: 60_000, ...opts });
-}
-
-/** A Windows path as a WSL engine mounts it: C:\x\y -> /mnt/c/x/y. */
-export function wslPath(p: string): string {
- const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(String(p));
- if (!match) return String(p).replace(/\\/g, "/");
- return `/mnt/${match[1]!.toLowerCase()}/${match[2]!.replace(/\\/g, "/")}`.replace(/\/+$/, "");
-}
-
-/** Where the runtime finds a folder of this machine (a WSL engine sees Windows drives under /mnt). */
-function source(runtime: BoxRuntime, p: string): string {
- return runtime.wsl ? wslPath(p) : p;
-}
-
-/** Whether `image` is present locally; its id and repo digest when it is. */
-export async function inspectImage(runtime: BoxRuntime, image: string, { run = runCommand }: { run?: RunCommand } = {}): Promise<{ id: string; digest: string | null; arch: string; size: number } | null> {
- const res = await rt(runtime, run)(["image", "inspect", image, "--format", "{{json .}}"], { timeoutMs: 20_000 });
- if (res.code !== 0) return null;
- try {
- const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");
- const digests: unknown[] = Array.isArray(info.RepoDigests) ? info.RepoDigests : [];
- const digest = digests.map((entry) => String(entry).split("@")[1]).find((d) => /^sha256:[0-9a-f]{64}$/.test(d || "")) || null;
- return { id: String(info.Id || ""), digest, arch: String(info.Architecture || ""), size: Number(info.Size || 0) };
- } catch {
- return null;
- }
-}
-
-/** `pull` with retries (a flaky link picks up where it stopped). */
-export async function pullImage(runtime: BoxRuntime, image: string, { run = runCommand, pauses = [2_000, 8_000], timeoutMs = 60 * 60_000, sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)) }: { run?: RunCommand; pauses?: number[]; timeoutMs?: number; sleep?: (ms: number) => Promise<unknown> } = {}): Promise<{ ok: true; attempts: number } | { ok: false; error: string }> {
- let last = null;
- for (let attempt = 0; attempt <= pauses.length; attempt += 1) {
- last = await rt(runtime, run)(["pull", image], { timeoutMs });
- if (last.code === 0) return { ok: true, attempts: attempt + 1 };
- if (attempt < pauses.length) await sleep(pauses[attempt]!);
- }
- const said = String(last?.stderr || "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) || `pull exited with ${last?.code}`;
- return { ok: false, error: said.slice(0, 300) };
-}
-
-type ContainerInfo = { id: string; running: boolean; image: string; labels: Record<string, string>; env: string[]; mounts: string[] };
-
-async function inspectContainer(runtime: BoxRuntime, name: string, run: RunCommand): Promise<ContainerInfo | null> {
- const res = await rt(runtime, run)(["container", "inspect", name, "--format", "{{json .}}"], { timeoutMs: 20_000 });
- if (res.code !== 0) return null;
- try {
- const info = JSON.parse(res.stdout.trim().split("\n")[0] ?? "");
- return {
- id: String(info.Id || ""),
- running: Boolean(info.State?.Running),
- image: String(info.Image || ""),
- labels: info.Config?.Labels ?? {},
- env: Array.isArray(info.Config?.Env) ? info.Config.Env : [],
- mounts: Array.isArray(info.Mounts) ? info.Mounts.map((mount: { Destination?: unknown }) => String(mount.Destination ?? "")) : [],
- };
- } catch {
- return null;
- }
-}
-
-/** The host port boxd is published on. */
-async function publishedPort(runtime: BoxRuntime, name: string, run: RunCommand): Promise<number | null> {
- const res = await rt(runtime, run)(["port", name, `${BOX_PORT}/tcp`], { timeoutMs: 15_000 });
- if (res.code !== 0) return null;
- for (const line of res.stdout.split("\n")) {
- const match = /:(\d+)\s*$/.exec(line.trim());
- if (match) return Number(match[1]);
- }
- return null;
-}
-
-/** Resource limits a new box gets (a VM runtime has its own; only the process cap then). */
-export function resourceArgs({ runtime, env = process.env, cpus = os.cpus().length, memory = os.totalmem() }: { runtime: BoxRuntime; env?: Env; cpus?: number; memory?: number }): string[] {
- const args = ["--pids-limit", String(Number(env.OMNIRUSH_BOX_PIDS) || 4096)];
- const askedCpus = Number(env.OMNIRUSH_BOX_CPUS);
- const askedMem = String(env.OMNIRUSH_BOX_MEMORY || "").trim();
- if (askedCpus > 0) args.push("--cpus", String(askedCpus));
- else if (!runtime.vm) args.push("--cpus", String(Math.max(1, Math.min(8, cpus - 1))));
- if (askedMem) args.push("--memory", askedMem);
- else if (!runtime.vm) {
- const gib = Math.max(2, Math.min(8, Math.floor(memory / 2 / 1024 ** 3)));
- args.push("--memory", `${gib}g`);
- }
- return args;
-}
-
-/** Who commands run as: root where root maps to the user (rootless, VMs), else the user's own uid. */
-export function commandUser(runtime: BoxRuntime, { platform = process.platform, uid = process.getuid?.(), gid = process.getgid?.() }: { platform?: NodeJS.Platform; uid?: number; gid?: number } = {}): { uid: number; gid: number } {
- if (platform !== "linux" || runtime.rootless || runtime.vm || uid === undefined || gid === undefined || uid === 0) return { uid: 0, gid: 0 };
- return { uid, gid };
-}
-
-/**
- * Create a box container (not started): the project folder at `croot`, the
- * launcher's run folder at /run/omnirush, the package-manager wrappers (when
- * there are) read-only, boxd published on this machine's loopback only.
- * Nothing else of this machine goes in: no home folder, no credentials, no
- * docker socket.
- */
-/** The install log (phase 1): its folder, the wrappers' folder and the pip hook's, all on this machine. */
-export type BoxInstallLog = { root: string; bin: string; py: string };
-
-export function createArgs({ name, key, root, croot, image, runtime, run: runFolder, shims, pkglog = null, token, user, env = process.env, platform = process.platform }: { name: string; key: string; root: string; croot: string; image: string; runtime: BoxRuntime; run: string; shims: string | null; pkglog?: BoxInstallLog | null; token: string; user: { uid: number; gid: number }; env?: Env; platform?: NodeJS.Platform }): string[] {
- return [
- "create", "--name", name, "--hostname", "omnirush-box", "--init",
- "--label", `${LABEL}=1`, "--label", `${LABEL}.key=${key}`, "--label", `${LABEL}.root=${root}`, "--label", `${LABEL}.version=1`,
- "--mount", `type=bind,source=${source(runtime, root)},target=${croot}`,
- "--mount", `type=bind,source=${source(runtime, runFolder)},target=${RUN_DIR}`,
- ...(shims ? ["--mount", `type=bind,source=${source(runtime, shims)},target=${SHIMS_DIR}-src,readonly`] : []),
- // The install log's folder (phase 1: its wrappers, pip hook and the per-run folders the
- // wrappers note calls in), at the path the launcher reads it at.
- ...(pkglog ? ["--mount", `type=bind,source=${source(runtime, pkglog.root)},target=${containerRoot(pkglog.root, platform)}`] : []),
- "-p", `127.0.0.1::${BOX_PORT}`,
- "-e", `BOXD_TOKEN=${token}`, "-e", `BOXD_UID=${user.uid}`, "-e", `BOXD_GID=${user.gid}`,
- "-e", `BOXD_HOME=${HOME_IN_BOX}`, "-e", `BOXD_ROOT=${croot}`, "-e", `BOXD_ENV_FILE=${RUN_DIR}/env`,
- "-e", "LANG=C.UTF-8", "-e", "DEBIAN_FRONTEND=noninteractive",
- "-w", croot,
- ...resourceArgs({ runtime, env }),
- ...(runtime.name === "podman" ? ["--security-opt", "label=disable"] : []),
- ...(user.uid === 0 ? ["--security-opt", "no-new-privileges"] : []),
- "--entrypoint", "/opt/omnirush/bin/boxd",
- image,
- ];
-}
-
// --- snapshot rules -------------------------------------------------------------
const H = HOME_IN_BOX;
@@ -478,12 +192,12 @@ export type BoxState = "starting" | "pulling" | "ready" | "failed";
type OnState = (state: BoxState, error: string | null) => void;
/**
- * Open (create or start) the project's box. Returns a Box. `onState` sees
- * "starting", "pulling", "ready", "failed" (the record boxsh reads says the
- * same). Throws only for programming errors; a box that cannot start is a
- * Box with state "failed" and `error`.
+ * Open (create or start) the project's box with the runtime's backend.
+ * Returns a Box. `onState` sees "starting", "pulling", "ready", "failed"
+ * (the record boxsh reads says the same). Throws only for programming
+ * errors; a box that cannot start is a Box with state "failed" and `error`.
*/
-export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = null, pkglog = null, pull = true, image: asked = null, onState = () => {} }: { root: string; runtime: BoxRuntime; env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand; log?: BoxLog; shims?: string | null; pkglog?: BoxInstallLog | null; pull?: boolean; image?: BoxImage | null; onState?: OnState }): Promise<Box> {
+export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = null, pkglog = null, pull = true, image: asked = null, onState = () => {}, spawnImpl, readyMs = 15_000 }: { root: string; runtime: BoxRuntime; env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand; log?: BoxLog; shims?: string | null; pkglog?: BoxInstallLog | null; pull?: boolean; image?: BoxImage | null; onState?: OnState; spawnImpl?: SpawnLike; readyMs?: number }): Promise<Box> {
const projectRoot = path.resolve(root);
const key = boxKey(projectRoot, { platform });
const name = containerName(key, env);
@@ -491,63 +205,31 @@ export async function openBox({ root, runtime, env = process.env, platform = pro
const runFolder = runDir(home, key);
mkdirSync(path.join(runFolder, "state"), { recursive: true });
const box = new Box({ key, name, root: projectRoot, croot, runtime, home, runFolder, run, log, platform, env });
+ const driver = driverFor(runtime);
const lock = await acquireLock(home, key);
try {
box.setState("starting", null, onState);
- let info = await inspectContainer(runtime, name, run);
- if (info && info.labels?.[`${LABEL}.root`] && info.labels[`${LABEL}.root`] !== projectRoot) {
- throw new Error(`container ${name} belongs to another folder`);
- }
- if (!info) {
- const chosen = asked ?? imageFor(detectStack(projectRoot), { env });
- let present = await inspectImage(runtime, chosen.pull, { run });
- if (!present) {
- if (!pull) return box.fail("the sandbox image is not downloaded yet", onState);
- box.setState("pulling", null, onState);
- const pulled = await pullImage(runtime, chosen.pull, { run });
- if (!pulled.ok) return box.fail(`could not download the sandbox image: ${pulled.error}`, onState);
- present = await inspectImage(runtime, chosen.pull, { run });
- if (!present) return box.fail("the sandbox image is not there after the download", onState);
- }
- const goarch = GOARCH[present.arch] || GOARCH[runtime.arch ?? ""] || "amd64";
- const boxd = helperPath("boxd", { goos: "linux", goarch, env });
- if (!boxd) return box.fail(`the sandbox helper is missing (linux-${goarch}/boxd)`, onState);
- const token = randomBytes(24).toString("hex");
- const user = commandUser(runtime, { platform });
- const created = await rt(runtime, run)(createArgs({ name, key, root: projectRoot, croot, image: chosen.pull, runtime, run: runFolder, shims, pkglog, token, user, env, platform }), { timeoutMs: 120_000 });
- if (created.code !== 0) return box.fail(`could not create the sandbox: ${firstLine(created.stderr)}`, onState);
- const copied = await rt(runtime, run)(["cp", "-", `${name}:/`], { timeoutMs: 60_000, input: singleFileTar("opt/omnirush/bin/boxd", readFileSync(boxd)) });
- if (copied.code !== 0) {
- await rt(runtime, run)(["rm", "-f", name], { timeoutMs: 30_000 });
- return box.fail(`could not copy the sandbox helper in: ${firstLine(copied.stderr)}`, onState);
- }
- writeJson(path.join(home, "chains", key, "image.json"), { ref: chosen.ref, pull: chosen.pull, digest: chosen.digest || present.digest, id: present.id, stack: chosen.stack, created_at: new Date().toISOString() });
- info = await inspectContainer(runtime, name, run);
- if (!info) return box.fail("the sandbox was not there after it was created", onState);
- log("info", "box created", { key, image: chosen.pull, stack: chosen.stack });
- }
- if (!info.running) {
- const started = await rt(runtime, run)(["start", name], { timeoutMs: 60_000 });
- if (started.code !== 0) return box.fail(`could not start the sandbox: ${firstLine(started.stderr)}`, onState);
- }
- const token = (info.env.find((kv) => kv.startsWith("BOXD_TOKEN=")) || "").slice("BOXD_TOKEN=".length);
- const uid = Number((info.env.find((kv) => kv.startsWith("BOXD_UID=")) || "BOXD_UID=0").slice(9));
- const gid = Number((info.env.find((kv) => kv.startsWith("BOXD_GID=")) || "BOXD_GID=0").slice(9));
- const port = await publishedPort(runtime, name, run);
- if (!port || !token) return box.fail("the sandbox started without its port", onState);
- box.connect({ port, token, uid, gid, containerId: info.id, imageId: info.image });
- const endpoint = box.endpoint!;
- const deadline = Date.now() + 15_000;
+ const chosen = asked ?? imageFor(detectStack(projectRoot), { env });
+ const opened = await driver.open({ key, name, root: projectRoot, croot, runtime, run, home, runFolder, image: chosen, pull, shims, pkglog, env, platform, log, ...(spawnImpl ? { spawnImpl } : {}), onPulling: () => box.setState("pulling", null, onState) });
+ if (!opened.ok) return box.fail(opened.error, onState);
+ if (opened.created) writeJson(path.join(home, "chains", key, "image.json"), { ...opened.created, backend: runtime.backend ?? runtime.name, created_at: new Date().toISOString() });
+ // The first address that answers: the published/loopback one, then the box's own (Apple, WSL any).
+ const ways = [opened.endpoint, ...(opened.alternates ?? [])];
let identity = null;
- while (!identity && Date.now() < deadline) {
- identity = await client.ping(endpoint, { timeoutMs: 1_000 });
- if (!identity) await new Promise((resolve) => setTimeout(resolve, 100));
+ for (let i = 0; i < ways.length && !identity; i += 1) {
+ box.connect({ ...ways[i]!, uid: opened.uid, gid: opened.gid, containerId: opened.containerId, imageId: opened.imageId });
+ const endpoint = box.endpoint!;
+ const deadline = Date.now() + (i === ways.length - 1 ? readyMs : Math.min(readyMs, 5_000));
+ while (!identity && Date.now() < deadline) {
+ identity = await client.ping(endpoint, { timeoutMs: 1_000 });
+ if (!identity) await new Promise((resolve) => setTimeout(resolve, 50));
+ }
}
if (!identity) return box.fail("the sandbox helper did not answer", onState);
box.identity = identity;
if (shims) await box.installShims().catch((error) => log("warn", "box wrappers not installed", { error: String(error?.message || error) }));
else if (pkglog) {
- if (info.mounts.includes(containerRoot(pkglog.root, platform))) box.useInstallLog(pkglog);
+ if (opened.mounts.includes(containerRoot(pkglog.root, platform))) box.useInstallLog(pkglog);
else log("info", "box made before the install log: its wrappers are not in this box (Reset sandbox adds them)", { key });
}
box.setState("ready", null, onState);
@@ -559,10 +241,6 @@ export async function openBox({ root, runtime, env = process.env, platform = pro
}
}
-function firstLine(text: unknown): string {
- return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean)?.slice(0, 300) ?? "";
-}
-
async function acquireLock(home: string, key: string, { waitMs = 60_000 }: { waitMs?: number } = {}): Promise<{ release: () => void }> {
const file = path.join(home, "locks", `${key}.lock`);
mkdirSync(path.dirname(file), { recursive: true });
@@ -615,6 +293,8 @@ type Chain = { container: string; last: string | null; signatures: Record<string
export type BoxLabel = {
kind: string;
box_id: string;
+ /** The backend id (backends/index.ts BACKENDS). */
+ backend: string;
runtime: { name: string; flavor: string; version: string | null; rootless: boolean };
image: { ref: string | null; digest: string | null; stack: string | null };
host_os: string;
@@ -662,8 +342,8 @@ export class Box {
this.container = name;
}
- connect({ port, token, uid, gid, containerId, imageId }: { port: number; token: string; uid: number; gid: number; containerId: string; imageId: string }): void {
- this.endpoint = { host: "127.0.0.1", port, token };
+ connect({ host = "127.0.0.1", port, token, uid, gid, containerId, imageId }: BoxEndpoint & { uid: number; gid: number; containerId: string; imageId: string }): void {
+ this.endpoint = { host, port, token };
this.uid = uid;
this.gid = gid;
this.containerId = containerId;
@@ -672,8 +352,11 @@ export class Box {
/** The record boxsh reads (boxes/<key>.json). */
writeRecord(): void {
+ const fallback = driverFor(this.runtime).execFallback;
const record: BoxRecord = {
- v: 1, key: this.key, root: this.root, croot: this.croot, container: this.name, runtime: this.runtime?.bin ?? "", runtime_args: this.runtime?.prefix ?? [],
+ v: 1, key: this.key, root: this.root, croot: this.croot, container: this.name, backend: this.runtime.backend ?? this.runtime.name ?? "",
+ // boxsh's fallback when boxd does not answer: `<runtime> exec` (container engines and wslc only).
+ runtime: fallback ? this.runtime.bin ?? "" : "", runtime_args: fallback ? this.runtime.prefix ?? [] : [],
host: this.endpoint?.host ?? "127.0.0.1", port: this.endpoint?.port ?? 0, token: this.endpoint?.token ?? "",
state: this.state, error: this.error ?? "", uid: this.uid ?? 0, gid: this.gid ?? 0, home: HOME_IN_BOX, shell: "/bin/bash",
path_prefix: this.pathPrefix, env_file: `${RUN_DIR}/env`, updated: Date.now(), pid: process.pid,
@@ -754,6 +437,7 @@ export class Box {
schema: RECORD_SCHEMA,
kind: "omnirush-box",
box: { id: `box_${this.key}`, container: this.name, created_at: image.created_at ?? null },
+ backend: this.runtime.backend ?? this.runtime.name,
runtime: { name: this.runtime.name, version: this.runtime.version ?? null, flavor: this.runtime.flavor ?? "unknown", rootless: Boolean(this.runtime.rootless), os: "linux", arch: this.runtime.arch || null },
image: { ref: image.ref ?? null, digest: image.digest ?? null, id: image.id ?? this.imageId ?? null, stack: image.stack ?? null },
host: { os: this.platform, arch: process.arch, os_version: os.release() },
@@ -767,7 +451,7 @@ export class Box {
/** The block trace envelopes carry as environment.sandbox. */
label(): BoxLabel {
const d = this.describe();
- return { kind: d.kind, box_id: d.box.id, runtime: { name: d.runtime.name, flavor: d.runtime.flavor, version: d.runtime.version, rootless: d.runtime.rootless }, image: { ref: d.image.ref, digest: d.image.digest, stack: d.image.stack }, host_os: d.host.os, host_arch: d.host.arch };
+ return { kind: d.kind, box_id: d.box.id, backend: d.backend, runtime: { name: d.runtime.name, flavor: d.runtime.flavor, version: d.runtime.version, rootless: d.runtime.rootless }, image: { ref: d.image.ref, digest: d.image.digest, stack: d.image.stack }, host_os: d.host.os, host_arch: d.host.arch };
}
/** Run a command in the box (toolchain probes, status). */
@@ -812,7 +496,9 @@ export class Box {
stats = walked.filter((entry) => entry.kind !== "D" && keptPaths.has(entry.path));
} else {
source = "diff";
- const diff = await rt(this.runtime, this.run)(["diff", this.name], { timeoutMs: 120_000, maxBytes: 256 << 20 });
+ const driver = driverFor(this.runtime);
+ if (!driver.diff) throw new Error("the sandbox helper could not list the changes");
+ const diff = await driver.diff(this.runtime, this.key, { run: this.run, home: this.home, env: this.env });
if (diff.code !== 0) throw new Error(`diff failed: ${firstLine(diff.stderr)}`);
entries = filterChanges(parseDiff(diff.stdout), { mounts });
const present = entries.filter((entry) => entry.kind !== "D").map((entry) => entry.path);
@@ -928,83 +614,61 @@ export class Box {
};
}
- /** Disk the container's own layer uses (bytes), when the runtime says. */
- async upperBytes(): Promise<number | null> {
- const res = await rt(this.runtime, this.run)(["ps", "-a", "-s", "--filter", `name=^/?${this.name}$`, "--format", "{{.Size}}"], { timeoutMs: 30_000 });
- return parseSize(res.stdout);
+ /** Disk the box's own layer uses (bytes), when the backend says. */
+ upperBytes(): Promise<number | null> {
+ return driverFor(this.runtime).upperBytes(this.runtime, this.key, { run: this.run, home: this.home, env: this.env });
}
}
-/** "57.2MB (virtual 1.1GB)" -> bytes of the first number. */
-export function parseSize(text: string): number | null {
- const match = /([\d.]+)\s*([kKMGT]?i?B)/.exec(String(text));
- if (!match) return null;
- const unit = match[2]!.replace(/i/, "").toUpperCase();
- const mult = ({ B: 1, KB: 1e3, MB: 1e6, GB: 1e9, TB: 1e12 } as Record<string, number>)[unit] ?? 1;
- return Math.round(Number(match[1]) * mult);
-}
-
// --- status, reset, gc --------------------------------------------------------------
-export type ListedBox = { key: string; name: string; root: string; running: boolean; image: string; created: string };
+type Removed = Array<{ kind: string; name: string; reason: string }>;
/** Boxes on this machine: { key, name, root, running, image, created }[] */
-export async function listBoxes(runtime: BoxRuntime, { run = runCommand }: { run?: RunCommand } = {}): Promise<ListedBox[]> {
- const res = await rt(runtime, run)(["ps", "-a", "--filter", `label=${LABEL}=1`, "--format", "{{json .}}"], { timeoutMs: 30_000 });
- if (res.code !== 0) return [];
- const out: ListedBox[] = [];
- for (const line of res.stdout.split("\n")) {
- if (!line.trim()) continue;
- try {
- const row = JSON.parse(line);
- const labels: Record<string, string> = typeof row.Labels === "string"
- ? Object.fromEntries(row.Labels.split(",").map((kv: string) => { const i = kv.indexOf("="); return [kv.slice(0, i), kv.slice(i + 1)]; }))
- : (row.Labels ?? {});
- const name = Array.isArray(row.Names) ? row.Names[0] : String(row.Names ?? "");
- out.push({ key: labels[`${LABEL}.key`] ?? "", name, root: labels[`${LABEL}.root`] ?? "", running: /^up|running/i.test(String(row.Status ?? row.State ?? "")), image: String(row.Image ?? ""), created: String(row.CreatedAt ?? row.Created ?? "") });
- } catch { /* skip */ }
- }
- return out;
+export async function listBoxes(runtime: BoxRuntime, { run = runCommand, env = process.env, home = boxHome(env) }: { run?: RunCommand; env?: Env; home?: string } = {}): Promise<ListedBox[]> {
+ return driverFor(runtime).list(runtime, { run, env, home });
}
/** Remove a project's box (the next start makes a new one). */
export async function resetBox(runtime: BoxRuntime, root: string, { env = process.env, platform = process.platform, home = boxHome(env), run = runCommand }: { env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand } = {}): Promise<{ key: string; removed: boolean }> {
const key = boxKey(root, { platform });
- const res = await rt(runtime, run)(["rm", "-f", containerName(key, env)], { timeoutMs: 60_000 });
+ const res = await driverFor(runtime).remove(runtime, key, { run, env, home });
rmSync(recordFile(home, key), { force: true });
rmSync(path.join(home, "chains", key), { recursive: true, force: true });
- return { key, removed: res.code === 0 };
+ return { key, removed: Boolean(res.removed) };
+}
+
+/** Stop a project's box (its installs stay; the next chat starts it again). */
+export async function stopBox(runtime: BoxRuntime, root: string, { env = process.env, platform = process.platform, home = boxHome(env), run = runCommand }: { env?: Env; platform?: NodeJS.Platform; home?: string; run?: RunCommand } = {}): Promise<{ key: string; stopped: boolean }> {
+ const key = boxKey(root, { platform });
+ return { key, ...(await driverFor(runtime).stop(runtime, key, { run, env, home })) };
}
/**
* Remove boxes whose folder is gone or that were not used for `maxIdleDays`,
- * and box images no box uses that are not the current pins. Only containers
- * and images labelled/named as OmniRush boxes are touched; nothing is pruned.
+ * and box images no box uses that are not the current pins. Only boxes and
+ * images labelled/named as OmniRush boxes are touched; nothing is pruned.
*/
-export async function gcBoxes(runtime: BoxRuntime, { env = process.env, home = boxHome(env), run = runCommand, maxIdleDays = 30, pins = null, now = Date.now(), exists = existsSync }: { env?: Env; home?: string; run?: RunCommand; maxIdleDays?: number; pins?: ImagePins | null; now?: number; exists?: (file: string) => boolean } = {}): Promise<Array<{ kind: string; name: string; reason: string }>> {
- const removed: Array<{ kind: string; name: string; reason: string }> = [];
- const boxes = await listBoxes(runtime, { run });
+export async function gcBoxes(runtime: BoxRuntime, { env = process.env, home = boxHome(env), run = runCommand, maxIdleDays = 30, pins = null, now = Date.now(), exists = existsSync }: { env?: Env; home?: string; run?: RunCommand; maxIdleDays?: number; pins?: ImagePins | null; now?: number; exists?: (file: string) => boolean } = {}): Promise<Removed> {
+ const driver = driverFor(runtime);
+ const removed: Removed = [];
+ const boxes = await driver.list(runtime, { run, env, home });
for (const box of boxes) {
const rec = readRecord(home, box.key);
const idle = rec?.updated ? (now - rec.updated) / 86_400_000 : Infinity;
if ((box.root && !exists(box.root)) || idle > maxIdleDays) {
- const res = await rt(runtime, run)(["rm", "-f", box.name], { timeoutMs: 60_000 });
- if (res.code === 0) {
+ const res = await driver.remove(runtime, box.key, { run, env, home });
+ if (res.removed) {
removed.push({ kind: "container", name: box.name, reason: box.root && !exists(box.root) ? "folder gone" : "unused" });
rmSync(recordFile(home, box.key), { force: true });
rmSync(path.join(home, "chains", box.key), { recursive: true, force: true });
}
}
}
- const images = await rt(runtime, run)(["images", "--format", "{{.Repository}}:{{.Tag}} {{.ID}}"], { timeoutMs: 30_000 });
const current = new Set(Object.values(pins?.images ?? {}).map((pin) => pin.ref));
- const used = new Set((await listBoxes(runtime, { run })).map((box) => box.image));
- for (const line of images.stdout.split("\n")) {
- const [ref, id] = line.trim().split(/\s+/);
- if (!ref || !/(^|\/)omnirush-ai\/box-[a-z]+:/.test(ref) || current.has(ref) || used.has(ref) || (id && used.has(id))) continue;
- const res = await rt(runtime, run)(["rmi", ref], { timeoutMs: 60_000 });
- if (res.code === 0) removed.push({ kind: "image", name: ref, reason: "not current" });
- }
+ const used = new Set<string>();
+ for (const box of await driver.list(runtime, { run, env, home })) used.add(box.image);
+ removed.push(...await driver.gcImages(runtime, { run, env, home, current, used }));
return removed;
}
diff --git a/apps/server/src/box/common.ts b/apps/server/src/box/common.ts
new file mode 100644
index 00000000..77ca9427
--- /dev/null
+++ b/apps/server/src/box/common.ts
@@ -0,0 +1,196 @@
+// Ported from the CLI (omnirush-cli src/box/common.js,
+// feat/local-box-backends); keep the two in step. Desktop differences, each
+// marked "Desktop:": types; the helpers' folder is the desktop's sidecars
+// (setToolsRoot) and there is no checkout box/bin fallback beyond
+// OMNIRUSH_BOX_BIN_DIR (helperPath is null when missing); the shell link
+// lives in <home>/shell-desktop (the CLI's own is <home>/shell); a
+// container-name prefix override for test rigs (OMNIRUSH_BOX_CONTAINER_PREFIX).
+//
+// Shared by the box and its backends: where things are, the helper
+// binaries, the box record, small file helpers.
+
+import { createHash, randomBytes } from "node:crypto";
+import { copyFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, realpathSync, renameSync, rmSync, statSync, symlinkSync, writeFileSync } from "node:fs";
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+import type { RuntimeInfo } from "./runtime.js";
+
+type Env = NodeJS.ProcessEnv;
+export type BoxLog = (level: "info" | "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
+
+export const RECORD_SCHEMA = 2;
+export const LABEL = "ai.omnirush.box";
+export const BOX_PORT = 7777;
+export const RUN_DIR = "/run/omnirush";
+export const SHIMS_DIR = "/opt/omnirush/pkglog";
+export const HOME_IN_BOX = "/root";
+/** One snapshot tar past this is cut (system paths first, then dependency folders). */
+export const TAR_MAX_BYTES = 256 * 1024 * 1024;
+/** A single file past this is left out of a snapshot (listed with its size). */
+export const FILE_MAX_BYTES = 128 * 1024 * 1024;
+/** Project dependency folders (node_modules, .venv) go into a turn's snapshot up to this. */
+export const DEPS_MAX_BYTES = 128 * 1024 * 1024;
+
+/** What runs a box: a probed backend (runtime.ts RuntimeInfo), or the parts of one a caller has. */
+export type BoxRuntime = Pick<RuntimeInfo, "name" | "bin"> & Partial<Omit<RuntimeInfo, "ok" | "name" | "bin">>;
+
+/** The install log (phase 1): its folder, the wrappers' folder and the pip hook's, all on this machine. */
+export type BoxInstallLog = { root: string; bin: string; py: string };
+
+// --- where things are ------------------------------------------------------
+
+export function boxHome(env: Env = process.env, home = os.homedir()): string {
+ return path.resolve(String(env.OMNIRUSH_BOX_HOME || "").trim() || path.join(home, ".omnirush", "box"));
+}
+
+/** The canonical form of a project folder (the box key hashes it). */
+export function canonicalRoot(root: string, { platform = process.platform, realpath = realpathSync.native }: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {
+ let resolved = path.resolve(root);
+ try { resolved = realpath(resolved); } catch { /* keep */ }
+ return platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+export function boxKey(root: string, opts: { platform?: NodeJS.Platform; realpath?: (file: string) => string } = {}): string {
+ return createHash("sha256").update(canonicalRoot(root, opts)).digest("hex").slice(0, 12);
+}
+
+/** Desktop: OMNIRUSH_BOX_CONTAINER_PREFIX renames the containers (test rigs on shared machines). */
+export function containerName(key: string, env: Env = process.env): string {
+ const prefix = String(env.OMNIRUSH_BOX_CONTAINER_PREFIX || "").trim();
+ return `${/^[a-z0-9][a-z0-9_.-]*$/.test(prefix) ? prefix : "omnirush-box-"}${key}`;
+}
+
+/** Where the project folder is inside: the same path; on Windows C:\x\y -> /c/x/y. */
+export function containerRoot(root: string, platform: NodeJS.Platform = process.platform): string {
+ if (platform !== "win32") return root;
+ const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(root);
+ if (!match) return `/w/${root.replace(/[\\]+/g, "/").replace(/^\/+/, "")}`;
+ return `/${match[1]!.toLowerCase()}/${match[2]!.replace(/[\\]+/g, "/")}`.replace(/\/+$/, "") || "/";
+}
+
+export function recordFile(home: string, key: string): string {
+ return path.join(home, "boxes", `${key}.json`);
+}
+
+export function runDir(home: string, key: string): string {
+ return path.join(home, "projects", key);
+}
+
+export function writeJson(file: string, value: unknown, mode = 0o600): void {
+ mkdirSync(path.dirname(file), { recursive: true });
+ const tmp = `${file}.${process.pid}.${randomBytes(3).toString("hex")}.tmp`;
+ writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, { mode });
+ renameSync(tmp, file);
+}
+
+export function readJson<T = Record<string, unknown>>(file: string): T | null {
+ try { return JSON.parse(readFileSync(file, "utf8")); } catch { return null; }
+}
+
+/** The record boxsh reads (boxes/<key>.json). `runtime` is empty when the backend has no exec fallback. */
+export type BoxRecord = {
+ v: 1; key: string; root: string; croot: string; container: string; backend: string; runtime: string; runtime_args: string[];
+ host: string; port: number; token: string; state: string; error: string; uid: number; gid: number;
+ home: string; shell: string; path_prefix: string; env_file: string; updated: number; pid: number;
+};
+
+export function readRecord(home: string, key: string): BoxRecord | null {
+ return readJson<BoxRecord>(recordFile(home, key));
+}
+
+// --- helper binaries ---------------------------------------------------------
+
+export const GOOS: Partial<Record<string, string>> = { linux: "linux", darwin: "darwin", win32: "windows" };
+export const GOARCH: Partial<Record<string, string>> = { x64: "amd64", arm64: "arm64", amd64: "amd64", aarch64: "arm64" };
+
+/**
+ * Folders holding the helpers, best first: OMNIRUSH_BOX_BIN_DIR, then the
+ * desktop's sidecars folder's box/ (setToolsRoot). Each has
+ * <goos>-<goarch>/boxsh, linux-<arch>/boxd and linux-<arch>/boxrun.
+ */
+export function helperDirs({ env = process.env, toolsRoot = null }: { env?: Env; toolsRoot?: string | null } = {}): string[] {
+ const asked = String(env.OMNIRUSH_BOX_BIN_DIR || "").trim();
+ return [...(asked ? [asked] : []), ...(toolsRoot ? [path.join(toolsRoot, "box")] : [])];
+}
+
+// Desktop: the sidecars folder (the engine binary's folder), set by the server at start.
+let platformTools: string | null = null;
+export function setToolsRoot(dir: string | null | undefined): void {
+ platformTools = dir || null;
+}
+
+/** The helper's file, or null when no folder has it (the box is then unavailable). */
+export function helperPath(name: string, { goos, goarch, env = process.env, toolsRoot = platformTools }: { goos: string | undefined; goarch: string | undefined; env?: Env; toolsRoot?: string | null }): string | null {
+ if (!goos || !goarch) return null;
+ const ext = goos === "windows" && name === "boxsh" ? ".exe" : "";
+ const rel = path.join(`${goos}-${goarch}`, name + ext);
+ return helperDirs({ env, toolsRoot }).map((dir) => path.join(dir, rel)).find((file) => existsSync(file)) ?? null;
+}
+
+/**
+ * The shell file the engine is given: a link (Windows: a copy) named `bash`
+ * to boxsh, so the engine describes its shell tool as bash.
+ */
+export function installShell(home: string, { platform = process.platform, arch = process.arch, env = process.env }: { platform?: NodeJS.Platform; arch?: string; env?: Env } = {}): string {
+ const source = helperPath("boxsh", { goos: GOOS[platform], goarch: GOARCH[arch], env });
+ if (!source) throw new Error(`the sandbox shell helper is missing (${GOOS[platform] ?? platform}-${GOARCH[arch] ?? arch}/boxsh)`);
+ const dir = shellDir(home);
+ mkdirSync(dir, { recursive: true });
+ const target = path.join(dir, platform === "win32" ? "bash.exe" : "bash");
+ if (platform === "win32") {
+ let same = false;
+ try { same = statSync(target).size === statSync(source).size && statSync(target).mtimeMs >= statSync(source).mtimeMs; } catch { /* missing */ }
+ if (!same) {
+ const tmp = `${target}.${process.pid}.tmp`;
+ copyFileSync(source, tmp);
+ try { renameSync(tmp, target); } catch { rmSync(tmp, { force: true }); }
+ }
+ return target;
+ }
+ let current: string | null = null;
+ try { current = lstatSync(target).isSymbolicLink() ? path.resolve(dir, readlinkSync(target)) : null; } catch { /* missing */ }
+ if (current !== source) {
+ const tmp = `${target}.${process.pid}.tmp`;
+ rmSync(tmp, { force: true });
+ symlinkSync(source, tmp);
+ renameSync(tmp, target);
+ }
+ return target;
+}
+
+/** Desktop: the shell link's folder (the CLI's is <home>/shell). */
+export function shellDir(home: string): string {
+ return path.join(home, "shell-desktop");
+}
+
+export function firstLine(text: unknown): string {
+ return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean)?.slice(0, 300) ?? "";
+}
+
+/** A Windows path as a WSL engine mounts it: C:\x\y -> /mnt/c/x/y. */
+export function wslPath(p: string): string {
+ const match = /^([a-zA-Z]):[\\/]?(.*)$/.exec(String(p));
+ if (!match) return String(p).replace(/\\/g, "/");
+ return `/mnt/${match[1]!.toLowerCase()}/${match[2]!.replace(/\\/g, "/")}`.replace(/\/+$/, "");
+}
+
+/** A free TCP port on this machine's loopback (for a runtime that needs one named). */
+export function freePort(): Promise<number> {
+ return new Promise((resolve, reject) => {
+ const server = net.createServer();
+ server.unref();
+ server.on("error", reject);
+ server.listen(0, "127.0.0.1", () => {
+ const address = server.address();
+ const port = typeof address === "object" && address ? address.port : 0;
+ server.close(() => resolve(port));
+ });
+ });
+}
+
+/** A token for a new box's boxd. */
+export function newToken(): string {
+ return randomBytes(24).toString("hex");
+}
diff --git a/apps/server/src/box/launch.ts b/apps/server/src/box/launch.ts
index 52afcfd1..1c5ae2c8 100644
--- a/apps/server/src/box/launch.ts
+++ b/apps/server/src/box/launch.ts
@@ -1,8 +1,12 @@
-// Ported from the CLI (omnirush-cli src/box/launch.js, feat/local-box); keep
-// the shared parts in step. Desktop differences: the per-project choice lives
-// in the workspace's OmniRush settings (service.ts), not box.json; the plan
-// is per workspace (one engine serves every project); a run tracks its turns
-// per chat; there is no --sandbox flag (OMNIRUSH_BOX=1|0 still overrides).
+// Ported from the CLI (omnirush-cli src/box/launch.js,
+// feat/local-box-backends); keep the shared parts in step. Desktop
+// differences: the per-project choice lives in the workspace's OmniRush
+// settings (service.ts), not box.json (box.json keeps only the machine's
+// backend, as the CLI's does); the plan is per workspace (one engine serves
+// every project); a run tracks its turns per chat; there is no --sandbox or
+// --sandbox-backend flag (OMNIRUSH_BOX=1|0 and OMNIRUSH_BOX_BACKEND still
+// override); a download with no detached command (the WSL distro) runs in
+// this process.
//
// Whether a chat runs in its project's box, and the box's part in a run:
// the engine config bits (shell, plugin), the per-turn checkpoints, the
@@ -14,10 +18,12 @@
// background, and a shell call waits for it (boxsh).
import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
import path from "node:path";
-import { boxKey, containerName, gcBoxes, inspectImage, installShell, openBox, recordFile, rt, savedTurns, type Box, type BoxInstallLog, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";
+import { boxKey, containerName, gcBoxes, installShell, openBox, recordFile, savedTurns, type Box, type BoxInstallLog, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";
+import { driverFor, normalizeBackend } from "./backends/index.js";
+import type { BoxExec } from "./backends/types.js";
import { detectStack, imageFor, loadPins, type BoxImage } from "./images.js";
import { detectRuntime, runCommand, type RunCommand, type RuntimeResult } from "./runtime.js";
@@ -42,18 +48,73 @@ export function serverDefault(stateDir: string): ServerBoxDefault {
}
}
-/** Remembers local_box.default of a capabilities answer; whether it changed. */
+/** The server's allowlist of backends (local_box.backends; null: any). */
+export function serverBackends(stateDir: string): string[] | null {
+ try {
+ const value = JSON.parse(readFileSync(path.join(stateDir, "box-server.json"), "utf8"));
+ return Array.isArray(value?.backends) ? value.backends.filter((b: unknown): b is string => typeof b === "string") : null;
+ } catch {
+ return null;
+ }
+}
+
+/** Remembers local_box.default (and its backends allowlist) of a capabilities answer; whether either changed. */
export function rememberServerDefault(stateDir: string, capabilities: { local_box?: unknown } | null | undefined): boolean {
const block = capabilities?.local_box;
if (!block || typeof block !== "object") return false;
- const fields = block as { default?: unknown; max_turn_bytes?: unknown };
+ const fields: { default?: unknown; max_turn_bytes?: unknown; backends?: unknown } = block;
const value = isMode(fields.default) ? fields.default : "off";
- const before = serverDefault(stateDir);
+ const backends = Array.isArray(fields.backends) ? fields.backends.filter((b): b is string => typeof b === "string").slice(0, 32) : null;
+ const before = JSON.stringify([serverDefault(stateDir), serverBackends(stateDir)]);
try {
mkdirSync(stateDir, { recursive: true });
- writeFileSync(path.join(stateDir, "box-server.json"), JSON.stringify({ default: value, max_turn_bytes: fields.max_turn_bytes ?? null, at: Date.now() }), { mode: 0o600 });
+ writeFileSync(path.join(stateDir, "box-server.json"), JSON.stringify({ default: value, max_turn_bytes: fields.max_turn_bytes ?? null, backends, at: Date.now() }), { mode: 0o600 });
} catch { /* best effort */ }
- return before !== value;
+ return before !== JSON.stringify([value, backends]);
+}
+
+// --- the backend --------------------------------------------------------------------
+
+/** What the backend setting holds: "auto" (the ranked order), one backend id, or "native" (no box). */
+export type BackendSetting = string;
+
+/** The machine's box settings file (the CLI's box.json; the desktop keeps only `backend` in it). */
+export function settingsFile(stateDir: string): string {
+ return path.join(stateDir, "box.json");
+}
+
+/** The saved backend setting ("auto" when none). */
+export function readBackend(stateDir: string): BackendSetting {
+ try {
+ return normalizeBackend(JSON.parse(readFileSync(settingsFile(stateDir), "utf8"))?.backend) || "auto";
+ } catch {
+ return "auto";
+ }
+}
+
+/** Save the backend boxes on this machine use: "auto" or one id (the desktop setting). */
+export function saveBackend(stateDir: string, backend: unknown): BackendSetting {
+ const id = normalizeBackend(backend);
+ if (!id) throw new Error(`unknown sandbox backend "${String(backend)}"`);
+ let current: Record<string, unknown> = {};
+ try {
+ const value: unknown = JSON.parse(readFileSync(settingsFile(stateDir), "utf8"));
+ if (value && typeof value === "object" && !Array.isArray(value)) current = Object.fromEntries(Object.entries(value));
+ } catch { /* none */ }
+ mkdirSync(stateDir, { recursive: true });
+ const file = settingsFile(stateDir);
+ const tmp = `${file}.${process.pid}.tmp`;
+ writeFileSync(tmp, `${JSON.stringify({ ...current, backend: id }, null, 2)}\n`, { mode: 0o600 });
+ renameSync(tmp, file);
+ return id;
+}
+
+/** The backend asked for, and by whom: OMNIRUSH_BOX_BACKEND, then the saved setting. */
+export function askedBackend({ env = process.env, stateDir }: { env?: NodeJS.ProcessEnv; stateDir: string }): { backend: string; source: "env" | "setting" | "auto" } {
+ const flag = String(env.OMNIRUSH_BOX_BACKEND || "").trim();
+ if (flag) return { backend: normalizeBackend(flag) ?? flag, source: "env" };
+ const saved = readBackend(stateDir);
+ return { backend: saved, source: saved !== "auto" ? "setting" : "auto" };
}
/**
@@ -72,14 +133,19 @@ export function resolveMode({ env = process.env, project, server, offered = fals
// --- background download ---------------------------------------------------------------
-function pullMarker(home: string, image: string): string {
- return path.join(home, "pulls", `${image.replace(/[^a-zA-Z0-9._-]+/g, "_")}.pid`);
+function pullMarker(home: string, runtime: Pick<BoxRuntime, "backend" | "name">, image: string): string {
+ return path.join(home, "pulls", `${runtime.backend ?? runtime.name}-${image.replace(/[^a-zA-Z0-9._-]+/g, "_")}.pid`);
}
-/** Whether a background download of `image` is running. */
-export function pulling(home: string, image: string): boolean {
+/** Downloads running in this process (a backend with no detached command: the WSL distro). */
+const inProcess = new Set<string>();
+
+/** Whether a background download of `image` with this backend is running. */
+export function pulling(home: string, runtime: Pick<BoxRuntime, "backend" | "name">, image: string): boolean {
+ const marker = pullMarker(home, runtime, image);
+ if (inProcess.has(marker)) return true;
try {
- const pid = Number(readFileSync(pullMarker(home, image), "utf8"));
+ const pid = Number(readFileSync(marker, "utf8"));
if (!pid) return false;
process.kill(pid, 0);
return true;
@@ -88,15 +154,30 @@ export function pulling(home: string, image: string): boolean {
}
}
-/** Start `pull` detached (survives this run); one at a time per image. */
-export function pullInBackground(runtime: BoxRuntime, image: string, home: string, { spawnImpl = spawn }: { spawnImpl?: (command: string, args: string[], options: { detached: boolean; stdio: "ignore"; windowsHide: boolean }) => Pick<ChildProcess, "pid" | "unref"> } = {}): { started: boolean; pid: number | undefined } {
- const marker = pullMarker(home, image);
+/**
+ * Start the backend's download detached (survives this run); one at a time
+ * per image. A backend without a detached command (the WSL distro, whose
+ * download imports the distro first) downloads in this process instead.
+ */
+export function pullInBackground(runtime: BoxRuntime, image: BoxImage, home: string, { spawnImpl = spawn, env = process.env, log = () => {} }: { spawnImpl?: (command: string, args: string[], options: { detached: boolean; stdio: "ignore"; windowsHide: boolean }) => Pick<ChildProcess, "pid" | "unref">; env?: NodeJS.ProcessEnv; log?: BoxLog } = {}): { started: boolean; pid: number | undefined } {
+ const marker = pullMarker(home, runtime, image.pull);
+ if (inProcess.has(marker)) return { started: false, pid: process.pid };
try {
const pid = Number(readFileSync(marker, "utf8"));
if (pid) { process.kill(pid, 0); return { started: false, pid }; }
} catch { /* none running */ }
mkdirSync(path.dirname(marker), { recursive: true });
- const child = spawnImpl(runtime.bin, [...(runtime.prefix ?? []), "pull", image], { detached: true, stdio: "ignore", windowsHide: true });
+ const driver = driverFor(runtime);
+ const cmd = driver.pullCommand(runtime, image, home);
+ if (!cmd) {
+ inProcess.add(marker);
+ void driver.pull(runtime, image, { home, env, log })
+ .then((res) => { if (!res.ok) log("warn", "box download failed", { backend: runtime.backend, error: res.error }); })
+ .catch((error) => log("warn", "box download failed", { backend: runtime.backend, error: String(error?.message || error) }))
+ .finally(() => inProcess.delete(marker));
+ return { started: true, pid: process.pid };
+ }
+ const child = spawnImpl(cmd.bin, cmd.args, { detached: true, stdio: "ignore", windowsHide: true });
child.unref?.();
try { writeFileSync(marker, String(child.pid ?? "")); } catch { /* best effort */ }
return { started: true, pid: child.pid };
@@ -123,10 +204,10 @@ export type BoxPlan = ReadyPlan | NativePlan;
* { box: null, notice } when its chats run on this machine for now (no
* runtime, no helpers, the image still downloading), else a ready plan.
*/
-export async function planBox({ env = process.env, home, root, log = () => {}, run = runCommand, probeMs = 4_000, shims = null }: { env?: NodeJS.ProcessEnv; home: string; root: string; log?: BoxLog; run?: RunCommand; probeMs?: number; shims?: string | null }): Promise<BoxPlan> {
+export async function planBox({ env = process.env, home, root, log = () => {}, run = runCommand, probeMs = 4_000, shims = null, asked = null, allow = null }: { env?: NodeJS.ProcessEnv; home: string; root: string; log?: BoxLog; run?: RunCommand; probeMs?: number; shims?: string | null; asked?: string | null; allow?: string[] | null }): Promise<BoxPlan> {
const key = boxKey(root);
const bounded = <T>(promise: Promise<T>, ms: number, fallback: T): Promise<T> => Promise.race([promise, new Promise<T>((resolve) => setTimeout(() => resolve(fallback), ms))]);
- const runtime = await bounded<RuntimeResult>(detectRuntime({ boxHome: home, env, run }), probeMs, { ok: false, reason: "the container runtime did not answer in time" });
+ const runtime = await bounded<RuntimeResult>(detectRuntime({ boxHome: home, env, run, ...(asked ? { asked } : {}), allow }), probeMs, { ok: false, reason: "the sandbox backend did not answer in time" });
if (!runtime.ok) {
log("info", "box unavailable", { reason: runtime.reason });
return { box: null, notice: `Sandbox off for now: ${runtime.reason}.`, runtime };
@@ -138,13 +219,14 @@ export async function planBox({ env = process.env, home, root, log = () => {}, r
return { box: null, notice: `Sandbox off for now: ${error instanceof Error ? error.message : String(error)}.`, runtime };
}
// A box already made keeps its image (and its installs); a new one needs the image here.
- const existing = await bounded(rt(runtime, run)(["container", "inspect", containerName(key, env), "--format", "{{.Id}}"], { timeoutMs: probeMs }), probeMs, { code: -1, stdout: "", stderr: "" });
- if (existing.code !== 0) {
+ const driver = driverFor(runtime);
+ const existing = await bounded(driver.exists(runtime, key, { run, home, env, timeoutMs: probeMs }), probeMs, false);
+ if (!existing) {
const image = imageFor(detectStack(root), { env });
- const present = await bounded(inspectImage(runtime, image.pull, { run }), probeMs, null);
+ const present = await bounded(driver.imagePresent(runtime, image, { run, home, env }), probeMs, null);
if (!present) {
- pullInBackground(runtime, image.pull, home);
- return { box: null, notice: `Sandbox is downloading (${image.approxMb ? `about ${image.approxMb} MB, ` : ""}once); chats here run on this machine until it is ready.`, runtime, image, downloading: true };
+ pullInBackground(runtime, image, home, { env, log });
+ return { box: null, notice: `Sandbox is downloading (${image.approxMb ? `about ${image.approxMb} MB, ` : ""}once${runtime.backend === "wsl" && !runtime.installed ? ", with the OmniRush WSL distro" : ""}); chats here run on this machine until it is ready.`, runtime, image, downloading: true };
}
}
if (env.OMNIRUSH_BOX_GC !== "off") setTimeout(() => gcInBackground(runtime, home, { log }), 30_000).unref?.();
@@ -220,6 +302,10 @@ export type BoxRun = {
runtimeBin: string;
/** Arguments before the runtime's own (`-e docker` for a WSL engine). */
runtimeArgs: string[];
+ /** The backend id (backends/index.ts). */
+ backend: string;
+ /** How to run a program in the box with stdin open when it is not `docker exec` (files-used reads); null for container engines. */
+ exec: BoxExec | null;
root: string;
readonly native: boolean;
readonly box: Box | null;
@@ -264,6 +350,8 @@ export function boxRun(plan: ReadyPlan, { log = () => {}, readyWaitMs = 30_000,
container: containerName(key),
runtimeBin: runtime.bin,
runtimeArgs: runtime.prefix ?? [],
+ backend: runtime.backend ?? runtime.name,
+ exec: driverFor(runtime).kind === "container" ? null : driverFor(runtime).execCommand(runtime, { key, home }),
root,
get native() { return native; },
get box() { return box; },
diff --git a/apps/server/src/box/run.ts b/apps/server/src/box/run.ts
new file mode 100644
index 00000000..d7649d4d
--- /dev/null
+++ b/apps/server/src/box/run.ts
@@ -0,0 +1,53 @@
+// Ported from the CLI (omnirush-cli src/box/run.js, feat/local-box-backends);
+// keep the two in step. Only types were added here.
+//
+// Running a runtime's CLI: a time limit, output caps, never a throw.
+
+import { spawn, type ChildProcess } from "node:child_process";
+
+type Env = NodeJS.ProcessEnv;
+
+export type RunResult = { code: number; stdout: string; stderr: string; error?: string };
+export type RunOptions = { env?: Env; timeoutMs?: number; input?: string | Buffer; maxBytes?: number; cwd?: string };
+export type RunCommand = (bin: string, args: string[], options?: RunOptions) => Promise<RunResult>;
+
+function errorText(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
+
+function errorCode(error: unknown): string {
+ const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+ return typeof code === "string" ? code : "spawn";
+}
+
+/** Run a program with a time limit; never throws. */
+export function runCommand(bin: string, args: string[], { env = process.env, timeoutMs = 8_000, input, maxBytes = 64 << 20, cwd }: RunOptions = {}): Promise<RunResult> {
+ return new Promise((resolve) => {
+ let child: ChildProcess;
+ try {
+ child = spawn(bin, args, { env, cwd, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });
+ } catch (error) {
+ resolve({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) });
+ return;
+ }
+ const out: Buffer[] = [];
+ let outBytes = 0;
+ const err: Buffer[] = [];
+ let done = false;
+ const finish = (value: RunResult) => {
+ if (done) return;
+ done = true;
+ clearTimeout(timer);
+ resolve(value);
+ };
+ const timer = setTimeout(() => {
+ try { child.kill("SIGKILL"); } catch { /* gone */ }
+ finish({ code: -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), error: "timeout" });
+ }, timeoutMs);
+ child.stdout?.on("data", (chunk: Buffer) => { outBytes += chunk.length; if (outBytes <= maxBytes) out.push(chunk); });
+ child.stderr?.on("data", (chunk: Buffer) => { if (err.length < 64) err.push(chunk); });
+ child.on("error", (error) => finish({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) }));
+ child.on("close", (code) => finish({ code: code ?? -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));
+ if (input !== undefined) child.stdin?.end(input);
+ });
+}
diff --git a/apps/server/src/box/runtime.ts b/apps/server/src/box/runtime.ts
index 43970dd7..d88fa378 100644
--- a/apps/server/src/box/runtime.ts
+++ b/apps/server/src/box/runtime.ts
@@ -1,9 +1,10 @@
-// Ported from the CLI (omnirush-cli src/box/runtime.js, feat/local-box);
-// keep the two in step. Only types were added here.
+// Ported from the CLI (omnirush-cli src/box/runtime.js,
+// feat/local-box-backends); keep the two in step. Only types were added here.
//
-// Which container runtime runs a project's box: rootless Podman or Docker on
-// Linux, Docker Desktop / OrbStack / colima / Rancher Desktop / Podman
-// machine on macOS and Windows, Docker inside WSL2. Never blocks a start: a
+// The container engines a box backend can be (backends/container.ts): rootless
+// Podman or Docker on Linux, Docker Desktop / OrbStack / colima / Rancher
+// Desktop / Podman machine on macOS and Windows, Docker inside WSL2. Which
+// backend runs a box is chosen by backends/index.ts. Never blocks a start: a
// probe has a short time limit, its result is cached, and "none" means the
// session runs on this machine with one line saying why.
//
@@ -12,22 +13,26 @@
// /mnt/c, the docker-group permission error shown as "the reason is above".
// Each of those has a rule below and a test.
-import { spawn, type ChildProcess } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync } from "node:fs";
import os from "node:os";
import path from "node:path";
+import { runCommand, type RunCommand, type RunResult } from "./run.js";
+
+export { runCommand, type RunCommand, type RunOptions, type RunResult } from "./run.js";
+
/** Probe results are reused this long (ms): a working runtime, and a missing one. */
export const CACHE_OK_MS = 10 * 60_000;
export const CACHE_FAIL_MS = 2 * 60_000;
type Env = NodeJS.ProcessEnv;
-export type RunResult = { code: number; stdout: string; stderr: string; error?: string };
-export type RunOptions = { env?: Env; timeoutMs?: number; input?: string | Buffer; maxBytes?: number };
-export type RunCommand = (bin: string, args: string[], options?: RunOptions) => Promise<RunResult>;
+/** A container CLI to probe; `prefix` goes before every call (`--context <name>`). */
+export type RuntimeCandidate = { name: string; bin: string; skipped?: string; prefix?: string[] };
+
+/** One backend as `all` lists it (the settings card's "others"). */
+export type BackendAlternative = { backend: string; name: string; ok: boolean; version: string | null; flavor: string | null; reason: string | null; context?: string };
-export type RuntimeCandidate = { name: string; bin: string; skipped?: string };
export type RuntimeInfo = {
ok: true;
name: string;
@@ -38,12 +43,45 @@ export type RuntimeInfo = {
rootless: boolean;
flavor: string;
vm: boolean;
- /** A WSL engine: arguments before the runtime's own (["-e", "docker"] through wsl.exe). */
+ /** The backend id (backends/index.ts BACKENDS): what uploads record as sandbox.backend. */
+ backend?: string;
+ /** Why this backend: the ranked order, the setting, the server's allowlist. */
+ why?: string;
+ /** Arguments before the runtime's own (["-e", "docker"] through wsl.exe, ["--context", "colima"]). */
prefix?: string[];
+ /** The docker context the runtime answered through (macOS, Windows). */
+ context?: string;
wsl?: boolean;
+ /** The OmniRush WSL distro: its name, whether it is imported yet. */
+ distro?: string;
+ installed?: boolean;
+ state?: string | null;
+ /** bubblewrap: the bwrap boxrun runs, the id mapping, the launcher. */
+ bwrap?: string | null;
+ idmap?: string;
+ launcher?: string;
+ kernel?: string;
+ cached?: boolean;
+ alternatives?: BackendAlternative[];
+};
+export type RuntimeTried = { backend?: string; name?: string; bin?: string; reason: string };
+export type RuntimeFailure = {
+ ok: false;
+ name?: string;
+ bin?: string;
+ backend?: string;
+ version?: string;
+ code?: string;
+ context?: string;
+ reason: string;
+ tried?: RuntimeTried[];
cached?: boolean;
+ /** The backend is set to native (this machine): no box, not a failure. */
+ native?: boolean;
+ /** macOS with nothing: the free option to offer (colima). */
+ hint?: string;
+ alternatives?: BackendAlternative[];
};
-export type RuntimeFailure = { ok: false; name?: string; bin?: string; reason: string; tried?: Array<{ name?: string; bin?: string; reason: string }>; cached?: boolean };
export type RuntimeResult = RuntimeInfo | RuntimeFailure;
/** Whether this Linux is WSL (the kernel says Microsoft). */
@@ -117,47 +155,6 @@ export function candidates({ platform = process.platform, home = os.homedir(), e
return out;
}
-function errorText(error: unknown): string {
- return error instanceof Error ? error.message : String(error);
-}
-
-function errorCode(error: unknown): string {
- const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
- return typeof code === "string" ? code : "spawn";
-}
-
-/** Run a program with a time limit; never throws. */
-export function runCommand(bin: string, args: string[], { env = process.env, timeoutMs = 8_000, input, maxBytes = 64 << 20 }: RunOptions = {}): Promise<RunResult> {
- return new Promise((resolve) => {
- let child: ChildProcess;
- try {
- child = spawn(bin, args, { env, stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], windowsHide: true });
- } catch (error) {
- resolve({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) });
- return;
- }
- const out: Buffer[] = [];
- let outBytes = 0;
- const err: Buffer[] = [];
- let done = false;
- const finish = (value: RunResult) => {
- if (done) return;
- done = true;
- clearTimeout(timer);
- resolve(value);
- };
- const timer = setTimeout(() => {
- try { child.kill("SIGKILL"); } catch { /* gone */ }
- finish({ code: -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), error: "timeout" });
- }, timeoutMs);
- child.stdout?.on("data", (chunk: Buffer) => { outBytes += chunk.length; if (outBytes <= maxBytes) out.push(chunk); });
- child.stderr?.on("data", (chunk: Buffer) => { if (err.length < 64) err.push(chunk); });
- child.on("error", (error) => finish({ code: -1, stdout: "", stderr: errorText(error), error: errorCode(error) }));
- child.on("close", (code) => finish({ code: code ?? -1, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8") }));
- if (input !== undefined) child.stdin?.end(input);
- });
-}
-
function firstLine(text: unknown): string {
return String(text ?? "").split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? "";
}
@@ -249,7 +246,8 @@ export async function probe(candidate: RuntimeCandidate, { run = runCommand, env
return { ok: false, name, bin, reason: "DOCKER_HOST points at another machine, which cannot see this folder" };
}
}
- const args = name === "podman" ? ["info", "--format", "json"] : ["info", "--format", "{{json .}}"];
+ const prefix = Array.isArray(candidate.prefix) ? candidate.prefix : [];
+ const args = [...prefix, ...(name === "podman" ? ["info", "--format", "json"] : ["info", "--format", "{{json .}}"])];
const result = await run(bin, args, { env, timeoutMs });
if (result.code !== 0) return { ok: false, name, bin, reason: explainFailure(name, result, { platform, env }) };
let info: Info;
@@ -326,70 +324,34 @@ export async function probeWsl(wslExe: string, { run = runCommand, env = process
return { ok: false, name: "wsl", bin: wslExe, reason: "no Docker or Podman engine answers in the default WSL distribution" };
}
-function cacheFile(boxHome: string): string {
- return path.join(boxHome, "runtime.json");
-}
-
-function readCache(boxHome: string, now: number, key: string): RuntimeResult | null {
- try {
- const cached = JSON.parse(readFileSync(cacheFile(boxHome), "utf8"));
- if (cached?.key !== key) return null;
- const age = now - Number(cached.at);
- if (!(age >= 0)) return null;
- if (cached.result?.ok ? age < CACHE_OK_MS : age < CACHE_FAIL_MS) return cached.result;
- } catch { /* none */ }
- return null;
-}
-
-function writeCache(boxHome: string, key: string, result: RuntimeResult, now: number): void {
- try {
- mkdirSync(boxHome, { recursive: true });
- const file = cacheFile(boxHome);
- const tmp = `${file}.${process.pid}.tmp`;
- writeFileSync(tmp, JSON.stringify({ key, at: now, result }), { mode: 0o600 });
- renameSync(tmp, file);
- } catch { /* best effort */ }
-}
-
/**
- * The runtime for boxes on this machine (cached; `fresh` skips the cache):
- * the first candidate that answers, or { ok: false, reason, tried } where
- * `reason` is one line for the user.
+ * The backend for boxes on this machine (backends/index.ts: bubblewrap,
+ * Apple container, WSL containers, the OmniRush WSL distro, then the
+ * container engines above, in a ranked order per OS). Kept here under its
+ * old name.
*/
-export async function detectRuntime({ boxHome, env = process.env, platform = process.platform, home = os.homedir(), exists = existsSync, run = runCommand, wsl = platform === "linux" && isWsl(env), now = Date.now(), fresh = false, timeoutMs }: { boxHome?: string; env?: Env; platform?: NodeJS.Platform; home?: string; exists?: (file: string) => boolean; run?: RunCommand; wsl?: boolean; now?: number; fresh?: boolean; timeoutMs?: number } = {}): Promise<RuntimeResult> {
- const key = JSON.stringify([platform, env.OMNIRUSH_BOX_RUNTIME || "", env.DOCKER_HOST || "", env.PATH || env.Path || ""]);
- if (boxHome && !fresh) {
- const cached = readCache(boxHome, now, key);
- if (cached) return { ...cached, cached: true };
- }
- const list = candidates({ platform, home, env, exists, wsl });
- const tried: RuntimeFailure[] = [];
- let result: RuntimeResult | null = null;
- for (const candidate of list) {
- const probed = await probe(candidate, { run, env, platform, wsl, ...(timeoutMs ? { timeoutMs } : {}) });
- if (probed.ok) { result = probed; break; }
- tried.push(probed);
- }
- // Windows: a Docker or Podman engine inside an existing WSL 2 distro, used
- // through wsl.exe (never installed or started for the user).
- if (!result && platform === "win32" && env.OMNIRUSH_BOX_WSL !== "0") {
- const wslExe = wslLauncher({ env, exists });
- if (wslExe) {
- const probed = await probeWsl(wslExe, { run, env, ...(timeoutMs ? { timeoutMs } : {}) });
- if (probed.ok) result = probed;
- else tried.push(probed);
- }
- }
- if (!result) {
- const reason = tried.length
- ? tried.map((entry) => entry.reason).join("; ")
- : platform === "linux"
- ? "no container runtime found (install Podman or Docker)"
- : platform === "darwin"
- ? "no container runtime found (install Docker Desktop, OrbStack, colima or Podman)"
- : "no container runtime found (install Docker Desktop with the WSL 2 backend, or Podman)";
- result = { ok: false, reason, tried: tried.map(({ name, bin, reason: why }) => ({ name, bin, reason: why })) };
- }
- if (boxHome) writeCache(boxHome, key, result, now);
- return result;
+export async function detectRuntime(opts: DetectOptions = {}): Promise<RuntimeResult> {
+ const { detectBackend } = await import("./backends/index.js");
+ return detectBackend(opts);
}
+
+export type DetectOptions = {
+ boxHome?: string;
+ env?: Env;
+ platform?: NodeJS.Platform;
+ home?: string;
+ exists?: (file: string) => boolean;
+ run?: RunCommand;
+ wsl?: boolean;
+ now?: number;
+ fresh?: boolean;
+ /** Probe every backend and list them as `alternatives` (status). */
+ all?: boolean;
+ timeoutMs?: number;
+ /** A backend id, "auto" or "native" (the desktop setting); default OMNIRUSH_BOX_BACKEND. */
+ asked?: string | null;
+ /** The server's allowlist (local_box.backends); null: any. */
+ allow?: string[] | null;
+ arch?: string;
+ release?: string;
+};
diff --git a/apps/server/src/box/service.ts b/apps/server/src/box/service.ts
index 65edcbca..a868ab33 100644
--- a/apps/server/src/box/service.ts
+++ b/apps/server/src/box/service.ts
@@ -10,7 +10,10 @@
* - <box home>/desktop-projects.json, the projects the plugin routes to
* their box (everything else runs natively through the same shell);
* - each project's run: the per-turn checkpoints and the label its chats'
- * uploads carry.
+ * uploads carry;
+ * - the machine's backend setting (`auto`, one backend id, or `native`) in
+ * <state>/box.json, and the server's allowlist of backends
+ * (local_box.backends, remembered in <state>/box-server.json).
*
* Nothing here blocks opening a project: probes are bounded, a missing image
* downloads in the background, a box that cannot start leaves its project
@@ -21,12 +24,14 @@
import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
import { join } from "node:path";
-import { boxHome, boxKey, boxSnapshotsDir, containerName, inspectImage, installShell, listBoxes, readRecord, resetBox, savedTurns, type BoxLabel, type BoxLog } from "./box.js";
+import { boxHome, boxKey, boxSnapshotsDir, containerName, installShell, listBoxes, readRecord, resetBox, savedTurns, type BoxLabel, type BoxLog } from "./box.js";
+import { LABELS, backendsFor, driverFor } from "./backends/index.js";
+import type { BoxExec } from "./backends/types.js";
import { detectStack, imageFor } from "./images.js";
-import { boxRun, planBox, pulling, pullInBackground, resolveMode, serverDefault, shimsDir, type BoxRun, type ProjectBoxMode, type ServerBoxDefault } from "./launch.js";
+import { askedBackend, boxRun, planBox, pulling, pullInBackground, resolveMode, saveBackend, serverBackends, serverDefault, shimsDir, type BoxRun, type ProjectBoxMode, type ServerBoxDefault } from "./launch.js";
import type { BoxInstallLogPaths } from "./install-log.js";
import { DESKTOP_PROJECTS_FILE } from "./plugin-lib.js";
-import { detectRuntime, type RuntimeResult } from "./runtime.js";
+import { detectRuntime, type BackendAlternative, type DetectOptions, type RuntimeResult } from "./runtime.js";
/** What the capture side needs of a chat's box (plain data: it crosses to the capture worker). */
export type BoxCaptureInfo = {
@@ -37,6 +42,10 @@ export type BoxCaptureInfo = {
runtimeBin: string;
/** Arguments before the runtime's own (`-e docker` for a WSL engine). */
runtimeArgs: string[];
+ /** The backend id (backends/index.ts). */
+ backend: string;
+ /** How files-used reads the box when it is not `docker exec` (bubblewrap, Apple container, the WSL distro). */
+ exec: BoxExec | null;
/** environment.sandbox of the chat's uploads. */
label: BoxLabel;
};
@@ -54,6 +63,10 @@ export type BoxStatus = {
offer: boolean;
state: "off" | "unavailable" | "downloading" | "starting" | "ready" | "failed";
runtime: { ok: boolean; name: string | null; flavor: string | null; version: string | null; reason: string | null } | null;
+ /** What runs the box on this machine: the chosen backend, why, and the others (each with why not). */
+ backend: BoxBackendView | null;
+ /** The machine's backend setting and the values it takes here. */
+ backendSetting: { value: string; source: "env" | "setting" | "auto"; choices: Array<{ id: string; label: string }> };
image: { ref: string; stack: string; present: boolean | null; downloading: boolean } | null;
container: { name: string; exists: boolean; running: boolean } | null;
/** One line for the user (why it is off, that it is downloading). */
@@ -61,6 +74,25 @@ export type BoxStatus = {
error: string | null;
};
+export type BoxBackendView = {
+ /** The chosen backend's id (null when none works here). */
+ id: string | null;
+ label: string | null;
+ version: string | null;
+ flavor: string | null;
+ /** Why this one (the ranked order, the setting, the server's allowlist), or why none. */
+ why: string | null;
+ /** Every backend tried here: id, whether it works, one line why not. Empty until the first full check. */
+ alternatives: Array<{ id: string; label: string; ok: boolean; reason: string | null }>;
+ /** The server limits the backends (local_box.backends). */
+ allowed: string[] | null;
+};
+
+/** The backend choices of a platform: auto, the ranked ids there, native. */
+export function backendChoices(platform: NodeJS.Platform = process.platform): Array<{ id: string; label: string }> {
+ return [{ id: "auto", label: "Automatic" }, ...backendsFor(platform).map((id) => ({ id, label: LABELS[id] ?? id })), { id: "native", label: "Off (this computer)" }];
+}
+
export type BoxServiceOptions = {
/** The capture state dir: the server default is remembered here, snapshots go under sandbox/snapshots. */
stateDir: string;
@@ -79,6 +111,8 @@ type Project = { run: BoxRun | null; notice: string | null; planning: Promise<Bo
const REPLAN_MS = 15_000;
/** A prompt waits at most this long for its turn's checkpoint. */
const FREEZE_WAIT_MS = 90_000;
+/** The full backend check (every backend, for the status card's "others") is reused this long. */
+const ALTERNATIVES_MS = 60_000;
export function boxRoot(workspace: BoxWorkspace): string {
return workspace.directory?.trim() || workspace.path;
@@ -92,6 +126,7 @@ export class BoxService {
private log: BoxLog;
private projectsWrite: Promise<void> = Promise.resolve();
private installLog: BoxInstallLogPaths | null = null;
+ private alternatives: { at: number; key: string; list: BackendAlternative[] } | null = null;
constructor(private readonly options: BoxServiceOptions) {
this.env = options.env ?? process.env;
@@ -121,6 +156,36 @@ export class BoxService {
return serverDefault(this.options.stateDir);
}
+ /** The backend detection's inputs: the setting (or OMNIRUSH_BOX_BACKEND) and the server's allowlist. */
+ private detectOptions(): Pick<DetectOptions, "asked" | "allow"> {
+ return { asked: askedBackend({ env: this.env, stateDir: this.options.stateDir }).backend, allow: serverBackends(this.options.stateDir) };
+ }
+
+ private detect(extra: DetectOptions = {}): Promise<RuntimeResult> {
+ return detectRuntime({ boxHome: this.home, env: this.env, ...this.detectOptions(), ...extra });
+ }
+
+ /**
+ * Save the machine's backend ("auto", one backend id, "native"). Projects
+ * are planned again with it (a running box keeps going until its project
+ * is planned again). Throws for an unknown value.
+ */
+ async setBackend(value: unknown): Promise<string> {
+ const saved = saveBackend(this.options.stateDir, value);
+ this.alternatives = null;
+ const now = await this.detect({ fresh: true });
+ const chosen = now.ok ? now.backend ?? now.name : null;
+ for (const project of this.projects.values()) {
+ if (project.run && project.run.backend === chosen) continue;
+ project.run = null;
+ project.notice = null;
+ project.nextPlanAt = 0;
+ }
+ await this.writeProjects();
+ void this.ensureAll();
+ return saved;
+ }
+
private async mode(workspace: BoxWorkspace) {
const settings = await this.options.readSettings(workspace.id).catch(() => ({ mode: null, offered: false }));
const server = this.serverDefault();
@@ -169,7 +234,7 @@ export class BoxService {
}
if (project.run && !project.run.native) return project.run;
if (Date.now() < project.nextPlanAt) return null;
- const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env) });
+ const plan = await planBox({ env: this.env, home: this.home, root, log: this.log, shims: shimsDir(this.env), ...this.detectOptions() });
if (!plan.box) {
project.run = null;
project.notice = plan.notice;
@@ -246,24 +311,43 @@ export class BoxService {
const key = boxKey(root);
const project = this.projects.get(key);
const base = { mode: settings.mode, serverDefault: server, on, source, offer, error: null };
- if (workspace.workspaceType !== "local") return { ...base, on: false, offer: false, state: "off", runtime: null, image: null, container: null, notice: "The sandbox is for folders on this computer." };
+ const backendSetting = { ...askedBackend({ env: this.env, stateDir: this.options.stateDir }), choices: backendChoices() };
+ const setting = { value: backendSetting.backend, source: backendSetting.source, choices: backendSetting.choices };
+ if (workspace.workspaceType !== "local") return { ...base, on: false, offer: false, state: "off", runtime: null, backend: null, backendSetting: setting, image: null, container: null, notice: "The sandbox is for folders on this computer." };
+ // The full check (every backend) on a fresh look or once a minute; the cached choice otherwise.
+ const { asked, allow } = this.detectOptions();
+ const altKey = JSON.stringify([asked, allow]);
+ const full = fresh || !this.alternatives || this.alternatives.key !== altKey || Date.now() - this.alternatives.at > ALTERNATIVES_MS;
+ const timeout = full ? 10_000 : 4_000;
const runtime = await Promise.race([
- detectRuntime({ boxHome: this.home, env: this.env, fresh }),
- new Promise<RuntimeResult>((resolve) => setTimeout(() => resolve({ ok: false, reason: "the container runtime did not answer in time" }), 4_000)),
+ this.detect(full ? { all: true } : {}),
+ new Promise<RuntimeResult>((resolve) => setTimeout(() => resolve({ ok: false, reason: "the sandbox backend did not answer in time" }), timeout)),
]);
+ if (full && runtime.alternatives) this.alternatives = { at: Date.now(), key: altKey, list: runtime.alternatives };
+ const alternatives = (runtime.alternatives ?? this.alternatives?.list ?? []).map((alt) => ({ id: alt.backend, label: LABELS[alt.backend] ?? alt.backend, ok: alt.ok, reason: alt.reason ? alt.reason.split("\n")[0]!.slice(0, 300) : null }));
const runtimeView = runtime.ok
? { ok: true, name: runtime.name, flavor: runtime.flavor, version: runtime.version, reason: null }
: { ok: false, name: null, flavor: null, version: null, reason: runtime.reason };
+ const backendId = runtime.ok ? runtime.backend ?? runtime.name : null;
+ const backend: BoxBackendView = {
+ id: backendId,
+ label: backendId ? LABELS[backendId] ?? backendId : null,
+ version: runtime.ok ? runtime.version || null : null,
+ flavor: runtime.ok ? runtime.flavor || null : null,
+ why: runtime.ok ? runtime.why ?? null : runtime.reason,
+ alternatives,
+ allowed: allow ?? null,
+ };
const image = imageFor(detectStack(root), { env: this.env });
const name = containerName(key, this.env);
let present: boolean | null = null;
let container: BoxStatus["container"] = null;
if (runtime.ok) {
- present = Boolean(await inspectImage(runtime, image.pull).catch(() => null));
- const mine = (await listBoxes(runtime).catch(() => [])).find((box) => box.key === key && box.name === name);
+ present = Boolean(await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env }).catch(() => null));
+ const mine = (await listBoxes(runtime, { env: this.env, home: this.home }).catch(() => [])).find((box) => box.key === key);
container = { name, exists: Boolean(mine), running: Boolean(mine?.running) };
}
- const downloading = runtime.ok && pulling(this.home, image.pull);
+ const downloading = runtime.ok && pulling(this.home, runtime, image.pull);
const record = readRecord(this.home, key);
const run = project?.run ?? null;
const state: BoxStatus["state"] = !on ? "off"
@@ -275,6 +359,8 @@ export class BoxService {
...base,
state,
runtime: runtimeView,
+ backend,
+ backendSetting: setting,
image: { ref: image.pull, stack: image.stack, present, downloading },
container,
notice: on ? project?.notice ?? (runtime.ok ? null : `Sandbox off for now: ${runtime.reason}.`) : null,
@@ -286,7 +372,7 @@ export class BoxService {
async reset(workspace: BoxWorkspace): Promise<{ removed: boolean }> {
const root = boxRoot(workspace);
const key = boxKey(root);
- const runtime = await detectRuntime({ boxHome: this.home, env: this.env });
+ const runtime = await this.detect();
const project = this.projects.get(key);
if (project) {
project.run = null;
@@ -301,11 +387,11 @@ export class BoxService {
/** Download the project's image now (the toggle turned on with no image here). */
async pull(workspace: BoxWorkspace): Promise<boolean> {
- const runtime = await detectRuntime({ boxHome: this.home, env: this.env });
+ const runtime = await this.detect();
if (!runtime.ok) return false;
const image = imageFor(detectStack(boxRoot(workspace)), { env: this.env });
- if (await inspectImage(runtime, image.pull)) return false;
- pullInBackground(runtime, image.pull, this.home);
+ if (await driverFor(runtime).imagePresent(runtime, image, { home: this.home, env: this.env })) return false;
+ pullInBackground(runtime, image, this.home, { env: this.env, log: this.log });
return true;
}
@@ -344,7 +430,7 @@ export class BoxService {
const label = run.label(sessionId);
const box = run.box;
if (!label || !box) return null;
- return { key: run.key, root: run.root, croot: box.croot, container: box.container, runtimeBin: run.runtimeBin, runtimeArgs: run.runtimeArgs, label };
+ return { key: run.key, root: run.root, croot: box.croot, container: box.container, runtimeBin: run.runtimeBin, runtimeArgs: run.runtimeArgs, backend: run.backend, exec: run.exec, label };
}
/** Whether chats ran in a box during this run (they get a `final` checkpoint at quit). */
diff --git a/apps/server/src/box/wsl.json b/apps/server/src/box/wsl.json
new file mode 100644
index 00000000..2a855f4e
--- /dev/null
+++ b/apps/server/src/box/wsl.json
@@ -0,0 +1,9 @@
+{
+ "version": "2026.10.1",
+ "distro": "OmniRushBox",
+ "base": "debian:bookworm-slim@sha256:7c7b2c966bc9ee8cedfeef67e0e279108992c77681fa595db4a9d65c06ccc587",
+ "assets": {
+ "amd64": { "url": null, "sha256": null, "bytes": null },
+ "arm64": { "url": null, "sha256": null, "bytes": null }
+ }
+}
diff --git a/apps/server/src/capture-host.ts b/apps/server/src/capture-host.ts
index 3bd00905..38cb5063 100644
--- a/apps/server/src/capture-host.ts
+++ b/apps/server/src/capture-host.ts
@@ -225,7 +225,7 @@ export class CaptureHost {
}
this.boxChats.set(sessionId, box.container);
if (!this.boxViews.has(box.container)) {
- const view = sandboxFilesUsed({ container: box.container, manifest: { home: "/root", workspaces: [box.croot] }, cwd: box.root, hostHome: null, docker: box.runtimeBin, dockerArgs: box.runtimeArgs, log: this.log });
+ const view = sandboxFilesUsed({ container: box.container, manifest: { home: "/root", workspaces: [box.croot] }, cwd: box.root, hostHome: null, docker: box.runtimeBin, dockerArgs: box.runtimeArgs, exec: box.exec, log: this.log });
if (view) this.boxViews.set(box.container, view);
}
}
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index f08de642..60304401 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -178,6 +178,7 @@ import {
import { boxServiceFor } from "./box/desktop.js";
import { prepareBoxInstallLog } from "./box/install-log.js";
import { rememberServerDefault } from "./box/launch.js";
+import { normalizeBackend } from "./box/backends/index.js";
import { buildOmniRushRuntimeConfigObject, omnirushGatewayConfigured, omnirushRuntimeConfigFilePath, writeOmniRushRuntimeConfigFile } from "./omnirush-runtime-config.js";
import { assertMcpAllowed, mcpAllowed, mcpPolicyForConfig, MCP_DISABLED_MESSAGE } from "./mcp-policy.js";
import { omnirushModelWantsReasoningSummary, readOmniRushModelCatalog } from "./omnirush-model-catalog.js";
@@ -3779,13 +3780,18 @@ function createRoutes(
const workspace = await resolveWorkspace(config, ctx.params.id);
const body = await readJsonBody(ctx.request);
const mode = body.mode;
- if ((mode !== "on" && mode !== "off" && mode !== null) || Object.keys(body).some((key) => key !== "mode")) {
- throw new ApiError(400, "invalid_payload", "mode must be \"on\", \"off\" or null and the only field");
+ const keys = Object.keys(body);
+ // `mode`: the project's choice; `backend`: what runs boxes on this computer (auto, one backend id, native).
+ if (!keys.length || keys.some((key) => key !== "mode" && key !== "backend")
+ || ("mode" in body && mode !== "on" && mode !== "off" && mode !== null)
+ || ("backend" in body && (typeof body.backend !== "string" || !normalizeBackend(body.backend)))) {
+ throw new ApiError(400, "invalid_payload", "mode must be \"on\", \"off\" or null; backend must be \"auto\", a sandbox backend or \"native\"");
}
if (workspace.workspaceType !== "local") throw new ApiError(400, "box_unsupported", "The sandbox is for folders on this computer");
const boxes = boxServiceFor(config);
const before = JSON.stringify(await boxes.engineBits());
- const status = await boxes.setMode(workspace, mode);
+ if (typeof body.backend === "string") await boxes.setBackend(body.backend);
+ const status = "mode" in body && (mode === "on" || mode === "off" || mode === null) ? await boxes.setMode(workspace, mode) : await boxes.status(workspace, { fresh: true });
// The engine gets the box shell and plugin when the first workspace turns its box on (and loses them with the last).
const engine = JSON.stringify(await boxes.engineBits()) === before ? { status: "unchanged" as const } : await applyBoxEngineConfig(config, "local_box");
return jsonResponse({ ...status, engine });
diff --git a/apps/server/src/session-archive/files-used-sandbox.ts b/apps/server/src/session-archive/files-used-sandbox.ts
index 2768d219..ccbd87d4 100644
--- a/apps/server/src/session-archive/files-used-sandbox.ts
+++ b/apps/server/src/session-archive/files-used-sandbox.ts
@@ -172,7 +172,10 @@ export type ViewRunner = (request: unknown, maxOutputBytes: number) => Promise<R
* failed, slow or oversized answer ends the process and the next request
* starts another.
*/
-export function dockerExecRunner(container: string, docker = "docker", timeoutMs = STEP_TIMEOUT_MS, dockerArgs: readonly string[] = []): ViewRunner {
+/** How to run a program in the box with stdin open (a box backend without `docker exec`: boxsh, `container exec`). */
+export type BoxExec = { bin: string; args: readonly string[]; env?: Record<string, string> };
+
+export function dockerExecRunner(container: string, docker = "docker", timeoutMs = STEP_TIMEOUT_MS, dockerArgs: readonly string[] = [], boxExec: BoxExec | null = null): ViewRunner {
type Live = { child: ChildProcessWithoutNullStreams; buffer: Buffer[]; size: number; waiting: ((line: Buffer | null) => void) | null };
let live: Live | null = null;
let tail: Promise<unknown> = Promise.resolve();
@@ -198,7 +201,9 @@ export function dockerExecRunner(container: string, docker = "docker", timeoutMs
const start = (): Live | null => {
let child: ChildProcessWithoutNullStreams;
try {
- child = spawn(docker, [...dockerArgs, "exec", "-i", container, "/usr/bin/python3", "-I", "-c", FILES_USED_VIEW_SCRIPT], { stdio: ["pipe", "pipe", "ignore"] as const, windowsHide: true }) as unknown as ChildProcessWithoutNullStreams;
+ child = (boxExec
+ ? spawn(boxExec.bin, [...boxExec.args, "/usr/bin/python3", "-I", "-c", FILES_USED_VIEW_SCRIPT], { stdio: ["pipe", "pipe", "ignore"] as const, windowsHide: true, env: { ...process.env, ...(boxExec.env ?? {}) } })
+ : spawn(docker, [...dockerArgs, "exec", "-i", container, "/usr/bin/python3", "-I", "-c", FILES_USED_VIEW_SCRIPT], { stdio: ["pipe", "pipe", "ignore"] as const, windowsHide: true })) as unknown as ChildProcessWithoutNullStreams;
} catch {
return null;
}
@@ -335,6 +340,8 @@ export function sandboxFilesUsed(input: {
docker?: string;
/** Arguments before docker's own (`-e docker` when docker is reached through wsl.exe). */
dockerArgs?: readonly string[];
+ /** The box backend's way in when it is not a container engine (bubblewrap, Apple container, the WSL distro). */
+ exec?: BoxExec | null;
log?: (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
}): FilesUsedSandbox | null {
if (!input.container) return null;
@@ -342,7 +349,7 @@ export function sandboxFilesUsed(input: {
const home = typeof manifest.home === "string" && manifest.home.startsWith("/") ? manifest.home : "/home/omnirush";
const workspaces = Array.isArray(manifest.workspaces) ? manifest.workspaces.filter((entry): entry is string => typeof entry === "string" && entry.startsWith("/")) : [];
let warned = false;
- const view = containerFilesUsedView(dockerExecRunner(input.container, input.docker || "docker", STEP_TIMEOUT_MS, input.dockerArgs ?? []), (op) => {
+ const view = containerFilesUsedView(dockerExecRunner(input.container, input.docker || "docker", STEP_TIMEOUT_MS, input.dockerArgs ?? [], input.exec ?? null), (op) => {
if (warned) return;
warned = true;
input.log?.("warn", "OmniRush files used: the sandbox could not be read; its files are listed, not kept", { op });