Skip to content

A desktop coding agent with free access to frontier models.

TypeScript
19.5 KB
Raw Blame
// 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:   OrbStack > colima > Docker Desktop > Rancher > Podman machine
//            (Apple container is opt-in only: never picked on its own, never started unasked);
//            under the required sandbox OmniRush's own Lima VM (macOS 13+, set up by itself) comes
//            first, else the VM runs only when chosen by name (REQUIRED_FIRST)
//   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 { boxEgress, bwrapDriver, probeBwrap } from "./bwrap.js";
import { containerDriver } from "./container.js";
import { limaDriver, probeLima } from "./lima.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: ["orbstack", "colima", "docker-desktop", "rancher", "podman", "docker"],
  win32: ["wslc", "wsl", "docker-desktop", "podman", "docker", "wsl-engine"],
};

/**
 * Backends used only when chosen by name (the sandbox backend setting,
 * OMNIRUSH_BOX_BACKEND), never in the automatic order. Apple container: on
 * macOS 27 `container system start` can hang and leave the Mac's network
 * sharing stuck until a reboot (apple/container#2275), and it turns the
 * packet filter on for all host traffic (#2335).
 */
export const OPT_IN: Partial<Record<NodeJS.Platform, string[]>> = { darwin: ["apple"] };

/**
 * Backends that lead the automatic order only while the sandbox is required
 * on this account (the server's `local_box.required`): macOS' own VM. Without
 * it the order is the one above, and the VM runs only when chosen by name.
 */
export const REQUIRED_FIRST: Partial<Record<NodeJS.Platform, string[]>> = { darwin: ["lima"] };

/**
 * Farm runs (bwrap.ts boxEgress): only the backends whose boxd gets BOXD_EGRESS and runs where it
 * can make the commands' network (boxrun's boxes; wslc when its container allows it), in this
 * order: the WSL distro, which always can, before wslc. boxd refuses to start where it cannot. CLI: the same.
 */
export const EGRESS_BACKENDS = ["bwrap", "lima", "wsl", "wslc"];

/** What the backend setting takes (and what uploads record as sandbox.backend). */
export const BACKENDS = ["bwrap", "lima", "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)", lima: "OmniRush VM (Lima)", 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 "lima": return limaDriver;
    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";
  if (base === "limactl") return "lima";
  const lower = String(value || "").toLowerCase();
  if (["bwrap", "lima", "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", "omnirush-vm": "lima", vm: "lima", "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, required = false): string {
  if (platform === "linux") return "no sandbox backend works here (install bubblewrap, Podman or Docker)";
  if (platform === "darwin") return (required ? "the OmniRush VM cannot run here and " : "") + "no container runtime found (free: `brew install colima docker && colima start`; also OrbStack, Docker Desktop, Podman; Apple container only when chosen in Settings)";
  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(), preferShadows = false, required = false }: 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 farm = Boolean(boxEgress(env));
  const key = JSON.stringify([2, platform, wanted, allowList, ...(preferShadows ? ["shadows"] : []), ...(required ? ["required"] : []), ...(farm ? ["farm"] : []), 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);
  // Under required (only): the backends that lead then (macOS: OmniRush's VM).
  const first = REQUIRED_FIRST[platform] ?? [];
  if (required && wanted === "auto") order = [...first, ...order.filter((id) => !first.includes(id))];
  // Otherwise they come last (macOS: the bundled VM when no container runtime works here).
  else if (wanted === "auto") order = [...order, ...first.filter((id) => !order.includes(id))];
  // OMNIRUSH_BOX_RUNTIME (docker, podman or a path) keeps meaning "this container CLI".
  if (legacyRuntime) order = order.filter((id) => !["bwrap", "lima", "apple", "wslc", "wsl", "wsl-engine"].includes(id));
  // Under the required sandbox on macOS/Windows: the backends whose boxes get their own build
  // folders (driver.shadows: boxrun as root, the WSL distro, the Lima VM) before the others.
  if (preferShadows && wanted === "auto") order = [...order.filter((id) => driverFor({ backend: id }).shadows), ...order.filter((id) => !driverFor({ backend: id }).shadows)];
  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(", ")}`;
  }
  if (farm) {
    for (const id of order) if (!EGRESS_BACKENDS.includes(id)) skipped.push({ backend: id, name: id, ok: false, reason: "cannot keep a farm session offline" });
    order = EGRESS_BACKENDS.filter((id) => order.includes(id));
    why += "; farm mode: the backends that keep the session offline";
  }
  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 === "lima") found = [{ backend: "lima", ...(await probeLima({ env, platform, arch, release, run, exists, home: boxHome ?? path.join(home, ".omnirush", "box"), explicit: wanted === "lima", ...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, explicit: wanted === "wslc", ...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();
  // Opt-in backends are listed for the status, never probed or started unless chosen.
  if (all && wanted === "auto") for (const id of OPT_IN[platform] ?? []) if (!results.some((r) => r.backend === id)) results.push({ backend: id, name: id, ok: false, reason: "opt-in only: choose it in Settings (sandbox backend)" });
  if (all && wanted === "auto" && !required) for (const id of REQUIRED_FIRST[platform] ?? []) if (!results.some((r) => r.backend === id)) results.push({ backend: id, name: id, ok: false, reason: "used when the sandbox is required on this account, or when chosen in Settings (sandbox backend)" });
  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, required), 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;
}