Skip to content

A desktop coding agent with free access to frontier models.

TypeScript

feat: run commands in a per-project linux sandbox

ogsamrate382980a0742
diff --git a/apps/app/src/app/lib/omnirush-server.ts b/apps/app/src/app/lib/omnirush-server.ts
index 2fe7df8e..480f1e18 100644
--- a/apps/app/src/app/lib/omnirush-server.ts
+++ b/apps/app/src/app/lib/omnirush-server.ts
@@ -427,6 +427,27 @@ export type OmniRushBestPracticesChange = OmniRushBestPractices & {
engine: { status: "applied" | "deferred" | "failed" | "unconfigured" };
};
+/**
+ * GET /workspace/:id/box: the workspace's Linux sandbox (commands run in a
+ * per-project container on this computer). `mode` null: the server's default.
+ */
+export type OmniRushWorkspaceBox = {
+ mode: "on" | "off" | null;
+ serverDefault: "off" | "offer" | "on";
+ on: boolean;
+ source: "env" | "project" | "server" | "default";
+ 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;
+ image: { ref: string; stack: string; present: boolean | null; downloading: boolean } | null;
+ container: { name: string; exists: boolean; running: boolean } | null;
+ notice: string | null;
+ error: string | null;
+};
+export type OmniRushWorkspaceBoxChange = OmniRushWorkspaceBox & {
+ engine: { status: "unchanged" | "applied" | "deferred" | "failed" | "unmanaged" };
+};
+
/** The sub-agent model and effort (Settings > Preferences and the composer's Sub-agents menu). */
export type OmniRushSubagentModelSetting = {
/** An omnirush.ai catalog model id; null runs sub-agents on the main agent's model. */
@@ -1928,6 +1949,18 @@ export function createOmniRushServerClient(options: { baseUrl: string; token?: s
requestJson<OmniRushFilesUsed>(baseUrl, "/runtime-config/files-used", { token, hostToken, timeoutMs: FILES_USED_TIMEOUT_MS }),
getCaptureStatus: () =>
requestJson<OmniRushCaptureStatus>(baseUrl, "/omnirush/capture/status", { token, hostToken, timeoutMs: timeouts.config }),
+ getWorkspaceBox: (workspaceId: string, options?: { fresh?: boolean }) =>
+ requestJson<OmniRushWorkspaceBox>(baseUrl, `/workspace/${encodeURIComponent(workspaceId)}/box${options?.fresh ? "?fresh=1" : ""}`, {
+ token, hostToken, timeoutMs: timeouts.config,
+ }),
+ setWorkspaceBox: (workspaceId: string, mode: "on" | "off" | null) =>
+ requestJson<OmniRushWorkspaceBoxChange>(baseUrl, `/workspace/${encodeURIComponent(workspaceId)}/box`, {
+ token, hostToken, method: "PUT", body: { mode }, timeoutMs: ENGINE_RELOAD_TIMEOUT_MS,
+ }),
+ resetWorkspaceBox: (workspaceId: string) =>
+ requestJson<{ removed: boolean }>(baseUrl, `/workspace/${encodeURIComponent(workspaceId)}/box/reset`, {
+ token, hostToken, method: "POST", body: {}, timeoutMs: 90_000,
+ }),
getBestPractices: () =>
requestJson<OmniRushBestPractices>(baseUrl, "/runtime-config/best-practices", { token, hostToken, timeoutMs: timeouts.config }),
setBestPractices: (enabled: boolean) =>
diff --git a/apps/app/src/react-app/domains/settings/linux-sandbox.ts b/apps/app/src/react-app/domains/settings/linux-sandbox.ts
new file mode 100644
index 00000000..0da933a9
--- /dev/null
+++ b/apps/app/src/react-app/domains/settings/linux-sandbox.ts
@@ -0,0 +1,106 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+
+import type { OmniRushServerClient, OmniRushWorkspaceBox } from "@/app/lib/omnirush-server";
+
+export type LinuxSandboxClient = Pick<OmniRushServerClient, "getWorkspaceBox" | "setWorkspaceBox" | "resetWorkspaceBox">;
+
+export const LINUX_SANDBOX_HELP = "Commands run in a Linux container for this project. Your files stay in this folder; installs are kept per project.";
+
+/** The one line under the switch: what the sandbox is doing now, or why it is not used. */
+export function linuxSandboxStatusLine(box: OmniRushWorkspaceBox): string {
+ if (!box.on) {
+ if (box.offer) return "Your omnirush.ai server suggests turning this on for this project.";
+ if (box.source === "env") return "Turned off for this app (OMNIRUSH_BOX).";
+ return "Off. Commands run on this computer.";
+ }
+ const runtime = box.runtime?.ok ? [box.runtime.name, box.runtime.flavor && box.runtime.flavor !== "engine" ? box.runtime.flavor : null].filter(Boolean).join(", ") : null;
+ switch (box.state) {
+ case "unavailable":
+ return box.notice ?? `Not available: ${box.runtime?.reason ?? "no container runtime found"}. Commands run on this computer.`;
+ case "downloading":
+ return "Downloading the sandbox image (once). Commands run on this computer until it is ready.";
+ case "starting":
+ return runtime ? `Starting the sandbox (${runtime})…` : "Starting the sandbox…";
+ case "ready":
+ return `Ready${runtime ? ` (${runtime})` : ""}${box.container?.running ? ", container running" : ""}.`;
+ case "failed":
+ return `The sandbox could not start${box.error ? `: ${box.error}` : ""}. Commands run on this computer.`;
+ case "off":
+ return box.notice ?? "Off. Commands run on this computer.";
+ }
+}
+
+/** States that change on their own: the card asks again while it shows one. */
+const MOVING = new Set<OmniRushWorkspaceBox["state"]>(["downloading", "starting"]);
+const POLL_MS = 5_000;
+
+/** The selected workspace's sandbox: its status (polled while it moves), the switch and Reset. */
+export function useLinuxSandbox(client: LinuxSandboxClient | null, workspaceId: string | null) {
+ const [box, setBox] = useState<OmniRushWorkspaceBox | null>(null);
+ const [busy, setBusy] = useState(false);
+ const [status, setStatus] = useState("");
+ const sequence = useRef(0);
+
+ const load = useCallback(async (fresh = false) => {
+ if (!client || !workspaceId) return;
+ const startedAt = sequence.current;
+ const value = await client.getWorkspaceBox(workspaceId, { fresh }).catch(() => null);
+ if (sequence.current !== startedAt) return;
+ if (value) setBox(value);
+ else setStatus("The sandbox status could not be loaded.");
+ }, [client, workspaceId]);
+
+ useEffect(() => {
+ sequence.current += 1;
+ setBox(null);
+ setBusy(false);
+ setStatus("");
+ void load(true);
+ }, [load]);
+
+ useEffect(() => {
+ if (!box || !box.on || !MOVING.has(box.state)) return;
+ const timer = setTimeout(() => void load(), POLL_MS);
+ return () => clearTimeout(timer);
+ }, [box, load]);
+
+ const setEnabled = useCallback(async (enabled: boolean) => {
+ if (!client || !workspaceId || busy) return;
+ sequence.current += 1;
+ const startedAt = sequence.current;
+ setBusy(true);
+ setStatus(enabled ? "Turning the sandbox on…" : "Turning the sandbox off…");
+ try {
+ const result = await client.setWorkspaceBox(workspaceId, enabled ? "on" : "off");
+ if (sequence.current !== startedAt) return;
+ setBox(result);
+ setStatus(result.engine.status === "failed" ? "Saved. The engine change could not be confirmed: use Reload in Settings." : "");
+ } catch {
+ if (sequence.current !== startedAt) return;
+ setStatus("The choice could not be saved. Try again.");
+ } finally {
+ if (sequence.current === startedAt) setBusy(false);
+ }
+ }, [busy, client, workspaceId]);
+
+ const reset = useCallback(async () => {
+ if (!client || !workspaceId || busy) return;
+ sequence.current += 1;
+ const startedAt = sequence.current;
+ setBusy(true);
+ setStatus("Resetting the sandbox…");
+ try {
+ const result = await client.resetWorkspaceBox(workspaceId);
+ if (sequence.current !== startedAt) return;
+ setStatus(result.removed ? "Sandbox reset. The next chat starts a fresh one." : "There was no sandbox to reset.");
+ } catch {
+ if (sequence.current !== startedAt) return;
+ setStatus("The sandbox could not be reset. Try again.");
+ } finally {
+ if (sequence.current === startedAt) setBusy(false);
+ }
+ await load(true);
+ }, [busy, client, load, workspaceId]);
+
+ return { box, busy, status, setEnabled, reset };
+}
diff --git a/apps/app/src/react-app/domains/settings/pages/general-view.tsx b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
index df244a38..0263de82 100644
--- a/apps/app/src/react-app/domains/settings/pages/general-view.tsx
+++ b/apps/app/src/react-app/domains/settings/pages/general-view.tsx
@@ -10,12 +10,14 @@ import {
ShieldCheck,
Sparkles,
Terminal,
+ Box,
Wrench,
UserRoundCheck,
} from "lucide-react";
import type { OmniRushAccountSignOutReason } from "@omnirush/types/desktop-ipc";
+import { Button } from "@/components/ui/button";
import { Switch } from "@/components/ui/switch";
import { t } from "../../../../i18n";
import type { SettingsTab } from "../../../../app/types";
@@ -24,7 +26,7 @@ import {
omnirushAccountSignOut,
omnirushAccountStatus,
} from "../../../../app/lib/desktop";
-import type { OmniRushRuntimeApprovals } from "../../../../app/lib/omnirush-server";
+import type { OmniRushRuntimeApprovals, OmniRushWorkspaceBox } from "../../../../app/lib/omnirush-server";
import { omnirushUsageSummary } from "../../../../app/lib/omnirush-usage";
import { isElectronRuntime } from "../../../../app/utils";
import {
@@ -35,6 +37,7 @@ import {
} from "../approval-mode";
import { DiagnosticsSection } from "./diagnostics-section";
import { BEST_PRACTICES_HELP, useBestPractices, type BestPracticesClient } from "../best-practices";
+import { LINUX_SANDBOX_HELP, linuxSandboxStatusLine, useLinuxSandbox, type LinuxSandboxClient } from "../linux-sandbox";
export type GeneralSettingsViewProps = {
onNavigateTab: (tab: SettingsTab) => void;
@@ -45,6 +48,9 @@ export type GeneralSettingsViewProps = {
bestPracticesClient?: BestPracticesClient | null;
/** Workspace whose engine is reloaded after the approval mode changes. */
runtimeWorkspaceId?: string | null;
+ /** The Linux sandbox card (per project); hidden without a client or a selected workspace. */
+ linuxSandboxClient?: LinuxSandboxClient | null;
+ sandboxWorkspaceId?: string | null;
/** Builds the sanitized diagnostics bundle with the route's context. */
buildDiagnosticsBundle?: () => Promise<string>;
};
@@ -211,6 +217,52 @@ export function BestPracticesCard(props: {
);
}
+/**
+ * Settings > General > Linux sandbox (beta): the selected project's choice,
+ * what the sandbox is doing, and Reset (removes its container and installs).
+ */
+export function LinuxSandboxCard(props: {
+ box: OmniRushWorkspaceBox | null;
+ busy: boolean;
+ status: string;
+ onToggle: (enabled: boolean) => void;
+ onReset: () => void;
+}) {
+ const box = props.box;
+ return (
+ <div className="space-y-3">
+ <div className="text-[11px] font-semibold uppercase tracking-[0.15em] text-dls-secondary">Linux sandbox</div>
+ <div className="flex items-center gap-4 rounded-2xl border border-dls-border bg-dls-surface p-4">
+ <div className="flex h-10 w-10 shrink-0 items-center justify-center rounded-xl border border-dls-border bg-dls-hover">
+ <Box size={17} className="text-dls-secondary" />
+ </div>
+ <div className="min-w-0 flex-1">
+ <div className="text-[13px] font-medium text-dls-text">Run commands in a Linux sandbox (beta)</div>
+ <div id="linux-sandbox-help" className="text-[11px] text-dls-secondary">{LINUX_SANDBOX_HELP}</div>
+ {/* TODO(Sam): data-collection wording for sandboxed chats goes here (what uploads record about the
+ sandbox: Linux as the OS, the container image, per-turn changes outside the project). No copy yet. */}
+ {box ? (
+ <div className="mt-0.5 text-[11px] text-dls-secondary" role="status" data-testid="linux-sandbox-state">{linuxSandboxStatusLine(box)}</div>
+ ) : null}
+ {props.status ? (
+ <div className="mt-0.5 text-[11px] text-dls-secondary" data-testid="linux-sandbox-status">{props.status}</div>
+ ) : null}
+ </div>
+ {box?.on && box.container?.exists ? (
+ <Button variant="outline" size="xs" disabled={props.busy} onClick={props.onReset}>Reset sandbox</Button>
+ ) : null}
+ <Switch
+ aria-label="Run commands in a Linux sandbox"
+ aria-describedby="linux-sandbox-help"
+ checked={box?.on === true}
+ disabled={props.busy || !box || box.source === "env"}
+ onCheckedChange={props.onToggle}
+ />
+ </div>
+ </div>
+ );
+}
+
export function GeneralSettingsView(props: GeneralSettingsViewProps) {
const [account, setAccount] = useState<NativeAccountStatus | null>(null);
const [accountBusy, setAccountBusy] = useState(false);
@@ -219,6 +271,8 @@ export function GeneralSettingsView(props: GeneralSettingsViewProps) {
const approvalMode = useApprovalMode(approvalsClient, props.runtimeWorkspaceId ?? null);
const bestPracticesClient = props.bestPracticesClient ?? null;
const bestPractices = useBestPractices(bestPracticesClient);
+ const linuxSandboxClient = props.linuxSandboxClient ?? null;
+ const linuxSandbox = useLinuxSandbox(linuxSandboxClient, props.sandboxWorkspaceId ?? null);
useEffect(() => {
if (!isElectronRuntime()) return;
@@ -375,6 +429,16 @@ export function GeneralSettingsView(props: GeneralSettingsViewProps) {
/>
) : null}
+ {linuxSandboxClient && props.sandboxWorkspaceId ? (
+ <LinuxSandboxCard
+ box={linuxSandbox.box}
+ busy={linuxSandbox.busy}
+ status={linuxSandbox.status}
+ onToggle={(enabled) => void linuxSandbox.setEnabled(enabled)}
+ onReset={() => void linuxSandbox.reset()}
+ />
+ ) : null}
+
<DiagnosticsSection buildBundle={props.buildDiagnosticsBundle} />
</div>
);
diff --git a/apps/app/src/react-app/shell/settings-route.tsx b/apps/app/src/react-app/shell/settings-route.tsx
index 39c55f4a..bcfd1cb9 100644
--- a/apps/app/src/react-app/shell/settings-route.tsx
+++ b/apps/app/src/react-app/shell/settings-route.tsx
@@ -2286,6 +2286,8 @@ function SettingsRouteContent(props: SettingsSurfaceProps = {}) {
omnirushClient={omnirushClient}
bestPracticesClient={bestPracticesClient}
runtimeWorkspaceId={runtimeWorkspaceId}
+ linuxSandboxClient={omnirushClient}
+ sandboxWorkspaceId={selectedWorkspaceId || runtimeWorkspaceId}
buildDiagnosticsBundle={() => buildDiagnosticsBundleJson({
developerMode,
omnirushServerStatus: routeOmniRushStatus,
diff --git a/apps/app/tests/linux-sandbox-card.test.tsx b/apps/app/tests/linux-sandbox-card.test.tsx
new file mode 100644
index 00000000..ac9f931c
--- /dev/null
+++ b/apps/app/tests/linux-sandbox-card.test.tsx
@@ -0,0 +1,57 @@
+import { describe, expect, test } from "bun:test";
+import { renderToStaticMarkup } from "react-dom/server";
+
+import type { OmniRushWorkspaceBox } from "../src/app/lib/omnirush-server";
+import { LinuxSandboxCard } from "../src/react-app/domains/settings/pages/general-view";
+import { LINUX_SANDBOX_HELP, linuxSandboxStatusLine } from "../src/react-app/domains/settings/linux-sandbox";
+
+function box(overrides: Partial<OmniRushWorkspaceBox> = {}): OmniRushWorkspaceBox {
+ return {
+ mode: null,
+ serverDefault: "off",
+ on: false,
+ source: "default",
+ offer: false,
+ state: "off",
+ runtime: { ok: true, name: "docker", flavor: "desktop", version: "27.1", reason: null },
+ image: { ref: "ghcr.io/omnirush-ai/box-base:2026.10.1", stack: "base", present: true, downloading: false },
+ container: null,
+ notice: null,
+ error: null,
+ ...overrides,
+ };
+}
+
+function switchMarkup(markup: string): string {
+ const match = markup.match(/<[a-z]+[^>]*role="switch"[^>]*>/);
+ if (!match) throw new Error(`no switch in ${markup}`);
+ return match[0];
+}
+
+describe("Linux sandbox card", () => {
+ test("off: the switch, its help, and the offer line when the server suggests it", () => {
+ const markup = renderToStaticMarkup(<LinuxSandboxCard box={box({ serverDefault: "offer", source: "server", offer: true })} busy={false} status="" onToggle={() => {}} onReset={() => {}} />);
+ expect(markup).toContain("Run commands in a Linux sandbox (beta)");
+ expect(markup).toContain(LINUX_SANDBOX_HELP);
+ expect(markup).toContain("suggests turning this on");
+ expect(switchMarkup(markup)).toContain('aria-checked="false"');
+ expect(markup).not.toContain("Reset sandbox");
+ });
+
+ test("on: what the sandbox is doing, and Reset once a container exists", () => {
+ const ready = renderToStaticMarkup(<LinuxSandboxCard box={box({ mode: "on", on: true, source: "project", state: "ready", container: { name: "omnirush-box-abc", exists: true, running: true } })} busy={false} status="" onToggle={() => {}} onReset={() => {}} />);
+ expect(switchMarkup(ready)).toContain('aria-checked="true"');
+ expect(ready).toContain("Ready (docker, desktop), container running.");
+ expect(ready).toContain("Reset sandbox");
+ // Nothing is claimed before the server answers.
+ const loading = renderToStaticMarkup(<LinuxSandboxCard box={null} busy={false} status="" onToggle={() => {}} onReset={() => {}} />);
+ expect(switchMarkup(loading)).toContain('aria-disabled="true"');
+ });
+
+ test("status lines: unavailable, downloading, failed, forced by the environment", () => {
+ expect(linuxSandboxStatusLine(box({ on: true, state: "unavailable", runtime: { ok: false, name: null, flavor: null, version: null, reason: "Docker is installed but not running" } }))).toBe("Not available: Docker is installed but not running. Commands run on this computer.");
+ expect(linuxSandboxStatusLine(box({ on: true, state: "downloading" }))).toContain("Downloading the sandbox image (once)");
+ expect(linuxSandboxStatusLine(box({ on: true, state: "failed", error: "could not start the sandbox: x" }))).toBe("The sandbox could not start: could not start the sandbox: x. Commands run on this computer.");
+ expect(linuxSandboxStatusLine(box({ source: "env" }))).toContain("OMNIRUSH_BOX");
+ });
+});
diff --git a/apps/desktop/box/go/cmd/boxd/main.go b/apps/desktop/box/go/cmd/boxd/main.go
new file mode 100644
index 00000000..cd97936a
--- /dev/null
+++ b/apps/desktop/box/go/cmd/boxd/main.go
@@ -0,0 +1,922 @@
+//go:build linux
+
+// boxd runs inside an OmniRush box (one persistent Linux container per
+// project). It executes the agent's shell commands for the host-side shell
+// client (boxsh) over one TCP connection per command, so a tool call costs a
+// fork/exec instead of a `docker exec` round trip, and it reads the files a
+// turn changed for the per-turn snapshot (stat + tar).
+//
+// Configuration (environment, removed before any command runs):
+//
+// BOXD_TOKEN shared secret; every request must carry it
+// BOXD_LISTEN address to listen on (default 0.0.0.0:7777)
+// BOXD_UID, BOXD_GID who commands run as (default 0:0)
+// BOXD_HOME HOME for commands (default /root)
+// BOXD_ROOT the project folder inside (fallback working directory)
+// BOXD_PATH folders put in front of PATH (the package-manager wrappers)
+// BOXD_ENV_FILE KEY=VALUE lines read before each command (host-written)
+// BOXD_SHELL shell for commands (default /bin/bash, else /bin/sh)
+package main
+
+import (
+ "archive/tar"
+ "bufio"
+ "compress/gzip"
+ "encoding/gob"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+ "log"
+ "net"
+ "os"
+ "io/fs"
+ "os/exec"
+ "path/filepath"
+ "os/signal"
+ "sort"
+ "strconv"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "syscall"
+ "time"
+
+ "omnirush.ai/box/proto"
+)
+
+var version = "dev"
+
+type config struct {
+ token string
+ listen string
+ uid int
+ gid int
+ home string
+ root string
+ pathPre string
+ envFile string
+ shell string
+ baseEnv []string
+}
+
+// snapshotGate lets a snapshot read the files with no new command starting
+// meanwhile. Both waits are bounded: a command that never ends (a server in
+// the foreground) cannot hold a snapshot, and a snapshot cannot hold
+// commands for long.
+type snapshotGate struct {
+ mu sync.Mutex
+ running int
+ snap bool
+}
+
+var gate snapshotGate
+
+// enter waits (up to max) for a snapshot to end, then counts a command in.
+func (g *snapshotGate) enter(max time.Duration) {
+ deadline := time.Now().Add(max)
+ for {
+ g.mu.Lock()
+ if !g.snap || time.Now().After(deadline) {
+ g.running++
+ g.mu.Unlock()
+ return
+ }
+ g.mu.Unlock()
+ time.Sleep(5 * time.Millisecond)
+ }
+}
+
+func (g *snapshotGate) leave() {
+ g.mu.Lock()
+ g.running--
+ g.mu.Unlock()
+}
+
+// begin stops new commands and waits (up to max) for running ones; it
+// reports whether the box was quiet.
+func (g *snapshotGate) begin(max time.Duration) bool {
+ g.mu.Lock()
+ g.snap = true
+ g.mu.Unlock()
+ deadline := time.Now().Add(max)
+ for {
+ g.mu.Lock()
+ quiet := g.running == 0
+ g.mu.Unlock()
+ if quiet {
+ return true
+ }
+ if time.Now().After(deadline) {
+ return false
+ }
+ time.Sleep(5 * time.Millisecond)
+ }
+}
+
+func (g *snapshotGate) end() {
+ g.mu.Lock()
+ g.snap = false
+ g.mu.Unlock()
+}
+
+func main() {
+ if len(os.Args) > 1 && os.Args[1] == "--version" {
+ fmt.Println(version)
+ return
+ }
+ cfg := loadConfig()
+ log.SetFlags(log.LstdFlags | log.Lmicroseconds)
+ log.SetPrefix("boxd ")
+ // The command user first, then the image's file index (once per
+ // container, before anything runs in it): the user's setup is not a change.
+ _, statErr := os.Stat(baselineFile)
+ first := statErr != nil
+ prepareUser(cfg, first)
+ if first {
+ start := time.Now()
+ n, err := writeBaseline()
+ log.Printf("baseline: %d entries in %v (err=%v)", n, time.Since(start), err)
+ }
+ ln, err := net.Listen("tcp", cfg.listen)
+ if err != nil {
+ log.Fatalf("listen: %v", err)
+ }
+ // Reap orphans when we are PID 1 (no --init).
+ if os.Getpid() == 1 {
+ go reap()
+ }
+ sigs := make(chan os.Signal, 1)
+ signal.Notify(sigs, syscall.SIGTERM, syscall.SIGINT)
+ go func() {
+ <-sigs
+ _ = ln.Close()
+ os.Exit(0)
+ }()
+ log.Printf("ready %s listen=%s uid=%d", version, cfg.listen, cfg.uid)
+ for {
+ conn, err := ln.Accept()
+ if err != nil {
+ if errors.Is(err, net.ErrClosed) {
+ return
+ }
+ log.Printf("accept: %v", err)
+ time.Sleep(50 * time.Millisecond)
+ continue
+ }
+ if tcp, ok := conn.(*net.TCPConn); ok {
+ _ = tcp.SetNoDelay(true)
+ }
+ go serve(cfg, conn)
+ }
+}
+
+func loadConfig() config {
+ get := func(k, d string) string {
+ v := os.Getenv(k)
+ if v == "" {
+ return d
+ }
+ return v
+ }
+ atoi := func(k string) int {
+ n, _ := strconv.Atoi(os.Getenv(k))
+ return n
+ }
+ cfg := config{
+ token: os.Getenv("BOXD_TOKEN"),
+ listen: get("BOXD_LISTEN", "0.0.0.0:7777"),
+ uid: atoi("BOXD_UID"),
+ gid: atoi("BOXD_GID"),
+ home: get("BOXD_HOME", "/root"),
+ root: get("BOXD_ROOT", "/"),
+ pathPre: os.Getenv("BOXD_PATH"),
+ envFile: os.Getenv("BOXD_ENV_FILE"),
+ shell: os.Getenv("BOXD_SHELL"),
+ }
+ if cfg.shell == "" {
+ cfg.shell = "/bin/bash"
+ if _, err := os.Stat(cfg.shell); err != nil {
+ cfg.shell = "/bin/sh"
+ }
+ }
+ for _, kv := range os.Environ() {
+ if strings.HasPrefix(kv, "BOXD_") {
+ continue
+ }
+ cfg.baseEnv = append(cfg.baseEnv, kv)
+ }
+ for _, k := range []string{"BOXD_TOKEN", "BOXD_LISTEN", "BOXD_UID", "BOXD_GID", "BOXD_HOME", "BOXD_ROOT", "BOXD_PATH", "BOXD_ENV_FILE", "BOXD_SHELL"} {
+ _ = os.Unsetenv(k)
+ }
+ if cfg.token == "" {
+ log.Fatal("BOXD_TOKEN is not set")
+ }
+ return cfg
+}
+
+// prepareUser gives a non-root command user (the uid-matched user of a
+// rootful Docker) an account, HOME=/root that it owns, and passwordless sudo
+// that keeps PATH (so the package-manager wrappers stay in front).
+func prepareUser(cfg config, first bool) {
+ _ = os.MkdirAll(cfg.home, 0o755)
+ if cfg.uid == 0 {
+ return
+ }
+ uid, gid := strconv.Itoa(cfg.uid), strconv.Itoa(cfg.gid)
+ if _, err := exec.LookPath("useradd"); err == nil {
+ _ = exec.Command("groupadd", "-o", "-g", gid, "omnirush").Run()
+ _ = exec.Command("useradd", "-o", "-u", uid, "-g", gid, "-M", "-d", cfg.home, "-s", "/bin/bash", "omnirush").Run()
+ }
+ ensureLine("/etc/group", ":"+gid+":", fmt.Sprintf("omnirush:x:%d:\n", cfg.gid))
+ ensureLine("/etc/passwd", ":"+uid+":", fmt.Sprintf("omnirush:x:%d:%d:omnirush:%s:/bin/bash\n", cfg.uid, cfg.gid, cfg.home))
+ if data, err := os.ReadFile("/etc/shadow"); err == nil && !strings.Contains(string(data), "\nomnirush:") && !strings.HasPrefix(string(data), "omnirush:") {
+ if f, err := os.OpenFile("/etc/shadow", os.O_APPEND|os.O_WRONLY, 0); err == nil {
+ _, _ = f.WriteString("omnirush:*:20000:0:99999:7:::\n")
+ f.Close()
+ }
+ }
+ if first {
+ // HOME is the user's: what the image put there (.local, .cache) too.
+ _ = filepath.WalkDir(cfg.home, func(p string, d fs.DirEntry, err error) error {
+ if err == nil {
+ _ = os.Lchown(p, cfg.uid, cfg.gid)
+ }
+ return nil
+ })
+ }
+ if _, err := os.Stat("/etc/sudoers.d"); err == nil {
+ rule := "omnirush ALL=(ALL) NOPASSWD:ALL\nDefaults:omnirush !secure_path\nDefaults:omnirush !requiretty\nDefaults:omnirush env_keep += \"PATH PYTHONPATH NODE_OPTIONS HOME OMNIRUSH_HOOKS OMNIRUSH_LEDGER OMNIRUSH_STATE_DIR OMNIRUSH_TURN OMNIRUSH_CALL\"\n"
+ _ = os.WriteFile("/etc/sudoers.d/omnirush", []byte(rule), 0o440)
+ }
+}
+
+func ensureLine(file, needle, line string) {
+ data, _ := os.ReadFile(file)
+ for _, l := range strings.Split(string(data), "\n") {
+ parts := strings.Split(l, ":")
+ if len(parts) > 2 && ":"+parts[2]+":" == needle {
+ return
+ }
+ }
+ f, err := os.OpenFile(file, os.O_APPEND|os.O_WRONLY|os.O_CREATE, 0o644)
+ if err != nil {
+ return
+ }
+ defer f.Close()
+ if len(data) > 0 && data[len(data)-1] != '\n' {
+ _, _ = f.WriteString("\n")
+ }
+ _, _ = f.WriteString(line)
+}
+
+func reap() {
+ for {
+ var status syscall.WaitStatus
+ pid, err := syscall.Wait4(-1, &status, 0, nil)
+ if err != nil || pid <= 0 {
+ time.Sleep(200 * time.Millisecond)
+ }
+ }
+}
+
+// conn wraps a connection with a write lock (frames come from several goroutines).
+type conn struct {
+ net.Conn
+ r *bufio.Reader
+ mu sync.Mutex
+}
+
+func (c *conn) frame(kind byte, payload []byte) error {
+ c.mu.Lock()
+ defer c.mu.Unlock()
+ return proto.WriteFrame(c.Conn, kind, payload)
+}
+
+func (c *conn) exit(info proto.ExitInfo) {
+ data, _ := json.Marshal(info)
+ _ = c.frame(proto.Exit, data)
+}
+
+func (c *conn) fail(start time.Time, err error) {
+ _ = c.frame(proto.Fail, []byte(err.Error()))
+ c.exit(proto.ExitInfo{Code: 125, Ms: ms(start)})
+}
+
+func ms(start time.Time) float64 {
+ return float64(time.Since(start).Microseconds()) / 1000
+}
+
+func serve(cfg config, raw net.Conn) {
+ defer raw.Close()
+ c := &conn{Conn: raw, r: bufio.NewReaderSize(raw, 64<<10)}
+ start := time.Now()
+ _ = raw.SetReadDeadline(time.Now().Add(10 * time.Second))
+ req, err := proto.ReadRequest(c.r, cfg.token)
+ _ = raw.SetReadDeadline(time.Time{})
+ if err != nil {
+ c.fail(start, err)
+ return
+ }
+ switch req.Op {
+ case "ping":
+ info, _ := json.Marshal(map[string]any{"version": version, "pid": os.Getpid(), "uid": cfg.uid, "home": cfg.home, "root": cfg.root, "shell": cfg.shell})
+ _ = c.frame(proto.Data, info)
+ c.exit(proto.ExitInfo{Ms: ms(start)})
+ case "exec":
+ runExec(cfg, c, req, start)
+ case "stat":
+ out, _ := json.Marshal(statPaths(req.Paths))
+ _ = c.frame(proto.Data, out)
+ c.exit(proto.ExitInfo{Ms: ms(start)})
+ case "changes":
+ // What differs from the image (like `docker diff`, with stat fields),
+ // by walking the box and comparing with the baseline index. Paths are
+ // folders not walked (caches; their kept subfolders are walked).
+ out, err := changes(req.Paths, req.Env)
+ if err != nil {
+ c.fail(start, err)
+ return
+ }
+ _ = c.frame(proto.Data, out)
+ c.exit(proto.ExitInfo{Ms: ms(start)})
+ case "walk":
+ // Every entry below the given folders (dependency folders inside
+ // the project), with the stat fields of the snapshot diff.
+ max := req.Wait
+ if max <= 0 {
+ max = 400000
+ }
+ entries, truncated := walkPaths(req.Paths, max)
+ out, _ := json.Marshal(map[string]any{"entries": entries, "truncated": truncated})
+ _ = c.frame(proto.Data, out)
+ c.exit(proto.ExitInfo{Ms: ms(start)})
+ case "tar":
+ // No new command starts while the snapshot reads the files.
+ quiet := gate.begin(3 * time.Second)
+ err := writeTar(c, req.Paths, cfg.uid, cfg.gid)
+ gate.end()
+ if !quiet {
+ _ = c.frame(proto.Stderr, []byte("busy: a command was running during the snapshot\n"))
+ }
+ if err != nil {
+ c.fail(start, err)
+ return
+ }
+ c.exit(proto.ExitInfo{Ms: ms(start)})
+ default:
+ c.fail(start, fmt.Errorf("unknown op %q", req.Op))
+ }
+}
+
+func commandEnv(cfg config, extra map[string]string) []string {
+ env := map[string]string{}
+ order := []string{}
+ set := func(k, v string) {
+ if _, ok := env[k]; !ok {
+ order = append(order, k)
+ }
+ env[k] = v
+ }
+ for _, kv := range cfg.baseEnv {
+ if i := strings.IndexByte(kv, '='); i > 0 {
+ set(kv[:i], kv[i+1:])
+ }
+ }
+ set("HOME", cfg.home)
+ user := "root"
+ if cfg.uid != 0 {
+ user = "omnirush"
+ }
+ set("USER", user)
+ set("LOGNAME", user)
+ if env["PATH"] == "" {
+ set("PATH", "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin")
+ }
+ if cfg.envFile != "" {
+ if data, err := os.ReadFile(cfg.envFile); err == nil {
+ for _, line := range strings.Split(string(data), "\n") {
+ line = strings.TrimSpace(line)
+ if line == "" || strings.HasPrefix(line, "#") {
+ continue
+ }
+ if i := strings.IndexByte(line, '='); i > 0 {
+ set(line[:i], line[i+1:])
+ }
+ }
+ }
+ }
+ for k, v := range extra {
+ set(k, v)
+ }
+ // The package-manager wrappers' folder, written by the launcher after the start.
+ if pre, ok := env["BOXD_PATH_PREFIX"]; ok {
+ delete(env, "BOXD_PATH_PREFIX")
+ if pre != "" {
+ set("PATH", pre+":"+env["PATH"])
+ }
+ }
+ if cfg.pathPre != "" {
+ set("PATH", cfg.pathPre+":"+env["PATH"])
+ }
+ out := make([]string, 0, len(order))
+ for _, k := range order {
+ if v, ok := env[k]; ok {
+ out = append(out, k+"="+v)
+ }
+ }
+ return out
+}
+
+func runExec(cfg config, c *conn, req proto.Request, start time.Time) {
+ if len(req.Argv) == 0 {
+ c.fail(start, errors.New("empty argv"))
+ return
+ }
+ // Wait (bounded) for a snapshot in progress, so it sees a quiet box.
+ waitStart := time.Now()
+ wait := time.Duration(req.Wait) * time.Millisecond
+ if wait <= 0 {
+ wait = 15 * time.Second
+ }
+ gate.enter(wait)
+ defer gate.leave()
+ waited := ms(waitStart)
+
+ argv := req.Argv
+ if argv[0] == "" || argv[0] == "$SHELL" {
+ argv = append([]string{cfg.shell}, argv[1:]...)
+ }
+ cmd := exec.Command(argv[0], argv[1:]...)
+ cmd.Env = commandEnv(cfg, req.Env)
+ cmd.Dir = cfg.root
+ if req.Cwd != "" {
+ if st, err := os.Stat(req.Cwd); err == nil && st.IsDir() {
+ cmd.Dir = req.Cwd
+ }
+ }
+ attr := &syscall.SysProcAttr{Setpgid: true}
+ if cfg.uid != 0 && !req.Root {
+ attr.Credential = &syscall.Credential{Uid: uint32(cfg.uid), Gid: uint32(cfg.gid), NoSetGroups: true}
+ }
+ cmd.SysProcAttr = attr
+ // Our own pipes: Wait() would close StdoutPipe's read end and drop
+ // output still buffered in it.
+ stdin, _ := cmd.StdinPipe()
+ outR, outW, err1 := os.Pipe()
+ errR, errW, err2 := os.Pipe()
+ if err1 != nil || err2 != nil {
+ c.fail(start, errors.New("pipe failed"))
+ return
+ }
+ cmd.Stdout, cmd.Stderr = outW, errW
+ if err := cmd.Start(); err != nil {
+ outW.Close()
+ errW.Close()
+ outR.Close()
+ errR.Close()
+ c.fail(start, err)
+ return
+ }
+ outW.Close()
+ errW.Close()
+ defer outR.Close()
+ defer errR.Close()
+ pgid := cmd.Process.Pid
+ kill := func(sig syscall.Signal) { _ = syscall.Kill(-pgid, sig) }
+
+ var lastRead atomic.Int64
+ lastRead.Store(time.Now().UnixNano())
+ var pumps sync.WaitGroup
+ pump := func(r io.Reader, kind byte) {
+ defer pumps.Done()
+ buf := make([]byte, 32<<10)
+ for {
+ n, err := r.Read(buf)
+ if n > 0 {
+ lastRead.Store(time.Now().UnixNano())
+ if c.frame(kind, buf[:n]) != nil {
+ return
+ }
+ }
+ if err != nil {
+ return
+ }
+ }
+ }
+ pumps.Add(2)
+ go pump(outR, proto.Stdout)
+ go pump(errR, proto.Stderr)
+
+ // Client frames: stdin, signals; a closed connection kills the command.
+ done := make(chan struct{})
+ go func() {
+ buf := make([]byte, 0, 64<<10)
+ for {
+ kind, payload, err := proto.ReadFrame(c.r, buf)
+ if err != nil {
+ select {
+ case <-done:
+ default:
+ kill(syscall.SIGKILL)
+ }
+ _ = stdin.Close()
+ return
+ }
+ switch kind {
+ case proto.Stdin:
+ _, _ = stdin.Write(payload)
+ case proto.StdinEOF:
+ _ = stdin.Close()
+ case proto.Signal:
+ kill(parseSignal(string(payload)))
+ }
+ }
+ }()
+
+ err := cmd.Wait()
+ close(done)
+ // Output a background child still holds open is not waited for: the
+ // command is over when its shell exits (as on the host). What is in the
+ // pipes is drained until they close or go quiet.
+ drained := make(chan struct{})
+ go func() { pumps.Wait(); close(drained) }()
+ for quiet := false; !quiet; {
+ select {
+ case <-drained:
+ quiet = true
+ case <-time.After(10 * time.Millisecond):
+ quiet = time.Since(time.Unix(0, lastRead.Load())) > 30*time.Millisecond
+ }
+ }
+ info := proto.ExitInfo{Ms: ms(start), WaitedMs: waited}
+ if err != nil {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ if ws, ok := ee.Sys().(syscall.WaitStatus); ok && ws.Signaled() {
+ info.Signal = ws.Signal().String()
+ info.Code = 128 + int(ws.Signal())
+ } else {
+ info.Code = ee.ExitCode()
+ }
+ } else {
+ info.Code = 126
+ }
+ }
+ c.exit(info)
+}
+
+func parseSignal(name string) syscall.Signal {
+ switch strings.ToUpper(strings.TrimPrefix(strings.ToUpper(name), "SIG")) {
+ case "KILL":
+ return syscall.SIGKILL
+ case "INT":
+ return syscall.SIGINT
+ case "HUP":
+ return syscall.SIGHUP
+ case "QUIT":
+ return syscall.SIGQUIT
+ default:
+ return syscall.SIGTERM
+ }
+}
+
+func statPaths(paths []string) []proto.StatEntry {
+ out := make([]proto.StatEntry, 0, len(paths))
+ for _, p := range paths {
+ var st syscall.Stat_t
+ e := proto.StatEntry{Path: p}
+ if err := syscall.Lstat(p, &st); err != nil {
+ e.Type = "missing"
+ out = append(out, e)
+ continue
+ }
+ e.Mode = st.Mode & 0o7777
+ e.Size = st.Size
+ e.MtimeNs = st.Mtim.Sec*1e9 + st.Mtim.Nsec
+ e.CtimeNs = st.Ctim.Sec*1e9 + st.Ctim.Nsec
+ e.Ino = st.Ino
+ e.Nlink = uint64(st.Nlink)
+ e.UID = st.Uid
+ e.GID = st.Gid
+ switch st.Mode & syscall.S_IFMT {
+ case syscall.S_IFREG:
+ e.Type = "file"
+ case syscall.S_IFDIR:
+ e.Type = "dir"
+ e.Size = 0
+ case syscall.S_IFLNK:
+ e.Type = "symlink"
+ e.Link, _ = os.Readlink(p)
+ default:
+ e.Type = "other"
+ }
+ out = append(out, e)
+ }
+ return out
+}
+
+func walkPaths(roots []string, max int) ([]proto.StatEntry, bool) {
+ var paths []string
+ truncated := false
+ for _, root := range roots {
+ _ = filepath.WalkDir(root, func(p string, d fs.DirEntry, err error) error {
+ if err != nil {
+ return nil
+ }
+ if len(paths) >= max {
+ truncated = true
+ return filepath.SkipAll
+ }
+ paths = append(paths, p)
+ return nil
+ })
+ }
+ return statPaths(paths), truncated
+}
+
+const baselineFile = "/opt/omnirush/state/baseline.gz"
+
+// Folders never walked for changes: kernel and runtime state, our own files.
+var walkSkip = []string{"/proc", "/sys", "/dev", "/run", "/opt/omnirush"}
+
+type sig struct {
+ Mt, Ct, Size int64
+ Mode uint32
+ Ino uint64
+ UID, GID uint32
+ Kind byte
+}
+
+func entrySig(st *syscall.Stat_t) sig {
+ k := byte('o')
+ switch st.Mode & syscall.S_IFMT {
+ case syscall.S_IFREG:
+ k = 'f'
+ case syscall.S_IFDIR:
+ k = 'd'
+ case syscall.S_IFLNK:
+ k = 'l'
+ }
+ s := sig{Mode: st.Mode & 0o7777, Ino: st.Ino, UID: st.Uid, GID: st.Gid, Kind: k}
+ if k != 'd' {
+ s.Mt = st.Mtim.Sec*1e9 + st.Mtim.Nsec
+ s.Ct = st.Ctim.Sec*1e9 + st.Ctim.Nsec
+ s.Size = st.Size
+ }
+ return s
+}
+
+func within(p, dir string) bool {
+ return p == dir || strings.HasPrefix(p, dir+"/")
+}
+
+// skipper: a path under a skipped folder is not walked, unless it leads to
+// or lies in a kept one.
+func skipper(skip, keep []string) func(string) bool {
+ return func(p string) bool {
+ for _, k := range keep {
+ if within(p, k) || within(k, p) {
+ return false
+ }
+ }
+ for _, s := range skip {
+ if within(p, s) {
+ return true
+ }
+ }
+ return false
+ }
+}
+
+// walkRoot visits every path of the box's own filesystem (not other mounts).
+func walkRoot(skipped func(string) bool, visit func(p string, st *syscall.Stat_t)) {
+ var rootSt syscall.Stat_t
+ _ = syscall.Lstat("/", &rootSt)
+ var walk func(dir string)
+ walk = func(dir string) {
+ f, err := os.Open(dir)
+ if err != nil {
+ return
+ }
+ names, _ := f.Readdirnames(-1)
+ f.Close()
+ for _, name := range names {
+ p := dir + "/" + name
+ if dir == "/" {
+ p = "/" + name
+ }
+ if skipped(p) {
+ continue
+ }
+ var st syscall.Stat_t
+ if syscall.Lstat(p, &st) != nil {
+ continue
+ }
+ if st.Dev != rootSt.Dev {
+ continue // a mount: the project folder, docker-init, /etc/hosts
+ }
+ visit(p, &st)
+ if st.Mode&syscall.S_IFMT == syscall.S_IFDIR {
+ walk(p)
+ }
+ }
+ }
+ walk("/")
+}
+
+func writeBaseline() (int, error) {
+ if err := os.MkdirAll(filepath.Dir(baselineFile), 0o700); err != nil {
+ return 0, err
+ }
+ tmp := baselineFile + ".tmp"
+ f, err := os.Create(tmp)
+ if err != nil {
+ return 0, err
+ }
+ zw := gzip.NewWriter(f)
+ enc := gob.NewEncoder(zw)
+ index := map[string]sig{}
+ walkRoot(skipper(walkSkip, nil), func(p string, st *syscall.Stat_t) { index[p] = entrySig(st) })
+ if err := enc.Encode(index); err != nil {
+ f.Close()
+ return 0, err
+ }
+ if err := zw.Close(); err != nil {
+ f.Close()
+ return 0, err
+ }
+ if err := f.Close(); err != nil {
+ return 0, err
+ }
+ return len(index), os.Rename(tmp, baselineFile)
+}
+
+var baselineCache map[string]sig
+
+func loadBaseline() (map[string]sig, error) {
+ if baselineCache != nil {
+ return baselineCache, nil
+ }
+ f, err := os.Open(baselineFile)
+ if err != nil {
+ return nil, fmt.Errorf("no baseline: %w", err)
+ }
+ defer f.Close()
+ zr, err := gzip.NewReader(f)
+ if err != nil {
+ return nil, err
+ }
+ index := map[string]sig{}
+ if err := gob.NewDecoder(zr).Decode(&index); err != nil {
+ return nil, err
+ }
+ baselineCache = index
+ return index, nil
+}
+
+type change struct {
+ Kind string `json:"kind"`
+ proto.StatEntry
+}
+
+// changes lists A/C/D against the image. extra["keep"] (comma list) are
+// folders under a skipped one that are still walked.
+func changes(skip []string, extra map[string]string) ([]byte, error) {
+ base, err := loadBaseline()
+ if err != nil {
+ return nil, err
+ }
+ var keep []string
+ if v := extra["keep"]; v != "" {
+ keep = strings.Split(v, ",")
+ }
+ skipped := skipper(append(append([]string(nil), walkSkip...), skip...), keep)
+ seen := make(map[string]bool, len(base))
+ out := []change{}
+ walkRoot(skipped, func(p string, st *syscall.Stat_t) {
+ seen[p] = true
+ now := entrySig(st)
+ old, ok := base[p]
+ if ok && old == now {
+ return
+ }
+ kind := "A"
+ if ok {
+ kind = "C"
+ }
+ out = append(out, change{Kind: kind, StatEntry: statPaths([]string{p})[0]})
+ })
+ for p := range base {
+ if !seen[p] && !skipped(p) {
+ out = append(out, change{Kind: "D", StatEntry: proto.StatEntry{Path: p, Type: "missing"}})
+ }
+ }
+ sort.Slice(out, func(i, j int) bool { return out[i].Path < out[j].Path })
+ return json.Marshal(out)
+}
+
+// frameWriter streams tar bytes as Data frames.
+type frameWriter struct{ c *conn }
+
+func (w frameWriter) Write(p []byte) (int, error) {
+ if err := w.c.frame(proto.Data, p); err != nil {
+ return 0, err
+ }
+ return len(p), nil
+}
+
+// writeTar writes exactly the listed paths (not recursively): parents before
+// children, numeric owners, a hard link only to a file already in this tar.
+// The command user (a uid-matched user on rootful Docker) is root in the tar:
+// a replay runs as root.
+func writeTar(c *conn, paths []string, uid, gid int) error {
+ sorted := append([]string(nil), paths...)
+ sort.Strings(sorted)
+ bw := bufio.NewWriterSize(frameWriter{c}, 256<<10)
+ tw := tar.NewWriter(bw)
+ seen := map[[2]uint64]string{}
+ for _, p := range sorted {
+ if !strings.HasPrefix(p, "/") {
+ continue
+ }
+ var st syscall.Stat_t
+ if err := syscall.Lstat(p, &st); err != nil {
+ continue // gone meanwhile: the next snapshot sees it
+ }
+ name := strings.TrimPrefix(p, "/")
+ owner, group := int(st.Uid), int(st.Gid)
+ if uid != 0 && owner == uid {
+ owner = 0
+ }
+ if gid != 0 && group == gid {
+ group = 0
+ }
+ hdr := &tar.Header{
+ Name: name,
+ Mode: int64(st.Mode & 0o7777),
+ Uid: owner,
+ Gid: group,
+ ModTime: time.Unix(st.Mtim.Sec, st.Mtim.Nsec),
+ Format: tar.FormatPAX,
+ }
+ switch st.Mode & syscall.S_IFMT {
+ case syscall.S_IFDIR:
+ hdr.Typeflag = tar.TypeDir
+ hdr.Name += "/"
+ if err := tw.WriteHeader(hdr); err != nil {
+ return err
+ }
+ case syscall.S_IFLNK:
+ target, err := os.Readlink(p)
+ if err != nil {
+ continue
+ }
+ hdr.Typeflag = tar.TypeSymlink
+ hdr.Linkname = target
+ if err := tw.WriteHeader(hdr); err != nil {
+ return err
+ }
+ case syscall.S_IFREG:
+ key := [2]uint64{uint64(st.Dev), st.Ino}
+ if first, ok := seen[key]; ok && st.Nlink > 1 {
+ hdr.Typeflag = tar.TypeLink
+ hdr.Linkname = first
+ if err := tw.WriteHeader(hdr); err != nil {
+ return err
+ }
+ continue
+ }
+ f, err := os.Open(p)
+ if err != nil {
+ continue
+ }
+ hdr.Typeflag = tar.TypeReg
+ hdr.Size = st.Size
+ if err := tw.WriteHeader(hdr); err != nil {
+ f.Close()
+ return err
+ }
+ n, err := io.CopyN(tw, f, st.Size)
+ f.Close()
+ if err != nil && !errors.Is(err, io.EOF) {
+ return err
+ }
+ if n < st.Size {
+ // Shrank while read: pad so the archive stays valid.
+ if _, err := tw.Write(make([]byte, st.Size-n)); err != nil {
+ return err
+ }
+ }
+ if st.Nlink > 1 {
+ seen[key] = name
+ }
+ default:
+ continue // fifos, sockets, devices: not environment
+ }
+ }
+ if err := tw.Close(); err != nil {
+ return err
+ }
+ return bw.Flush()
+}
diff --git a/apps/desktop/box/go/cmd/boxd/main_test.go b/apps/desktop/box/go/cmd/boxd/main_test.go
new file mode 100644
index 00000000..e1bbe2de
--- /dev/null
+++ b/apps/desktop/box/go/cmd/boxd/main_test.go
@@ -0,0 +1,180 @@
+//go:build linux
+
+package main
+
+import (
+ "archive/tar"
+ "bufio"
+ "bytes"
+ "encoding/json"
+ "io"
+ "net"
+ "os"
+ "path/filepath"
+ "strings"
+ "testing"
+ "time"
+
+ "omnirush.ai/box/proto"
+)
+
+func startDaemon(t *testing.T) (config, string) {
+ t.Helper()
+ dir := t.TempDir()
+ cfg := config{token: "tok", uid: 0, home: dir, root: dir, shell: "/bin/sh", baseEnv: []string{"PATH=/usr/bin:/bin", "SECRET_FROM_HOST=1"}}
+ cfg.uid = os.Getuid()
+ cfg.gid = os.Getgid()
+ if cfg.uid != 0 {
+ cfg.uid, cfg.gid = 0, 0 // run commands as ourselves (no setuid in tests)
+ }
+ ln, err := net.Listen("tcp", "127.0.0.1:0")
+ if err != nil {
+ t.Fatal(err)
+ }
+ t.Cleanup(func() { ln.Close() })
+ go func() {
+ for {
+ c, err := ln.Accept()
+ if err != nil {
+ return
+ }
+ go serve(cfg, c)
+ }
+ }()
+ return cfg, ln.Addr().String()
+}
+
+type result struct {
+ out, err string
+ data []byte
+ exit proto.ExitInfo
+}
+
+func call(t *testing.T, addr string, req proto.Request, during func(net.Conn)) result {
+ t.Helper()
+ c, err := net.Dial("tcp", addr)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer c.Close()
+ req.Token = "tok"
+ _ = proto.WriteRequest(c, req)
+ _ = proto.WriteFrame(c, proto.StdinEOF, nil)
+ if during != nil {
+ go during(c)
+ }
+ r := bufio.NewReader(c)
+ var res result
+ for {
+ k, p, err := proto.ReadFrame(r, nil)
+ if err != nil {
+ t.Fatal(err)
+ }
+ switch k {
+ case proto.Stdout:
+ res.out += string(p)
+ case proto.Stderr, proto.Fail:
+ res.err += string(p)
+ case proto.Data:
+ res.data = append(res.data, p...)
+ case proto.Exit:
+ _ = json.Unmarshal(p, &res.exit)
+ return res
+ }
+ }
+}
+
+func TestExec(t *testing.T) {
+ cfg, addr := startDaemon(t)
+ res := call(t, addr, proto.Request{Op: "exec", Argv: []string{"/bin/sh", "-c", "echo out; echo err >&2; echo $HOME; echo ${SECRET_FROM_HOST:-none}; echo $TURNX; pwd; exit 3"}, Cwd: "/nonexistent", Env: map[string]string{"TURNX": "7"}}, nil)
+ if res.exit.Code != 3 {
+ t.Fatalf("code %d", res.exit.Code)
+ }
+ lines := strings.Split(strings.TrimSpace(res.out), "\n")
+ if lines[0] != "out" || lines[1] != cfg.home || lines[3] != "7" || lines[4] != cfg.root {
+ t.Fatalf("%q", res.out)
+ }
+ if res.err != "err\n" {
+ t.Fatalf("stderr %q", res.err)
+ }
+ _ = lines[2] // base env passes through (image ENV)
+}
+
+func TestSignal(t *testing.T) {
+ _, addr := startDaemon(t)
+ start := time.Now()
+ res := call(t, addr, proto.Request{Op: "exec", Argv: []string{"/bin/sh", "-c", "sleep 30"}}, func(c net.Conn) {
+ time.Sleep(200 * time.Millisecond)
+ _ = proto.WriteFrame(c, proto.Signal, []byte("TERM"))
+ })
+ if time.Since(start) > 5*time.Second || res.exit.Code != 143 {
+ t.Fatalf("code %d after %v", res.exit.Code, time.Since(start))
+ }
+}
+
+func TestBackgroundChildDoesNotHold(t *testing.T) {
+ _, addr := startDaemon(t)
+ start := time.Now()
+ res := call(t, addr, proto.Request{Op: "exec", Argv: []string{"/bin/sh", "-c", "sleep 20 & echo started"}}, nil)
+ if time.Since(start) > 3*time.Second || !strings.Contains(res.out, "started") {
+ t.Fatalf("took %v out %q", time.Since(start), res.out)
+ }
+}
+
+func TestStatAndTar(t *testing.T) {
+ _, addr := startDaemon(t)
+ dir := t.TempDir()
+ a := filepath.Join(dir, "a.txt")
+ _ = os.WriteFile(a, []byte("hello"), 0o644)
+ _ = os.Link(a, filepath.Join(dir, "hard"))
+ _ = os.Symlink("a.txt", filepath.Join(dir, "link"))
+ _ = os.Mkdir(filepath.Join(dir, "sub"), 0o755)
+ paths := []string{filepath.Join(dir, "link"), a, filepath.Join(dir, "hard"), filepath.Join(dir, "sub"), filepath.Join(dir, "gone")}
+ res := call(t, addr, proto.Request{Op: "stat", Paths: paths}, nil)
+ var st []proto.StatEntry
+ if err := json.Unmarshal(res.data, &st); err != nil || len(st) != 5 || st[4].Type != "missing" || st[0].Type != "symlink" || st[1].Size != 5 {
+ t.Fatalf("%v %s", err, res.data)
+ }
+ res = call(t, addr, proto.Request{Op: "tar", Paths: paths}, nil)
+ if res.exit.Code != 0 {
+ t.Fatalf("tar failed %s", res.err)
+ }
+ tr := tar.NewReader(bytes.NewReader(res.data))
+ kinds := map[string]byte{}
+ for {
+ h, err := tr.Next()
+ if err == io.EOF {
+ break
+ }
+ if err != nil {
+ t.Fatal(err)
+ }
+ kinds[filepath.Base(strings.TrimSuffix(h.Name, "/"))] = h.Typeflag
+ if strings.HasPrefix(h.Name, "/") {
+ t.Fatal("absolute member", h.Name)
+ }
+ }
+ if kinds["a.txt"] != tar.TypeReg || kinds["hard"] != tar.TypeLink || kinds["link"] != tar.TypeSymlink || kinds["sub"] != tar.TypeDir || len(kinds) != 4 {
+ t.Fatalf("%v", kinds)
+ }
+}
+
+func TestBadToken(t *testing.T) {
+ _, addr := startDaemon(t)
+ c, _ := net.Dial("tcp", addr)
+ defer c.Close()
+ _ = proto.WriteRequest(c, proto.Request{Op: "exec", Token: "nope", Argv: []string{"/bin/true"}})
+ k, p, err := proto.ReadFrame(bufio.NewReader(c), nil)
+ if err != nil || k != proto.Fail || !strings.Contains(string(p), "unauthorized") {
+ t.Fatal(k, string(p), err)
+ }
+}
+
+func TestSkipper(t *testing.T) {
+ skip := skipper([]string{"/proc", "/root/.cache"}, []string{"/root/.cache/ms-playwright"})
+ for p, want := range map[string]bool{"/proc": true, "/proc/1": true, "/root/.cache": false, "/root/.cache/pip": true, "/root/.cache/ms-playwright": false, "/root/.cache/ms-playwright/x": false, "/root/.cachex": false, "/usr": false} {
+ if got := skip(p); got != want {
+ t.Errorf("%s: %v", p, got)
+ }
+ }
+}
diff --git a/apps/desktop/box/go/cmd/boxsh/main.go b/apps/desktop/box/go/cmd/boxsh/main.go
new file mode 100644
index 00000000..0e48c5e1
--- /dev/null
+++ b/apps/desktop/box/go/cmd/boxsh/main.go
@@ -0,0 +1,494 @@
+// boxsh is the shell the engine runs its shell tool with when a project's
+// box is on. The engine calls it like a shell (`bash -c <command>`); boxsh
+// runs the command inside the project's box through boxd and streams the
+// output back, with the exit code and signals of a local shell.
+//
+// Which box: OMNIRUSH_BOX_KEY names it (set on the engine by the CLI, or per
+// call by the box plugin); the box's record is <OMNIRUSH_BOX_HOME>/boxes/<key>.json,
+// written by the CLI or the desktop app. With no key, a record that is "off",
+// or a call that is not `-c <command>`, boxsh runs the real shell instead.
+package main
+
+import (
+ "bufio"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "net"
+ "os"
+ "os/exec"
+ "path/filepath"
+ "runtime"
+ "strconv"
+ "strings"
+ "sync"
+ "syscall"
+ "time"
+
+ "omnirush.ai/box/proto"
+)
+
+var version = "dev"
+
+// Record is the box record the CLI/desktop writes (boxes/<key>.json).
+type Record struct {
+ V int `json:"v"`
+ Key string `json:"key"`
+ Root string `json:"root"`
+ CRoot string `json:"croot"`
+ Container string `json:"container"`
+ Runtime string `json:"runtime"`
+ Host string `json:"host"`
+ Port int `json:"port"`
+ Token string `json:"token"`
+ State string `json:"state"`
+ Error string `json:"error"`
+ UID int `json:"uid"`
+ GID int `json:"gid"`
+ Home string `json:"home"`
+ Shell string `json:"shell"`
+ PathPre string `json:"path_prefix"`
+ EnvFile string `json:"env_file"`
+}
+
+func main() {
+ args := os.Args[1:]
+ if len(args) == 1 && args[0] == "--box-version" {
+ fmt.Println(version)
+ return
+ }
+ command, rest, login, ok := parseShellArgs(args)
+ key := strings.TrimSpace(os.Getenv("OMNIRUSH_BOX_KEY"))
+ if !ok || key == "" {
+ native(args)
+ return
+ }
+ rec, err := waitReady(key)
+ if err != nil {
+ fmt.Fprintf(os.Stderr, "omnirush sandbox: %v\n", err)
+ os.Exit(125)
+ }
+ if rec == nil {
+ native(args)
+ return
+ }
+ cwd, _ := os.Getwd()
+ if cyg, handled := cygpath(rec, command, rest); handled {
+ fmt.Println(cyg)
+ return
+ }
+ argv := []string{rec.shell()}
+ if login {
+ argv = append(argv, "-l")
+ }
+ argv = append(argv, "-c", command)
+ argv = append(argv, rest...)
+ req := proto.Request{Op: "exec", Token: rec.Token, Argv: argv, Cwd: mapPath(cwd, rec), Env: forwardEnv(os.Environ())}
+ start := time.Now()
+ code, timing, err := runRemote(rec, req)
+ if err != nil {
+ // boxd is not reachable (restarting, crashed): run it with the runtime's exec instead.
+ code = runtimeExec(rec, req)
+ timing.Fallback = true
+ }
+ timing.TotalMs = float64(time.Since(start).Microseconds()) / 1000
+ timing.Code = code
+ logTiming(timing)
+ os.Exit(code)
+}
+
+func (r *Record) shell() string {
+ if r.Shell != "" {
+ return r.Shell
+ }
+ return "/bin/bash"
+}
+
+// parseShellArgs reads a shell invocation: [-l] -c <command> [arg0 args...]
+// (also -lc / -cl). ok is false for anything else (an interactive shell).
+func parseShellArgs(args []string) (command string, rest []string, login bool, ok bool) {
+ for i := 0; i < len(args); i++ {
+ a := args[i]
+ switch {
+ case a == "-l" || a == "--login":
+ login = true
+ case a == "-c" || a == "-lc" || a == "-cl":
+ if a != "-c" {
+ login = true
+ }
+ if i+1 >= len(args) {
+ return "", nil, login, false
+ }
+ return args[i+1], args[i+2:], login, true
+ case strings.HasPrefix(a, "-") && len(a) > 1 && !strings.HasPrefix(a, "--"):
+ // combined short flags like -ec: keep the shell's own behaviour natively
+ if strings.Contains(a, "c") {
+ return "", nil, login, false
+ }
+ default:
+ return "", nil, login, false
+ }
+ }
+ return "", nil, login, false
+}
+
+func boxHome() string {
+ if v := os.Getenv("OMNIRUSH_BOX_HOME"); v != "" {
+ return v
+ }
+ home, _ := os.UserHomeDir()
+ return filepath.Join(home, ".omnirush", "box")
+}
+
+func readRecord(key string) (*Record, error) {
+ for _, c := range key {
+ if !(c >= 'a' && c <= 'z' || c >= '0' && c <= '9' || c == '-') {
+ return nil, errors.New("bad box key")
+ }
+ }
+ data, err := os.ReadFile(filepath.Join(boxHome(), "boxes", key+".json"))
+ if err != nil {
+ return nil, err
+ }
+ var rec Record
+ if err := json.Unmarshal(data, &rec); err != nil {
+ return nil, err
+ }
+ return &rec, nil
+}
+
+// waitReady returns the ready record, nil for "run natively" (off), or an
+// error the agent sees (failed, or never ready in time).
+func waitReady(key string) (*Record, error) {
+ limit := 180 * time.Second
+ if v, err := strconv.Atoi(os.Getenv("OMNIRUSH_BOX_WAIT_MS")); err == nil && v >= 0 {
+ limit = time.Duration(v) * time.Millisecond
+ }
+ start := time.Now()
+ said := false
+ for {
+ rec, err := readRecord(key)
+ if err == nil {
+ switch rec.State {
+ case "ready":
+ return rec, nil
+ case "off":
+ return nil, nil
+ case "failed":
+ msg := rec.Error
+ if msg == "" {
+ msg = "it could not start"
+ }
+ return nil, fmt.Errorf("the sandbox is not available (%s); run `omnirush sandbox status`", msg)
+ }
+ }
+ if time.Since(start) > limit {
+ if err != nil {
+ return nil, fmt.Errorf("no sandbox record for this project (%v)", err)
+ }
+ return nil, errors.New("the sandbox did not start in time; run `omnirush sandbox status`")
+ }
+ if !said && time.Since(start) > 1500*time.Millisecond {
+ fmt.Fprintln(os.Stderr, "omnirush: waiting for the sandbox to start...")
+ said = true
+ }
+ time.Sleep(100 * time.Millisecond)
+ }
+}
+
+// mapPath maps a host path to the box: the project folder to its place
+// inside; on Windows anything else to the project folder.
+func mapPath(p string, rec *Record) string {
+ if p == "" {
+ return rec.CRoot
+ }
+ root, croot := rec.Root, rec.CRoot
+ if runtime.GOOS == "windows" {
+ lp, lr := strings.ToLower(filepath.Clean(p)), strings.ToLower(filepath.Clean(root))
+ if lp == lr {
+ return croot
+ }
+ if strings.HasPrefix(lp, lr+`\`) {
+ rel := filepath.ToSlash(p[len(filepath.Clean(root))+1:])
+ return strings.TrimSuffix(croot, "/") + "/" + rel
+ }
+ return croot
+ }
+ if root == croot {
+ return p
+ }
+ if p == root {
+ return croot
+ }
+ if strings.HasPrefix(p, strings.TrimSuffix(root, "/")+"/") {
+ return strings.TrimSuffix(croot, "/") + p[len(strings.TrimSuffix(root, "/")):]
+ }
+ return p
+}
+
+// unmapPath maps a path inside the box back to the host (Windows cygpath).
+func unmapPath(p string, rec *Record) string {
+ croot := strings.TrimSuffix(rec.CRoot, "/")
+ if p == croot {
+ return rec.Root
+ }
+ if strings.HasPrefix(p, croot+"/") {
+ rel := p[len(croot)+1:]
+ if runtime.GOOS == "windows" {
+ rel = strings.ReplaceAll(rel, "/", `\`)
+ }
+ return filepath.Join(rec.Root, rel)
+ }
+ return p
+}
+
+// cygpath answers the engine's Windows path probe (`cygpath -w -- "$1"`) for
+// paths in the box, without a round trip.
+func cygpath(rec *Record, command string, rest []string) (string, bool) {
+ if runtime.GOOS != "windows" || !strings.HasPrefix(strings.TrimSpace(command), "cygpath -w") || len(rest) < 2 {
+ return "", false
+ }
+ return unmapPath(rest[1], rec), true
+}
+
+var passExact = map[string]bool{
+ "TERM": true, "COLORTERM": true, "NO_COLOR": true, "FORCE_COLOR": true, "CLICOLOR": true, "CLICOLOR_FORCE": true,
+ "TZ": true, "CI": true, "HTTP_PROXY": true, "HTTPS_PROXY": true, "NO_PROXY": true, "http_proxy": true,
+ "https_proxy": true, "no_proxy": true, "OMNIRUSH_TURN": true, "OMNIRUSH_CALL": true, "OMNIRUSH_SESSION": true,
+ "OMNIRUSH_LEDGER_OFF": true, "PAGER": true, "GIT_PAGER": true, "GIT_TERMINAL_PROMPT": true, "DEBIAN_FRONTEND": true,
+}
+
+// forwardEnv keeps only what describes the terminal and the turn: the host's
+// environment (tokens, keys, PATH, HOME) never enters the box.
+func forwardEnv(environ []string) map[string]string {
+ extra := map[string]bool{}
+ for _, name := range strings.Split(os.Getenv("OMNIRUSH_BOX_PASS_ENV"), ",") {
+ if name = strings.TrimSpace(name); name != "" {
+ extra[name] = true
+ }
+ }
+ out := map[string]string{}
+ for _, kv := range environ {
+ i := strings.IndexByte(kv, '=')
+ if i <= 0 {
+ continue
+ }
+ k, v := kv[:i], kv[i+1:]
+ if passExact[k] || extra[k] {
+ out[k] = v
+ }
+ }
+ return out
+}
+
+// Timing is one call's overhead record (OMNIRUSH_BOX_TIMING_LOG).
+type Timing struct {
+ T int64 `json:"t"`
+ ConnectMs float64 `json:"connect_ms"`
+ FirstMs float64 `json:"first_byte_ms,omitempty"`
+ DaemonMs float64 `json:"daemon_ms"`
+ WaitedMs float64 `json:"waited_ms,omitempty"`
+ TotalMs float64 `json:"total_ms"`
+ Code int `json:"code"`
+ Fallback bool `json:"fallback,omitempty"`
+}
+
+func logTiming(t Timing) {
+ file := os.Getenv("OMNIRUSH_BOX_TIMING_LOG")
+ if file == "" {
+ return
+ }
+ t.T = time.Now().UnixMilli()
+ line, _ := json.Marshal(t)
+ f, err := os.OpenFile(file, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o600)
+ if err != nil {
+ return
+ }
+ defer f.Close()
+ _, _ = f.Write(append(line, '\n'))
+}
+
+func runRemote(rec *Record, req proto.Request) (int, Timing, error) {
+ var timing Timing
+ host := rec.Host
+ if host == "" {
+ host = "127.0.0.1"
+ }
+ start := time.Now()
+ raw, err := net.DialTimeout("tcp", net.JoinHostPort(host, strconv.Itoa(rec.Port)), 3*time.Second)
+ if err != nil {
+ return 0, timing, err
+ }
+ defer raw.Close()
+ if tcp, ok := raw.(*net.TCPConn); ok {
+ _ = tcp.SetNoDelay(true)
+ }
+ timing.ConnectMs = float64(time.Since(start).Microseconds()) / 1000
+ var wmu sync.Mutex
+ send := func(kind byte, payload []byte) {
+ wmu.Lock()
+ defer wmu.Unlock()
+ _ = proto.WriteFrame(raw, kind, payload)
+ }
+ wmu.Lock()
+ err = proto.WriteRequest(raw, req)
+ wmu.Unlock()
+ if err != nil {
+ return 0, timing, err
+ }
+
+ // Signals go to the command's process group in the box.
+ sigs := make(chan os.Signal, 4)
+ notifySignals(sigs)
+ go func() {
+ for s := range sigs {
+ send(proto.Signal, []byte(signalName(s)))
+ }
+ }()
+ // stdin: forwarded until EOF (the engine gives /dev/null: EOF at once).
+ go func() {
+ buf := make([]byte, 32<<10)
+ for {
+ n, err := os.Stdin.Read(buf)
+ if n > 0 {
+ send(proto.Stdin, buf[:n])
+ }
+ if err != nil {
+ send(proto.StdinEOF, nil)
+ return
+ }
+ }
+ }()
+
+ r := bufio.NewReaderSize(raw, 64<<10)
+ out := bufio.NewWriterSize(os.Stdout, 32<<10)
+ defer out.Flush()
+ buf := make([]byte, 0, 64<<10)
+ got := false
+ for {
+ kind, payload, err := proto.ReadFrame(r, buf)
+ if err != nil {
+ if !got {
+ return 0, timing, err
+ }
+ out.Flush()
+ fmt.Fprintln(os.Stderr, "omnirush sandbox: the connection to the sandbox was lost")
+ return 125, timing, nil
+ }
+ if !got {
+ got = true
+ timing.FirstMs = float64(time.Since(start).Microseconds()) / 1000
+ }
+ switch kind {
+ case proto.Stdout:
+ _, _ = out.Write(payload)
+ if r.Buffered() == 0 {
+ out.Flush()
+ }
+ case proto.Stderr:
+ out.Flush()
+ _, _ = os.Stderr.Write(payload)
+ case proto.Fail:
+ out.Flush()
+ fmt.Fprintf(os.Stderr, "omnirush sandbox: %s\n", payload)
+ case proto.Exit:
+ var info proto.ExitInfo
+ _ = json.Unmarshal(payload, &info)
+ timing.DaemonMs = info.Ms
+ timing.WaitedMs = info.WaitedMs
+ return info.Code, timing, nil
+ }
+ }
+}
+
+// runtimeExec runs the command with `docker|podman exec` (no boxd).
+func runtimeExec(rec *Record, req proto.Request) int {
+ bin := rec.Runtime
+ if bin == "" {
+ bin = "docker"
+ }
+ args := []string{"exec", "-i", "-w", req.Cwd}
+ if rec.UID != 0 {
+ args = append(args, "-u", fmt.Sprintf("%d:%d", rec.UID, rec.GID))
+ }
+ home := rec.Home
+ if home == "" {
+ home = "/root"
+ }
+ args = append(args, "-e", "HOME="+home)
+ for k, v := range req.Env {
+ args = append(args, "-e", k+"="+v)
+ }
+ args = append(args, rec.Container)
+ argv := append([]string(nil), req.Argv...)
+ if rec.PathPre != "" {
+ // keep the package-manager wrappers in front, as boxd does
+ for i := 0; i+1 < len(argv); i++ {
+ if argv[i] == "-c" {
+ argv[i+1] = "export PATH=" + rec.PathPre + ":\"$PATH\"; " + argv[i+1]
+ break
+ }
+ }
+ }
+ args = append(args, argv...)
+ cmd := exec.Command(bin, args...)
+ cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
+ if err := cmd.Run(); err != nil {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ return ee.ExitCode()
+ }
+ fmt.Fprintf(os.Stderr, "omnirush sandbox: the sandbox is not reachable: %v\n", err)
+ return 125
+ }
+ return 0
+}
+
+// native runs the real shell with the same arguments.
+func native(args []string) {
+ shell := realShell()
+ if runtime.GOOS != "windows" {
+ err := syscall.Exec(shell, append([]string{shell}, args...), os.Environ())
+ fmt.Fprintf(os.Stderr, "omnirush: could not run %s: %v\n", shell, err)
+ os.Exit(127)
+ }
+ cmd := exec.Command(shell, args...)
+ cmd.Stdin, cmd.Stdout, cmd.Stderr = os.Stdin, os.Stdout, os.Stderr
+ if err := cmd.Run(); err != nil {
+ var ee *exec.ExitError
+ if errors.As(err, &ee) {
+ os.Exit(ee.ExitCode())
+ }
+ fmt.Fprintf(os.Stderr, "omnirush: could not run %s: %v\n", shell, err)
+ os.Exit(127)
+ }
+ os.Exit(0)
+}
+
+func realShell() string {
+ if v := os.Getenv("OMNIRUSH_BOX_REAL_SHELL"); v != "" {
+ return v
+ }
+ self, _ := os.Executable()
+ selfDir := filepath.Dir(self)
+ names := []string{"bash", "sh"}
+ if runtime.GOOS == "windows" {
+ names = []string{"bash.exe", "pwsh.exe", "powershell.exe", "cmd.exe"}
+ }
+ for _, name := range names {
+ for _, dir := range filepath.SplitList(os.Getenv("PATH")) {
+ if dir == "" || filepath.Clean(dir) == filepath.Clean(selfDir) {
+ continue
+ }
+ cand := filepath.Join(dir, name)
+ if st, err := os.Stat(cand); err == nil && !st.IsDir() {
+ return cand
+ }
+ }
+ }
+ if runtime.GOOS == "windows" {
+ return "cmd.exe"
+ }
+ return "/bin/sh"
+}
+
diff --git a/apps/desktop/box/go/cmd/boxsh/main_test.go b/apps/desktop/box/go/cmd/boxsh/main_test.go
new file mode 100644
index 00000000..7bb02c3d
--- /dev/null
+++ b/apps/desktop/box/go/cmd/boxsh/main_test.go
@@ -0,0 +1,59 @@
+package main
+
+import (
+ "reflect"
+ "runtime"
+ "testing"
+)
+
+func TestParseShellArgs(t *testing.T) {
+ cases := []struct {
+ in []string
+ cmd string
+ rest []string
+ login bool
+ ok bool
+ }{
+ {[]string{"-c", "ls -la"}, "ls -la", []string{}, false, true},
+ {[]string{"-lc", "cygpath -w -- \"$1\"", "_", "/x"}, "cygpath -w -- \"$1\"", []string{"_", "/x"}, true, true},
+ {[]string{"-l", "-c", "echo hi"}, "echo hi", []string{}, true, true},
+ {[]string{}, "", nil, false, false},
+ {[]string{"script.sh"}, "", nil, false, false},
+ {[]string{"-c"}, "", nil, false, false},
+ {[]string{"-ec", "x"}, "", nil, false, false},
+ }
+ for _, c := range cases {
+ cmd, rest, login, ok := parseShellArgs(c.in)
+ if ok != c.ok || cmd != c.cmd || login != c.login || (c.ok && !reflect.DeepEqual(rest, c.rest)) {
+ t.Errorf("%v: got %q %v %v %v", c.in, cmd, rest, login, ok)
+ }
+ }
+}
+
+func TestMapPathSame(t *testing.T) {
+ if runtime.GOOS == "windows" {
+ t.Skip()
+ }
+ rec := &Record{Root: "/home/u/proj", CRoot: "/home/u/proj"}
+ if got := mapPath("/home/u/proj/src", rec); got != "/home/u/proj/src" {
+ t.Fatal(got)
+ }
+ rec = &Record{Root: "/home/u/proj", CRoot: "/app"}
+ for in, want := range map[string]string{"/home/u/proj": "/app", "/home/u/proj/a/b": "/app/a/b", "/home/u/projx": "/home/u/projx", "/tmp": "/tmp", "": "/app"} {
+ if got := mapPath(in, rec); got != want {
+ t.Errorf("%q -> %q want %q", in, got, want)
+ }
+ }
+ if got := unmapPath("/app/a/b", rec); got != "/home/u/proj/a/b" {
+ t.Fatal(got)
+ }
+}
+
+func TestForwardEnv(t *testing.T) {
+ t.Setenv("OMNIRUSH_BOX_PASS_ENV", "MY_FLAG")
+ got := forwardEnv([]string{"TERM=xterm", "OMNIRUSH_ACCESS_TOKEN=secret", "OPENAI_API_KEY=k", "PATH=/x", "HOME=/h", "OMNIRUSH_TURN=3", "MY_FLAG=1", "AWS_SECRET_ACCESS_KEY=s"})
+ want := map[string]string{"TERM": "xterm", "OMNIRUSH_TURN": "3", "MY_FLAG": "1"}
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("%v", got)
+ }
+}
diff --git a/apps/desktop/box/go/cmd/boxsh/signals_unix.go b/apps/desktop/box/go/cmd/boxsh/signals_unix.go
new file mode 100644
index 00000000..3432421b
--- /dev/null
+++ b/apps/desktop/box/go/cmd/boxsh/signals_unix.go
@@ -0,0 +1,26 @@
+//go:build !windows
+
+package main
+
+import (
+ "os"
+ "os/signal"
+ "syscall"
+)
+
+func notifySignals(c chan os.Signal) {
+ signal.Notify(c, syscall.SIGTERM, syscall.SIGINT, syscall.SIGHUP, syscall.SIGQUIT)
+}
+
+func signalName(s os.Signal) string {
+ switch s {
+ case syscall.SIGINT:
+ return "INT"
+ case syscall.SIGHUP:
+ return "HUP"
+ case syscall.SIGQUIT:
+ return "QUIT"
+ default:
+ return "TERM"
+ }
+}
diff --git a/apps/desktop/box/go/cmd/boxsh/signals_windows.go b/apps/desktop/box/go/cmd/boxsh/signals_windows.go
new file mode 100644
index 00000000..b1969300
--- /dev/null
+++ b/apps/desktop/box/go/cmd/boxsh/signals_windows.go
@@ -0,0 +1,14 @@
+//go:build windows
+
+package main
+
+import (
+ "os"
+ "os/signal"
+)
+
+func notifySignals(c chan os.Signal) {
+ signal.Notify(c, os.Interrupt)
+}
+
+func signalName(os.Signal) string { return "TERM" }
diff --git a/apps/desktop/box/go/go.mod b/apps/desktop/box/go/go.mod
new file mode 100644
index 00000000..6868900a
--- /dev/null
+++ b/apps/desktop/box/go/go.mod
@@ -0,0 +1,3 @@
+module omnirush.ai/box
+
+go 1.22
diff --git a/apps/desktop/box/go/proto/proto.go b/apps/desktop/box/go/proto/proto.go
new file mode 100644
index 00000000..69e277c0
--- /dev/null
+++ b/apps/desktop/box/go/proto/proto.go
@@ -0,0 +1,165 @@
+// Package proto is the wire format between the host shell client (boxsh)
+// and the in-container daemon (boxd).
+//
+// A connection starts with one JSON line from the client (Request). After
+// it, both sides send frames: one type byte, a 4-byte big-endian length,
+// then the payload. The daemon ends every operation with an Exit frame.
+package proto
+
+import (
+ "bufio"
+ "crypto/subtle"
+ "encoding/binary"
+ "encoding/json"
+ "errors"
+ "fmt"
+ "io"
+)
+
+// Version is bumped when the wire format changes incompatibly.
+const Version = 1
+
+// Frame types.
+const (
+ Stdout byte = 'o' // daemon -> client: command stdout
+ Stderr byte = 'e' // daemon -> client: command stderr
+ Exit byte = 'x' // daemon -> client: ExitInfo JSON; last frame
+ Data byte = 'd' // daemon -> client: op payload (tar bytes, JSON)
+ Fail byte = 'E' // daemon -> client: error text; an Exit frame follows
+ Signal byte = 's' // client -> daemon: "TERM", "KILL", "INT", "HUP"
+ Stdin byte = 'i' // client -> daemon: stdin bytes
+ StdinEOF byte = 'c' // client -> daemon: stdin closed
+)
+
+// MaxFrame bounds one frame's payload.
+const MaxFrame = 1 << 20
+
+// Request is the first line of a connection.
+type Request struct {
+ V int `json:"v"`
+ Token string `json:"token"`
+ Op string `json:"op"` // exec | stat | tar | ping
+ Argv []string `json:"argv,omitempty"`
+ Cwd string `json:"cwd,omitempty"`
+ Env map[string]string `json:"env,omitempty"`
+ Paths []string `json:"paths,omitempty"`
+ // Wait: for exec, how long (ms) to wait for a running snapshot to end.
+ Wait int `json:"wait,omitempty"`
+ // Root: exec as root instead of the box's command user (the launcher's
+ // own setup steps; the shell client never sets it).
+ Root bool `json:"root,omitempty"`
+}
+
+// ExitInfo ends an operation.
+type ExitInfo struct {
+ Code int `json:"code"`
+ Signal string `json:"signal,omitempty"`
+ // Ms is the daemon-side wall time of the operation.
+ Ms float64 `json:"ms"`
+ // WaitedMs is the time an exec waited for a snapshot to finish.
+ WaitedMs float64 `json:"waited_ms,omitempty"`
+}
+
+// StatEntry describes one path for the snapshot diff.
+type StatEntry struct {
+ Path string `json:"path"`
+ Type string `json:"type"` // file | dir | symlink | other | missing
+ Mode uint32 `json:"mode,omitempty"`
+ Size int64 `json:"size,omitempty"`
+ MtimeNs int64 `json:"mtime_ns,omitempty"`
+ CtimeNs int64 `json:"ctime_ns,omitempty"`
+ Ino uint64 `json:"ino,omitempty"`
+ Nlink uint64 `json:"nlink,omitempty"`
+ UID uint32 `json:"uid"`
+ GID uint32 `json:"gid"`
+ Link string `json:"link,omitempty"`
+}
+
+// WriteFrame writes one frame.
+func WriteFrame(w io.Writer, kind byte, payload []byte) error {
+ for len(payload) > MaxFrame {
+ if err := WriteFrame(w, kind, payload[:MaxFrame]); err != nil {
+ return err
+ }
+ payload = payload[MaxFrame:]
+ }
+ var head [5]byte
+ head[0] = kind
+ binary.BigEndian.PutUint32(head[1:], uint32(len(payload)))
+ if _, err := w.Write(head[:]); err != nil {
+ return err
+ }
+ if len(payload) == 0 {
+ return nil
+ }
+ _, err := w.Write(payload)
+ return err
+}
+
+// ReadFrame reads one frame. buf is reused when large enough.
+func ReadFrame(r io.Reader, buf []byte) (byte, []byte, error) {
+ var head [5]byte
+ if _, err := io.ReadFull(r, head[:]); err != nil {
+ return 0, nil, err
+ }
+ n := binary.BigEndian.Uint32(head[1:])
+ if n > MaxFrame {
+ return 0, nil, fmt.Errorf("frame too large: %d", n)
+ }
+ if cap(buf) < int(n) {
+ buf = make([]byte, n)
+ }
+ buf = buf[:n]
+ if _, err := io.ReadFull(r, buf); err != nil {
+ return 0, nil, err
+ }
+ return head[0], buf, nil
+}
+
+// WriteRequest sends the first line.
+func WriteRequest(w io.Writer, req Request) error {
+ req.V = Version
+ line, err := json.Marshal(req)
+ if err != nil {
+ return err
+ }
+ line = append(line, '\n')
+ _, err = w.Write(line)
+ return err
+}
+
+// ReadRequest reads the first line (bounded) and checks the token.
+func ReadRequest(r *bufio.Reader, token string) (Request, error) {
+ var req Request
+ line, err := readLine(r, 4<<20)
+ if err != nil {
+ return req, err
+ }
+ if err := json.Unmarshal(line, &req); err != nil {
+ return req, fmt.Errorf("bad request: %w", err)
+ }
+ if req.V != Version {
+ return req, fmt.Errorf("protocol version %d, want %d", req.V, Version)
+ }
+ if token == "" || subtle.ConstantTimeCompare([]byte(req.Token), []byte(token)) != 1 {
+ return req, errors.New("unauthorized")
+ }
+ return req, nil
+}
+
+func readLine(r *bufio.Reader, max int) ([]byte, error) {
+ var out []byte
+ for {
+ chunk, isPrefix, err := r.ReadLine()
+ if err != nil {
+ return nil, err
+ }
+ out = append(out, chunk...)
+ if len(out) > max {
+ return nil, errors.New("request line too long")
+ }
+ if !isPrefix {
+ return out, nil
+ }
+ }
+}
diff --git a/apps/desktop/box/go/proto/proto_test.go b/apps/desktop/box/go/proto/proto_test.go
new file mode 100644
index 00000000..f9be5b1b
--- /dev/null
+++ b/apps/desktop/box/go/proto/proto_test.go
@@ -0,0 +1,46 @@
+package proto
+
+import (
+ "bufio"
+ "bytes"
+ "strings"
+ "testing"
+)
+
+func TestFrames(t *testing.T) {
+ var b bytes.Buffer
+ big := bytes.Repeat([]byte("x"), MaxFrame+10)
+ if err := WriteFrame(&b, Stdout, []byte("hi")); err != nil {
+ t.Fatal(err)
+ }
+ if err := WriteFrame(&b, Data, big); err != nil {
+ t.Fatal(err)
+ }
+ k, p, err := ReadFrame(&b, nil)
+ if err != nil || k != Stdout || string(p) != "hi" {
+ t.Fatal(k, p, err)
+ }
+ total := 0
+ for total < len(big) {
+ k, p, err = ReadFrame(&b, nil)
+ if err != nil || k != Data {
+ t.Fatal(err)
+ }
+ total += len(p)
+ }
+}
+
+func TestRequestAuth(t *testing.T) {
+ var b bytes.Buffer
+ _ = WriteRequest(&b, Request{Op: "ping", Token: "t1"})
+ if _, err := ReadRequest(bufio.NewReader(bytes.NewReader(b.Bytes())), "t2"); err == nil || !strings.Contains(err.Error(), "unauthorized") {
+ t.Fatal("wrong token accepted")
+ }
+ req, err := ReadRequest(bufio.NewReader(bytes.NewReader(b.Bytes())), "t1")
+ if err != nil || req.Op != "ping" {
+ t.Fatal(err)
+ }
+ if _, err := ReadRequest(bufio.NewReader(strings.NewReader("{}\n")), ""); err == nil {
+ t.Fatal("empty token accepted")
+ }
+}
diff --git a/apps/desktop/electron-builder.base.yml b/apps/desktop/electron-builder.base.yml
index d29f0ba8..6a891d71 100644
--- a/apps/desktop/electron-builder.base.yml
+++ b/apps/desktop/electron-builder.base.yml
@@ -65,6 +65,8 @@ mac:
- versions.json
- versions.json-aarch64-apple-darwin
- versions.json-x86_64-apple-darwin
+ - box/darwin-*/boxsh
+ - box/linux-*/boxd
- from: resources/helpers
to: helpers
filter:
@@ -88,6 +90,8 @@ linux:
- versions.json
- versions.json-aarch64-unknown-linux-gnu
- versions.json-x86_64-unknown-linux-gnu
+ - box/linux-*/boxsh
+ - box/linux-*/boxd
target:
- AppImage
- deb
@@ -126,6 +130,8 @@ win:
- versions.json
- versions.json-aarch64-pc-windows-msvc.exe
- versions.json-x86_64-pc-windows-msvc.exe
+ - box/windows-*/boxsh.exe
+ - box/linux-*/boxd
target:
- nsis
nsis:
diff --git a/apps/desktop/scripts/prepare-box-helpers.mjs b/apps/desktop/scripts/prepare-box-helpers.mjs
new file mode 100644
index 00000000..779dcebc
--- /dev/null
+++ b/apps/desktop/scripts/prepare-box-helpers.mjs
@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+// The Linux sandbox's helpers (apps/server/src/box), next to the engine in
+// the sidecars folder: box/<goos>-<goarch>/boxsh[.exe] (the shell the engine
+// runs its shell tool with) and box/linux-<arch>/boxd (copied into each
+// project's container). Built from box/go, a copy of the CLI's box/go
+// (omnirush-cli feat/local-box), with Go >= 1.22 (GO=/path/to/go), or copied
+// from OMNIRUSH_BOX_PREBUILT_DIR (a folder with the same layout). Without
+// either the app ships without them and the sandbox reports itself
+// unavailable; nothing else changes.
+import { execFileSync, spawnSync } from "node:child_process";
+import { chmodSync, copyFileSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const source = resolve(here, "..", "box", "go");
+// The same folder prepare-sidecar.mjs fills (OMNIRUSH_SIDECAR_DIR or --outdir).
+const argv = process.argv.slice(2);
+const outdirArg = argv.find((arg) => arg.startsWith("--outdir="))?.split("=")[1] ?? (argv.includes("--outdir") ? argv[argv.indexOf("--outdir") + 1] : null);
+const sidecarOverride = process.env.OMNIRUSH_SIDECAR_DIR?.trim() || outdirArg;
+const sidecarDir = sidecarOverride ? resolve(sidecarOverride) : resolve(here, "..", "resources", "sidecars");
+const out = join(sidecarDir, "box");
+
+const GOOS = { darwin: "darwin", linux: "linux", win32: "windows" };
+const GOARCH = { x64: "amd64", arm64: "arm64" };
+
+/** The target from the same triple prepare-sidecar.mjs reads, else this machine. */
+function target() {
+ const triple = process.env.TAURI_ENV_TARGET_TRIPLE ?? process.env.CARGO_CFG_TARGET_TRIPLE ?? process.env.TARGET ?? "";
+ const goos = triple.includes("darwin") ? "darwin" : triple.includes("windows") ? "windows" : triple.includes("linux") ? "linux" : GOOS[process.platform];
+ const goarch = triple.startsWith("aarch64") ? "arm64" : triple.startsWith("x86_64") ? "amd64" : GOARCH[process.arch];
+ return { goos, goarch };
+}
+
+const { goos, goarch } = target();
+const files = [
+ { cmd: "boxsh", goos, goarch, name: goos === "windows" ? "boxsh.exe" : "boxsh" },
+ { cmd: "boxd", goos: "linux", goarch, name: "boxd" },
+];
+
+const go = process.env.GO?.trim() || "go";
+const haveGo = spawnSync(go, ["version"], { stdio: "ignore" }).status === 0;
+const prebuilt = process.env.OMNIRUSH_BOX_PREBUILT_DIR?.trim() ? resolve(process.env.OMNIRUSH_BOX_PREBUILT_DIR.trim()) : null;
+const version = process.env.OMNIRUSH_BOX_HELPER_VERSION?.trim() || "desktop";
+
+let missing = 0;
+for (const file of files) {
+ const dir = join(out, `${file.goos}-${file.goarch}`);
+ const dest = join(dir, file.name);
+ mkdirSync(dir, { recursive: true });
+ if (haveGo) {
+ execFileSync(go, ["build", "-trimpath", "-buildvcs=false", "-ldflags", `-s -w -X main.version=${version}`, "-o", dest, `./cmd/${file.cmd}`], {
+ cwd: source,
+ stdio: "inherit",
+ env: { ...process.env, GOOS: file.goos, GOARCH: file.goarch, CGO_ENABLED: "0", GOFLAGS: "-mod=mod" },
+ });
+ } else if (prebuilt && existsSync(join(prebuilt, `${file.goos}-${file.goarch}`, file.name))) {
+ copyFileSync(join(prebuilt, `${file.goos}-${file.goarch}`, file.name), dest);
+ } else {
+ missing += 1;
+ continue;
+ }
+ chmodSync(dest, 0o755);
+ // A runnable local build on macOS (release builds are signed with the app).
+ if (process.platform === "darwin" && file.goos === "darwin") spawnSync("codesign", ["--force", "--sign", "-", dest], { stdio: "ignore" });
+ console.log(`Sandbox helper ${file.goos}-${file.goarch}/${file.name} ready.`);
+}
+if (missing) console.warn("Sandbox helpers missing (no Go and no OMNIRUSH_BOX_PREBUILT_DIR): the Linux sandbox will report itself unavailable.");
diff --git a/apps/desktop/scripts/prepare-sidecar.mjs b/apps/desktop/scripts/prepare-sidecar.mjs
index 98937466..ff2cfbb3 100644
--- a/apps/desktop/scripts/prepare-sidecar.mjs
+++ b/apps/desktop/scripts/prepare-sidecar.mjs
@@ -417,3 +417,10 @@ try {
console.error(`Failed to write versions.json: ${error}`);
process.exit(1);
}
+
+// The Linux sandbox's helpers (boxsh, boxd) beside the engine: optional, never fatal.
+try {
+ await import("./prepare-box-helpers.mjs");
+} catch (error) {
+ console.warn(`Sandbox helpers not prepared: ${error instanceof Error ? error.message : String(error)}`);
+}
diff --git a/apps/server/package.json b/apps/server/package.json
index ae04a0de..ac4272d1 100644
--- a/apps/server/package.json
+++ b/apps/server/package.json
@@ -12,7 +12,7 @@
"test:coverage": "bun --conditions=development test --coverage --coverage-reporter=text --coverage-reporter=lcov --coverage-dir=coverage",
"test:artifacts": "bun --conditions=development test src/artifact-files.e2e.test.ts src/workspace-init.test.ts src/server.normalizeWorkspaceRelativePath.test.ts",
"build:enterprise-mcp-client": "pnpm --filter @omnirush/enterprise-mcp-client build",
- "build": "pnpm --filter @omnirush/types build && pnpm build:enterprise-mcp-client && tsc -p tsconfig.json && bun build src/opencode-plugins/managed-policy-next.ts src/opencode-plugins/managed-policy.ts src/opencode-plugins/omnirush-chrome-devtools.ts src/opencode-plugins/omnirush-extensions-preview.ts src/opencode-plugins/omnirush-capabilities-knowledge.ts src/opencode-plugins/omnirush-office-attachments.ts src/opencode-plugins/omnirush-spreadsheets.ts src/opencode-plugins/omnirush-pdf-attachments.ts src/opencode-plugins/omnirush-anthropic-adaptive-thinking.ts src/opencode-plugins/omnirush-anthropic-tool-schema.ts src/opencode-plugins/omnirush-title-recovery.ts src/opencode-plugins/omnirush-reasoning-effort.ts src/opencode-plugins/omnirush-swarm.ts src/opencode-plugins/omnirush-budget-wrap.ts src/opencode-plugins/omnirush-mcp-policy.ts --root src/opencode-plugins --outdir dist/opencode-plugins --target node --format esm && node scripts/copy-pdfium-wasm.mjs dist/opencode-plugins",
+ "build": "pnpm --filter @omnirush/types build && pnpm build:enterprise-mcp-client && tsc -p tsconfig.json && bun build src/opencode-plugins/managed-policy-next.ts src/opencode-plugins/managed-policy.ts src/opencode-plugins/omnirush-chrome-devtools.ts src/opencode-plugins/omnirush-extensions-preview.ts src/opencode-plugins/omnirush-capabilities-knowledge.ts src/opencode-plugins/omnirush-office-attachments.ts src/opencode-plugins/omnirush-spreadsheets.ts src/opencode-plugins/omnirush-pdf-attachments.ts src/opencode-plugins/omnirush-anthropic-adaptive-thinking.ts src/opencode-plugins/omnirush-anthropic-tool-schema.ts src/opencode-plugins/omnirush-title-recovery.ts src/opencode-plugins/omnirush-reasoning-effort.ts src/opencode-plugins/omnirush-swarm.ts src/opencode-plugins/omnirush-budget-wrap.ts src/opencode-plugins/omnirush-mcp-policy.ts src/opencode-plugins/omnirush-box.ts --root src/opencode-plugins --outdir dist/opencode-plugins --target node --format esm && node scripts/copy-pdfium-wasm.mjs dist/opencode-plugins",
"build:bin": "pnpm --filter @omnirush/types build && pnpm build:enterprise-mcp-client && bun build --compile src/cli.ts --outfile dist/bin/omnirush-server",
"build:bin:all": "pnpm --filter @omnirush/types build && pnpm build:enterprise-mcp-client && bun ./script/build.ts --outdir dist/bin --target bun-darwin-arm64 --target bun-darwin-x64 --target bun-linux-x64 --target bun-linux-arm64 --target bun-windows-x64 --target bun-windows-arm64",
"prepare:npm": "pnpm build:bin && node scripts/publish-npm.mjs --prepare-only",
diff --git a/apps/server/src/box/box-server.test.ts b/apps/server/src/box/box-server.test.ts
new file mode 100644
index 00000000..fc1e586d
--- /dev/null
+++ b/apps/server/src/box/box-server.test.ts
@@ -0,0 +1,141 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { omnirushRuntimeConfigFilePath } from "../omnirush-runtime-config.js";
+import { readOmniRushWorkspaceConfig } from "../omnirush-workspace-config-store.js";
+import { policyRequestActions } from "../managed-policy-rules.js";
+import { FakeArchiveServer } from "../session-archive/fake-archive-server.js";
+import { SessionArchiver } from "../session-archive/index.js";
+import { openArchive } from "../session-archive/test-helpers.js";
+import { BUNDLED_HARNESS } from "../engine-identity.js";
+import { boxEnvironment, type UploadEnvironment } from "../session-uploader.js";
+import { startServer } from "../server.js";
+import type { ServerConfig } from "../types.js";
+import { boxSnapshotsDir, type BoxLabel } from "./box.js";
+
+const WORKSPACE_ID = "ws_box_test";
+const savedEnv = { ...process.env };
+const dirs: string[] = [];
+
+afterEach(async () => {
+ process.env = { ...savedEnv };
+ await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+async function temp(name: string): Promise<string> {
+ const dir = await mkdtemp(join(tmpdir(), `omnirush-box-server-${name}-`));
+ dirs.push(dir);
+ return dir;
+}
+
+function serverConfig(root: string): ServerConfig {
+ return {
+ host: "127.0.0.1",
+ port: 0,
+ token: "token",
+ hostToken: "host-token",
+ configPath: join(root, "server.json"),
+ approval: { mode: "auto", timeoutMs: 0 },
+ corsOrigins: [],
+ workspaces: [{ id: WORKSPACE_ID, name: "Box", path: join(root, "project"), preset: "starter", workspaceType: "local" }],
+ authorizedRoots: [root],
+ readOnly: false,
+ startedAt: Date.now(),
+ tokenSource: "generated",
+ hostTokenSource: "generated",
+ logFormat: "pretty",
+ logRequests: false,
+ } satisfies ServerConfig;
+}
+
+/** The helpers folder layout (sidecars/box): this machine's boxsh, both boxd (stand-ins). */
+async function helpers(root: string): Promise<string> {
+ const dir = join(root, "box-bin");
+ const goos = process.platform === "win32" ? "windows" : process.platform;
+ const goarch = process.arch === "arm64" ? "arm64" : "amd64";
+ await mkdir(join(dir, `${goos}-${goarch}`), { recursive: true });
+ await writeFile(join(dir, `${goos}-${goarch}`, process.platform === "win32" ? "boxsh.exe" : "boxsh"), "#!/bin/sh\n");
+ await mkdir(join(dir, `linux-${goarch}`), { recursive: true });
+ await writeFile(join(dir, `linux-${goarch}`, "boxd"), "");
+ return dir;
+}
+
+describe("Linux sandbox through the server", () => {
+ test.skipIf(process.platform === "win32")("turning the box on for a workspace gives the engine config the box shell and plugin; off takes them out", async () => {
+ const root = await temp("root");
+ await mkdir(join(root, "project"), { recursive: true });
+ process.env.OMNIRUSH_RUNTIME_DB = join(root, "runtime.sqlite");
+ process.env.OPENCODE_CONFIG_DIR = join(root, "global-opencode");
+ process.env.OMNIRUSH_BOX_HOME = join(root, "box-home");
+ process.env.OMNIRUSH_BOX_BIN_DIR = await helpers(root);
+ // No container runtime here: the box is unavailable, which the status says; nothing fails.
+ process.env.OMNIRUSH_BOX_RUNTIME = join(root, "no-docker");
+ await mkdir(process.env.OPENCODE_CONFIG_DIR, { recursive: true });
+ const config = serverConfig(root);
+ const server = await startServer(config) as { port: number; stop: (close?: boolean) => Promise<void> | void };
+ const base = `http://127.0.0.1:${server.port}`;
+ const headers = { authorization: `Bearer ${config.token}`, "content-type": "application/json" };
+ const engineConfig = async () => JSON.parse(await readFile(omnirushRuntimeConfigFilePath(config), "utf8")) as { shell?: string; plugin?: string[] };
+ try {
+ expect((await fetch(`${base}/workspace/${WORKSPACE_ID}/box`)).status).toBe(401);
+ const before = await (await fetch(`${base}/workspace/${WORKSPACE_ID}/box`, { headers })).json();
+ expect(before).toMatchObject({ mode: null, on: false, serverDefault: "off", state: "off" });
+ for (const payload of [{ mode: "yes" }, {}, { mode: "on", extra: 1 }]) {
+ expect((await fetch(`${base}/workspace/${WORKSPACE_ID}/box`, { method: "PUT", headers, body: JSON.stringify(payload) })).status).toBe(400);
+ }
+ expect(policyRequestActions("PUT", `/workspace/${WORKSPACE_ID}/box`)).toEqual(["settings"]);
+
+ const on = await fetch(`${base}/workspace/${WORKSPACE_ID}/box`, { method: "PUT", headers, body: JSON.stringify({ mode: "on" }) });
+ expect(on.status).toBe(200);
+ const status = await on.json();
+ expect(status).toMatchObject({ mode: "on", on: true, source: "project", state: "unavailable", engine: { status: "unmanaged" } });
+ expect(status.runtime.ok).toBe(false);
+ expect(await readOmniRushWorkspaceConfig(config, WORKSPACE_ID)).toMatchObject({ localBox: { mode: "on", offered: true } });
+ const withBox = await engineConfig();
+ expect(withBox.shell).toBe(join(root, "box-home", "shell-desktop", "bash"));
+ expect(withBox.plugin?.filter((entry) => /omnirush-box\.(?:ts|js)$/.test(entry))).toHaveLength(1);
+
+ const off = await fetch(`${base}/workspace/${WORKSPACE_ID}/box`, { method: "PUT", headers, body: JSON.stringify({ mode: "off" }) });
+ expect(await off.json()).toMatchObject({ mode: "off", on: false, state: "off" });
+ const without = await engineConfig();
+ expect(without.shell).toBeUndefined();
+ expect(without.plugin?.some((entry) => /omnirush-box\.(?:ts|js)$/.test(entry))).toBe(false);
+ expect((await fetch(`${base}/workspace/${WORKSPACE_ID}/box/reset`, { method: "POST", headers, body: "{}" })).status).toBe(200);
+ } finally {
+ await server.stop(true);
+ }
+ });
+
+ test("capture: a chat's box checkpoints ride in its project archive, and its environment says linux", async () => {
+ const stateDir = await temp("state");
+ const project = await temp("project");
+ await writeFile(join(project, "app.py"), "print(1)\n");
+ // A git project: archived by the default policy.
+ for (const args of [["init", "-q", "-b", "main"], ["add", "app.py"], ["commit", "-q", "-m", "initial"]]) {
+ execFileSync("git", ["-C", project, "-c", "user.name=t", "-c", "[email protected]", "-c", "commit.gpgsign=false", ...args]);
+ }
+ const sessionId = "ses_box_capture_1";
+ const folder = join(boxSnapshotsDir(stateDir), sessionId);
+ await mkdir(folder, { recursive: true });
+ await writeFile(join(folder, "record.json"), JSON.stringify({ kind: "omnirush-box" }));
+ await writeFile(join(folder, "turn-1.json"), JSON.stringify({ label: "turn-1" }));
+ await writeFile(join(folder, "turn-1.tar"), Buffer.alloc(1024));
+ // Left out: not a checkpoint name.
+ await writeFile(join(folder, ".chain.json"), "{}");
+ const server = new FakeArchiveServer();
+ const archiver = new SessionArchiver({ gatewayUrl: server.gatewayUrl, accessToken: server.token, fetch: server.respond, stateDir, retry: { baseMs: 1, maxMs: 2, attempts: 2 }, sandboxSnapshotsDir: boxSnapshotsDir(stateDir) });
+ expect(await archiver.captureBase(sessionId, project)).toMatchObject({ status: "queued", kind: "base" });
+ await archiver.drain();
+ const names = (await openArchive(server.objects()[0]!.object!)).map((member) => member.name);
+ 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 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
new file mode 100644
index 00000000..9756296c
--- /dev/null
+++ b/apps/server/src/box/box.test.ts
@@ -0,0 +1,261 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { boxKey, containerName, containerRoot, createArgs, credentialPath, filterChanges, helperPath, installShell, parseDiff, parseSize, setToolsRoot, singleFileTar } from "./box.js";
+import { readBoxSettings } from "./desktop.js";
+import { detectStack, imageFor } from "./images.js";
+import { engineConfig, mapToBox, rememberServerDefault, resolveMode, serverDefault } from "./launch.js";
+import { DESKTOP_PROJECTS_FILE } from "./plugin-lib.js";
+import { candidates, detectRuntime, explainFailure, probe, type RunCommand } from "./runtime.js";
+import { BoxService, type BoxWorkspace } from "./service.js";
+import { OmniRushBox } from "../opencode-plugins/omnirush-box.js";
+
+const dirs: string[] = [];
+const savedEnv = { ...process.env };
+
+async function temp(name: string): Promise<string> {
+ const dir = await mkdtemp(join(tmpdir(), `omnirush-box-${name}-`));
+ dirs.push(dir);
+ return dir;
+}
+
+beforeEach(() => {
+ setToolsRoot(null);
+});
+
+afterEach(async () => {
+ process.env = { ...savedEnv };
+ setToolsRoot(null);
+ await Promise.all(dirs.splice(0).map((dir) => rm(dir, { recursive: true, force: true })));
+});
+
+const HOST_GOOS = process.platform === "win32" ? "windows" : process.platform;
+const HOST_GOARCH = process.arch === "arm64" ? "arm64" : "amd64";
+
+/** A helpers folder with this machine's boxsh and both boxd files (empty stand-ins). */
+async function helpers(): Promise<string> {
+ const dir = await temp("bin");
+ await mkdir(join(dir, `${HOST_GOOS}-${HOST_GOARCH}`), { recursive: true });
+ await writeFile(join(dir, `${HOST_GOOS}-${HOST_GOARCH}`, process.platform === "win32" ? "boxsh.exe" : "boxsh"), "#!/bin/sh\n");
+ for (const arch of ["amd64", "arm64"]) {
+ await mkdir(join(dir, `linux-${arch}`), { recursive: true });
+ await writeFile(join(dir, `linux-${arch}`, "boxd"), "");
+ }
+ return dir;
+}
+
+describe("box runtime", () => {
+ test("a Windows docker.exe seen from WSL is skipped with the reason, never used", () => {
+ const list = candidates({ platform: "linux", home: "/home/u", env: { PATH: "/usr/bin:/mnt/c/Program Files/Docker/Docker/resources/bin" }, wsl: true, exists: (file) => file.startsWith("/mnt/c/") && file.endsWith("/docker") });
+ expect(list).toHaveLength(1);
+ expect(list[0]!.skipped).toContain("WSL");
+ });
+
+ test("OMNIRUSH_BOX_RUNTIME as a path is the only candidate", () => {
+ expect(candidates({ platform: "linux", env: { OMNIRUSH_BOX_RUNTIME: "/opt/podman/bin/podman", PATH: "/usr/bin" }, exists: () => true })).toEqual([{ name: "podman", bin: "/opt/podman/bin/podman" }]);
+ });
+
+ test("failures read as one line for the user", () => {
+ expect(explainFailure("docker", { code: 1, stderr: "permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock" })).toContain("docker group");
+ expect(explainFailure("docker", { code: 1, stderr: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?" }, { platform: "darwin" })).toContain("start Docker Desktop");
+ expect(explainFailure("docker", { code: -1, stderr: "", error: "ENOENT" })).toBe("docker is not installed");
+ });
+
+ test("a docker probe reads `docker info`; a remote DOCKER_HOST is refused", async () => {
+ const run: RunCommand = async () => ({ code: 0, stdout: JSON.stringify({ OSType: "linux", ServerVersion: "27.1", Architecture: "x86_64", OperatingSystem: "Docker Desktop", SecurityOptions: [] }), stderr: "" });
+ expect(await probe({ name: "docker", bin: "/usr/bin/docker" }, { run, platform: "darwin", env: {} })).toMatchObject({ ok: true, flavor: "desktop", vm: true, version: "27.1" });
+ expect(await probe({ name: "docker", bin: "/usr/bin/docker" }, { run, env: { DOCKER_HOST: "ssh://elsewhere" } })).toMatchObject({ ok: false });
+ });
+
+ test("no runtime: one reason per platform, cached for the next ask", async () => {
+ const home = await temp("home");
+ 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)" });
+ expect(await detectRuntime({ boxHome: home, platform: "linux", env: { PATH: "" }, exists: () => false, run, now: 2_000 })).toMatchObject({ ok: false, cached: true });
+ expect(calls).toBe(0);
+ });
+});
+
+describe("box core", () => {
+ test("key, container name and the in-box project path", async () => {
+ const root = await temp("project");
+ expect(boxKey(root)).toMatch(/^[0-9a-f]{12}$/);
+ expect(containerName("abc123def456", {})).toBe("omnirush-box-abc123def456");
+ expect(containerName("abc123def456", { OMNIRUSH_BOX_CONTAINER_PREFIX: "guibox-" })).toBe("guibox-abc123def456");
+ expect(containerName("abc123def456", { OMNIRUSH_BOX_CONTAINER_PREFIX: "../bad" })).toBe("omnirush-box-abc123def456");
+ expect(containerRoot("C:\\Users\\Sam\\proj", "win32")).toBe("/c/Users/Sam/proj");
+ expect(containerRoot("/home/sam/proj", "linux")).toBe("/home/sam/proj");
+ expect(mapToBox("/a/proj/src", "/a/proj", "/c/proj")).toBe("/c/proj/src");
+ expect(mapToBox("/elsewhere", "/a/proj", "/c/proj")).toBe("/c/proj");
+ });
+
+ test("a new box: the project at the same path, boxd on loopback only, nothing else of this machine", () => {
+ const args = createArgs({ name: "omnirush-box-k", key: "k", root: "/p", croot: "/p", image: "img", runtime: { name: "docker", bin: "docker", vm: false }, run: "/h/projects/k", shims: null, token: "t", user: { uid: 1000, gid: 1000 }, env: {} });
+ expect(args).toContain("type=bind,source=/p,target=/p");
+ expect(args).toContain("127.0.0.1::7777");
+ expect(args.join(" ")).not.toContain("docker.sock");
+ expect(args.filter((arg) => arg.startsWith("type=bind")).length).toBe(2);
+ });
+
+ test("snapshot filter: noise, mounts and credentials out; a folder changed only by them goes too", () => {
+ const kept = filterChanges(parseDiff(["C /var", "C /var/lib", "A /var/lib/apt/lists/x", "C /usr", "A /usr/local/bin/tool", "A /root/.ssh/id_ed25519", "A /p/src/a.ts", "A /root/.cache/ms-playwright/chromium"].join("\n")), { mounts: ["/p"] });
+ expect(kept.map((entry) => entry.path)).toEqual(["/usr", "/usr/local/bin/tool", "/root/.cache/ms-playwright/chromium"]);
+ expect(credentialPath("/home/u/.aws/credentials")).toBe(true);
+ expect(credentialPath("/usr/lib/x.so")).toBe(false);
+ });
+
+ test("tar header and size parsing", () => {
+ const tar = singleFileTar("opt/omnirush/bin/boxd", Buffer.from("hi"));
+ expect(tar.length % 512).toBe(0);
+ expect(tar.subarray(512 * 3, 512 * 3 + 21).toString()).toBe("opt/omnirush/bin/boxd");
+ expect(parseSize("57.2MB (virtual 1.1GB)")).toBe(57_200_000);
+ });
+
+ test("stack detection and image overrides", async () => {
+ const root = await temp("go");
+ await writeFile(join(root, "go.mod"), "module x\n");
+ expect(detectStack(root)).toBe("go");
+ expect(imageFor("go", { env: {} }).ref).toContain("box-go");
+ expect(imageFor("go", { env: { OMNIRUSH_BOX_IMAGE: "local/base:dev" } })).toMatchObject({ pull: "local/base:dev", override: true });
+ });
+
+ test("missing helpers mean unavailable (null, or a reason thrown to the planner), found in the sidecars' box folder", async () => {
+ const home = await temp("home");
+ expect(helperPath("boxsh", { goos: "linux", goarch: "amd64", env: {} })).toBeNull();
+ expect(() => installShell(home, { env: {} })).toThrow("sandbox shell helper is missing");
+ const sidecars = await temp("sidecars");
+ const bin = await helpers();
+ expect(helperPath("boxd", { goos: "linux", goarch: "amd64", env: {}, toolsRoot: sidecars })).toBeNull();
+ expect(helperPath("boxd", { goos: "linux", goarch: "amd64", env: { OMNIRUSH_BOX_BIN_DIR: bin } })).toBe(join(bin, "linux-amd64", "boxd"));
+ if (process.platform !== "win32") {
+ expect(installShell(home, { env: { OMNIRUSH_BOX_BIN_DIR: bin } })).toBe(join(home, "shell-desktop", "bash"));
+ }
+ });
+});
+
+describe("box mode and engine config", () => {
+ test("precedence: OMNIRUSH_BOX, then the project, then the server default (offer until offered once)", () => {
+ expect(resolveMode({ env: { OMNIRUSH_BOX: "0" }, project: "on", server: "on" })).toEqual({ on: false, source: "env", offer: false });
+ expect(resolveMode({ env: {}, project: "off", server: "on" })).toEqual({ on: false, source: "project", offer: false });
+ expect(resolveMode({ env: {}, project: null, server: "on" })).toEqual({ on: true, source: "server", offer: false });
+ expect(resolveMode({ env: {}, project: null, server: "offer" })).toEqual({ on: false, source: "server", offer: true });
+ expect(resolveMode({ env: {}, project: null, server: "offer", offered: true })).toEqual({ on: false, source: "server", offer: false });
+ expect(resolveMode({ env: {}, project: null, server: "off" })).toEqual({ on: false, source: "default", offer: false });
+ });
+
+ test("the server default is remembered from /collect/capabilities", async () => {
+ const state = await temp("state");
+ expect(serverDefault(state)).toBe("off");
+ expect(rememberServerDefault(state, { local_box: { default: "offer" } })).toBe(true);
+ expect(serverDefault(state)).toBe("offer");
+ expect(rememberServerDefault(state, { local_box: { default: "offer" } })).toBe(false);
+ expect(rememberServerDefault(state, {})).toBe(false);
+ expect(rememberServerDefault(state, { local_box: { default: "bogus" } })).toBe(true);
+ expect(serverDefault(state)).toBe("off");
+ });
+
+ test("engine config: the shell and the plugin appended; nothing without bits", () => {
+ expect(engineConfig(null, { plugin: ["a"] })).toEqual({ plugin: ["a"] });
+ expect(engineConfig({ shell: "/h/shell-desktop/bash", plugin: "/p/omnirush-box.js" }, { plugin: ["a"], model: "m" })).toEqual({ plugin: ["a", "/p/omnirush-box.js"], model: "m", shell: "/h/shell-desktop/bash" });
+ });
+
+ test("workspace settings: localBox.mode and offered", () => {
+ expect(readBoxSettings({})).toEqual({ mode: null, offered: false });
+ expect(readBoxSettings({ localBox: { mode: "on", offered: true } })).toEqual({ mode: "on", offered: true });
+ expect(readBoxSettings({ localBox: { mode: "maybe" } })).toEqual({ mode: null, offered: false });
+ });
+});
+
+describe("box plugin", () => {
+ test("routes only listed projects with a live record; file tools stay in the project; the prompt says linux", async () => {
+ const home = await temp("boxhome");
+ const root = await temp("project");
+ process.env.OMNIRUSH_BOX_HOME = home;
+ const key = boxKey(root);
+ const hooks = await OmniRushBox({ directory: root });
+ const env: Record<string, string> = {};
+ await hooks["shell.env"]({ callID: "c1", sessionID: "s1" }, { env });
+ expect(env).toEqual({});
+ await mkdir(join(home, "boxes"), { recursive: true });
+ await writeFile(join(home, "boxes", `${key}.json`), JSON.stringify({ state: "ready", uid: 0 }));
+ // A record alone (a CLI run's) does not route a desktop chat.
+ await hooks["shell.env"]({ callID: "c1", sessionID: "s1" }, { env });
+ expect(env).toEqual({});
+ await writeFile(join(home, DESKTOP_PROJECTS_FILE), JSON.stringify({ keys: [key] }));
+ await hooks["shell.env"]({ callID: "c1", sessionID: "s1" }, { env });
+ expect(env).toEqual({ OMNIRUSH_BOX_KEY: key, OMNIRUSH_CALL: "c1", OMNIRUSH_SESSION: "s1" });
+ await expect(hooks["tool.execute.before"]({ tool: "read" }, { args: { filePath: "/etc/hostname" } })).rejects.toThrow("outside the project folder");
+ await hooks["tool.execute.before"]({ tool: "read" }, { args: { filePath: join(root, "a.txt") } });
+ const system = ["You are...\nPlatform: darwin\n"];
+ const same = system;
+ await hooks["experimental.chat.system.transform"]({}, { system });
+ expect(same).toBe(system);
+ expect(system[0]).toContain("Platform: linux");
+ expect(system[1]).toContain("Sandbox: shell commands run in a Linux (Debian) container");
+ await writeFile(join(home, "boxes", `${key}.json`), JSON.stringify({ state: "off" }));
+ const off: Record<string, string> = {};
+ await hooks["shell.env"]({ callID: "c2" }, { env: off });
+ expect(off).toEqual({});
+ });
+});
+
+describe("box service", () => {
+ type Settings = Map<string, { mode: "on" | "off" | null; offered: boolean }>;
+ function service(input: { stateDir: string; workspaces: BoxWorkspace[]; settings: Settings; env: NodeJS.ProcessEnv }) {
+ return new BoxService({
+ stateDir: input.stateDir,
+ readSettings: async (id) => input.settings.get(id) ?? { mode: null, offered: false },
+ writeSettings: async (id, update) => {
+ const current = input.settings.get(id) ?? { mode: null, offered: false };
+ input.settings.set(id, { mode: update.mode === undefined ? current.mode : update.mode, offered: update.offered ?? current.offered });
+ },
+ workspaces: () => input.workspaces,
+ pluginPath: () => "/plugins/omnirush-box.js",
+ env: input.env,
+ });
+ }
+
+ test("the toggle: engine bits once a workspace is on (or the server offers it), only with the helpers; no runtime is no error", async () => {
+ const stateDir = await temp("state");
+ const home = await temp("boxhome");
+ const root = await temp("project");
+ const bin = await helpers();
+ const workspace: BoxWorkspace = { id: "ws_1", path: root, workspaceType: "local" };
+ const settings: Settings = new Map();
+ const env = { OMNIRUSH_BOX_HOME: home, OMNIRUSH_BOX_BIN_DIR: bin, PATH: "", OMNIRUSH_BOX_RUNTIME: "/nonexistent/docker" };
+ const boxes = service({ stateDir, workspaces: [workspace], settings, env });
+ expect(await boxes.engineBits()).toBeNull();
+ const status = await boxes.setMode(workspace, "on");
+ expect(settings.get("ws_1")).toEqual({ mode: "on", offered: true });
+ expect(status).toMatchObject({ mode: "on", on: true, source: "project", state: "unavailable" });
+ expect(status.runtime?.ok).toBe(false);
+ if (process.platform !== "win32") expect(await boxes.engineBits()).toEqual({ shell: join(home, "shell-desktop", "bash"), plugin: "/plugins/omnirush-box.js" });
+ // Unavailable: the plugin is not told to route this project, and a prompt goes on natively.
+ await boxes.ensure(workspace);
+ expect(await boxes.listedProjects()).toEqual([]);
+ expect(await boxes.beforePrompt("ses_box_test_1", workspace)).toBeNull();
+ await boxes.setMode(workspace, "off");
+ expect(await boxes.engineBits()).toBeNull();
+ rememberServerDefault(stateDir, { local_box: { default: "offer" } });
+ expect(await boxes.status(workspace)).toMatchObject({ on: false, offer: false, state: "off" });
+ await boxes.setMode(workspace, null);
+ expect(await boxes.status(workspace)).toMatchObject({ mode: null, on: false, source: "server", offer: false });
+ if (process.platform !== "win32") expect(await boxes.engineBits()).not.toBeNull();
+ // Without helpers there are no engine bits, whatever the settings.
+ const none = service({ stateDir, workspaces: [workspace], settings, env: { ...env, OMNIRUSH_BOX_BIN_DIR: join(bin, "nothing") } });
+ expect(await none.engineBits()).toBeNull();
+ });
+
+ test("a remote workspace never gets a box", async () => {
+ const stateDir = await temp("state");
+ const workspace: BoxWorkspace = { id: "ws_r", path: "/remote", workspaceType: "remote" };
+ const settings: Settings = new Map([["ws_r", { mode: "on", offered: true }]]);
+ const boxes = service({ stateDir, workspaces: [workspace], settings, env: { OMNIRUSH_BOX_HOME: await temp("boxhome") } });
+ expect(await boxes.ensure(workspace)).toBeNull();
+ expect(await boxes.status(workspace)).toMatchObject({ on: false, state: "off" });
+ });
+});
diff --git a/apps/server/src/box/box.ts b/apps/server/src/box/box.ts
new file mode 100644
index 00000000..26070b3a
--- /dev/null
+++ b/apps/server/src/box/box.ts
@@ -0,0 +1,963 @@
+// 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).
+//
+// 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.
+//
+// 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).
+
+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 os from "node:os";
+import path from "node:path";
+
+import * as client from "./client.js";
+import type { BoxEndpoint, BoxStat } from "./client.js";
+import { detectStack, imageFor, type BoxImage, type ImagePins } from "./images.js";
+import { runCommand, type RunCommand, type RunOptions, 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;
+
+// --- 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(/\/+$/, "") || "/";
+}
+
+/** 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;
+ 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">>;
+
+function rt(runtime: BoxRuntime, run: RunCommand = runCommand) {
+ return (args: string[], opts: RunOptions = {}) => run(runtime.bin, args, { timeoutMs: 60_000, ...opts });
+}
+
+/** 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[] };
+
+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 : [],
+ };
+ } 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, token, user, env = process.env }: { name: string; key: string; root: string; croot: string; image: string; runtime: BoxRuntime; run: string; shims: string | 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=${root},target=${croot}`,
+ "--mount", `type=bind,source=${runFolder},target=${RUN_DIR}`,
+ ...(shims ? ["--mount", `type=bind,source=${shims},target=${SHIMS_DIR}-src,readonly`] : []),
+ "-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;
+/** Never part of a turn's environment: runtime state, logs, download caches the ledger replays. */
+export const NOISE_PREFIXES = [
+ "/run", "/proc", "/sys", "/dev", "/var/log", "/var/cache/apt", "/var/lib/apt/lists", "/var/cache/debconf/templates.dat-old",
+ "/opt/omnirush", "/usr/sbin/docker-init", "/sbin/docker-init", "/var/lib/dpkg/lock", "/var/lib/dpkg/lock-frontend", "/var/cache/ldconfig/aux-cache",
+ `${H}/.cache/pip`, `${H}/.cache/uv`, `${H}/.cache/pre-commit`, `${H}/.cache/yarn`, `${H}/.cache/go-build`, `${H}/.cache/pnpm`,
+ `${H}/.npm/_cacache`, `${H}/.npm/_logs`, `${H}/.npm/_update-notifier-last-checked`, `${H}/.npm/_npx`,
+ `${H}/.bun/install/cache`, `${H}/.yarn/berry/cache`, `${H}/.local/share/pnpm/store`, `${H}/.cargo/registry/cache`, "/usr/local/cargo/registry/cache",
+ `${H}/go/pkg/mod/cache/download`, `${H}/.cache/go-build`, `${H}/.m2/repository/.cache`, `${H}/.gem/cache`, `${H}/.local/share/gem/cache`,
+ `${H}/.gradle/caches`, `${H}/.gradle/daemon`, `${H}/.gradle/native`, `${H}/.bash_history`, `${H}/.python_history`,
+ `${H}/.node_repl_history`, `${H}/.lesshst`, `${H}/.wget-hsts`, `${H}/.sudo_as_admin_successful`,
+];
+/**
+ * Kept although they are under a cache folder: rebuilt turns need them
+ * (bake-off 2026-10-11: pnpm via corepack and Playwright browsers break otherwise).
+ */
+export const KEEP_PREFIXES = [`${H}/.cache/node/corepack`, `${H}/.cache/ms-playwright`];
+export const NOISE_PATTERNS = [/(?:^|\/)__pycache__(?:\/|$)/, /\.py[co]$/, /(?:^|\/)\.(?:pytest|mypy|ruff)_cache(?:\/|$)/, /^\/tmp\/\.bun-[^/]+\.(?:node|so)$/, /^\/tmp\/\.X11-unix/];
+export const NOISE_FILES = new Set(["/etc/passwd", "/etc/group", "/etc/shadow", "/etc/gshadow", "/etc/passwd-", "/etc/group-", "/etc/.pwd.lock", "/etc/hostname", "/etc/hosts", "/etc/resolv.conf", "/etc/mtab", "/etc/sudoers.d/omnirush", "/etc/sudoers.d"]);
+const CREDENTIAL_NAMES = new Set([".ssh", ".gnupg", ".aws", ".azure", ".kube", ".netrc", ".git-credentials", ".pypirc", ".password-store", ".vault-token", ".docker"]);
+const CREDENTIAL_SUBPATHS = [".config/gh", ".config/gcloud", ".config/hub", ".config/op", ".config/rclone", ".config/doctl"];
+const CREDENTIAL_FILE = /(?:^|\/)(?:id_(?:rsa|dsa|ecdsa|ed25519)(?:\.pub)?|[^/]+\.(?:pem|key|p12|pfx|kdbx|jks|keystore))$/i;
+/** Project dependency folders whose contents a turn's snapshot carries (capped). */
+export const DEPENDENCY_DIRS = new Set(["node_modules", ".venv", "venv"]);
+
+function within(child: string, parent: string): boolean {
+ return child === parent || child.startsWith(parent.endsWith("/") ? parent : `${parent}/`);
+}
+
+/** A credential under a home folder (the box's own, or a user's). */
+export function credentialPath(entry: string): boolean {
+ const home = /^(?:\/root|\/home\/[^/]+)\/(.*)$/.exec(entry);
+ if (!home) return CREDENTIAL_FILE.test(entry) && /^\/(?:root|home)\//.test(entry);
+ const rel = home[1]!;
+ const first = rel.split("/")[0]!;
+ if (CREDENTIAL_NAMES.has(first)) return true;
+ if (CREDENTIAL_SUBPATHS.some((prefix) => within(rel, prefix))) return true;
+ return CREDENTIAL_FILE.test(rel);
+}
+
+export type DiffEntry = { kind: string; path: string };
+
+export function parseDiff(stdout: string): DiffEntry[] {
+ const out: DiffEntry[] = [];
+ for (const line of String(stdout).split("\n")) {
+ const match = /^([ACD]) (\/.*)$/.exec(line);
+ if (match) out.push({ kind: match[1]!, path: match[2]! });
+ }
+ return out;
+}
+
+function ancestors(entry: string): string[] {
+ const out: string[] = [];
+ let current = path.posix.dirname(entry);
+ while (current !== "/" && current !== ".") {
+ out.push(current);
+ current = path.posix.dirname(current);
+ }
+ return out;
+}
+
+/** What of `docker diff` is the environment: no noise, nothing in a mount, no credentials. */
+export function filterChanges(entries: DiffEntry[], { mounts = [] }: { mounts?: string[] } = {}): DiffEntry[] {
+ const dropped = new Set<string>();
+ const kept: DiffEntry[] = [];
+ for (const entry of entries) {
+ const p = entry.path;
+ const keep = KEEP_PREFIXES.some((prefix) => within(p, prefix));
+ const noise = !keep && (NOISE_FILES.has(p)
+ || NOISE_PREFIXES.some((prefix) => within(p, prefix))
+ || NOISE_PATTERNS.some((pattern) => pattern.test(p))
+ || credentialPath(p))
+ || mounts.some((target) => within(p, target) || within(target, p));
+ if (noise) dropped.add(p);
+ else kept.push(entry);
+ }
+ // A folder listed only because of what was dropped below it is no change.
+ // Deepest first, so `C /var` goes once `C /var/lib/apt` has gone.
+ const keptBelow = new Map<string, number>();
+ for (const { path: p } of kept) for (const parent of ancestors(p)) keptBelow.set(parent, (keptBelow.get(parent) ?? 0) + 1);
+ const droppedBelow = new Set<string>();
+ for (const p of dropped) for (const parent of ancestors(p)) droppedBelow.add(parent);
+ const gone = new Set<string>();
+ const deepestFirst = kept.filter(({ kind }) => kind === "C").sort((a, b) => b.path.split("/").length - a.path.split("/").length);
+ for (const { path: p } of deepestFirst) {
+ if (!droppedBelow.has(p) || keptBelow.get(p)) continue;
+ gone.add(p);
+ for (const parent of ancestors(p)) {
+ keptBelow.set(parent, (keptBelow.get(parent) ?? 1) - 1);
+ droppedBelow.add(parent);
+ }
+ }
+ return kept.filter(({ path: p }) => !gone.has(p));
+}
+
+function signature(entry: BoxStat): string {
+ if (entry.type === "dir") return `d|${entry.mode}|${entry.uid}:${entry.gid}`;
+ if (entry.type === "symlink") return `l|${entry.link}|${entry.uid}:${entry.gid}`;
+ return `${entry.type}|${entry.mode}|${entry.size}|${entry.mtime_ns}|${entry.ctime_ns}|${entry.uid}:${entry.gid}`;
+}
+
+function canonical(value: unknown): string {
+ if (value === null || typeof value !== "object") return JSON.stringify(value);
+ if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+ const record = value as Record<string, unknown>;
+ return `{${Object.keys(record).sort().map((k) => `${JSON.stringify(k)}:${canonical(record[k])}`).join(",")}}`;
+}
+
+/** Topmost paths only (a removed folder covers what was under it). */
+function topmost(paths: string[]): string[] {
+ const sorted = [...new Set(paths)].sort();
+ const out: string[] = [];
+ for (const p of sorted) if (!out.some((top) => within(p, top))) out.push(p);
+ return out;
+}
+
+/** Dependency folders of the project (top level, and one or two levels down). */
+export function dependencyFolders(root: string, { maxDepth = 2 }: { maxDepth?: number } = {}): string[] {
+ const out: string[] = [];
+ const visit = (dir: string, depth: number) => {
+ let entries;
+ try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
+ for (const entry of entries) {
+ if (!entry.isDirectory() || entry.isSymbolicLink()) continue;
+ const full = path.join(dir, entry.name);
+ if (DEPENDENCY_DIRS.has(entry.name)) { out.push(full); continue; }
+ if (depth < maxDepth && !entry.name.startsWith(".") && entry.name !== "dist" && entry.name !== "build" && entry.name !== "target") visit(full, depth + 1);
+ }
+ };
+ visit(root, 0);
+ return out;
+}
+
+// --- the box ---------------------------------------------------------------------
+
+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`.
+ */
+export async function openBox({ root, runtime, env = process.env, platform = process.platform, home = boxHome(env), run = runCommand, log = () => {}, shims = 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; pull?: boolean; image?: BoxImage | null; onState?: OnState }): Promise<Box> {
+ const projectRoot = path.resolve(root);
+ const key = boxKey(projectRoot, { platform });
+ const name = containerName(key, env);
+ const croot = containerRoot(projectRoot, platform);
+ 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 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, 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;
+ 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));
+ }
+ 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) }));
+ box.setState("ready", null, onState);
+ return box;
+ } catch (error) {
+ return box.fail(error instanceof Error ? error.message : String(error), onState);
+ } finally {
+ lock.release();
+ }
+}
+
+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 });
+ const deadline = Date.now() + waitMs;
+ for (;;) {
+ try {
+ writeFileSync(file, String(process.pid), { flag: "wx" });
+ return { release: () => { try { unlinkSync(file); } catch { /* gone */ } } };
+ } catch {
+ let stale = false;
+ try {
+ const pid = Number(readFileSync(file, "utf8"));
+ stale = !pid || Date.now() - statSync(file).mtimeMs > 120_000 || !alive(pid);
+ } catch { stale = true; }
+ if (stale) { try { unlinkSync(file); } catch { /* raced */ } continue; }
+ if (Date.now() > deadline) return { release: () => {} };
+ await new Promise((resolve) => setTimeout(resolve, 150));
+ }
+ }
+}
+
+function alive(pid: number): boolean {
+ try { process.kill(pid, 0); return true; } catch (error) { return typeof error === "object" && error !== null && "code" in error && error.code === "EPERM"; }
+}
+
+export type CheckpointSummary = {
+ schema: number;
+ label: string;
+ turn: number | null;
+ tar: string | null;
+ bytes: number;
+ sha256: string | null;
+ full: boolean;
+ leaf?: true;
+ delta: { parent: string | null; changed: string[]; removed: string[] };
+ checkpoint: Record<string, unknown>;
+ skipped: Array<{ path: string; size: number; reason: string }>;
+ deps?: Record<string, unknown>;
+ stats: { source: string; diff_entries: number; kept: number; copied: number; removed: number; diff_ms: number; stat_ms: number; tar_ms: number; total_ms: number; warning?: string };
+};
+
+export type Checkpoint = {
+ summary: CheckpointSummary;
+ commit: (to?: string) => CheckpointSummary;
+ discard: () => void;
+};
+
+type Chain = { container: string; last: string | null; signatures: Record<string, string> };
+
+export type BoxLabel = {
+ kind: string;
+ box_id: string;
+ runtime: { name: string; flavor: string; version: string | null; rootless: boolean };
+ image: { ref: string | null; digest: string | null; stack: string | null };
+ host_os: string;
+ host_arch: string;
+};
+
+type BoxInit = { key: string; name: string; root: string; croot: string; runtime: BoxRuntime; home: string; runFolder: string; run: RunCommand; log: BoxLog; platform: NodeJS.Platform; env: Env };
+
+export class Box {
+ readonly key: string;
+ readonly name: string;
+ readonly root: string;
+ readonly croot: string;
+ readonly runtime: BoxRuntime;
+ readonly home: string;
+ readonly runFolder: string;
+ readonly run: RunCommand;
+ readonly log: BoxLog;
+ readonly platform: NodeJS.Platform;
+ readonly env: Env;
+ readonly container: string;
+ state: BoxState = "starting";
+ error: string | null = null;
+ endpoint: BoxEndpoint | null = null;
+ identity: Record<string, unknown> | null = null;
+ pathPrefix = "";
+ uid: number | undefined;
+ gid: number | undefined;
+ containerId: string | undefined;
+ imageId: string | undefined;
+ private queue: Promise<unknown> = Promise.resolve();
+
+ constructor({ key, name, root, croot, runtime, home, runFolder, run, log, platform, env }: BoxInit) {
+ this.key = key;
+ this.name = name;
+ this.root = root;
+ this.croot = croot;
+ this.runtime = runtime;
+ this.home = home;
+ this.runFolder = runFolder;
+ this.run = run;
+ this.log = log;
+ this.platform = platform;
+ this.env = env;
+ 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 };
+ this.uid = uid;
+ this.gid = gid;
+ this.containerId = containerId;
+ this.imageId = imageId;
+ }
+
+ /** The record boxsh reads (boxes/<key>.json). */
+ writeRecord(): void {
+ const record: BoxRecord = {
+ v: 1, key: this.key, root: this.root, croot: this.croot, container: this.name, runtime: this.runtime?.bin ?? "",
+ 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,
+ };
+ writeJson(recordFile(this.home, this.key), record);
+ }
+
+ setState(state: BoxState, error: string | null, onState: OnState = () => {}): void {
+ this.state = state;
+ this.error = error;
+ this.writeRecord();
+ onState(state, error);
+ }
+
+ fail(error: string, onState?: OnState): Box {
+ this.setState("failed", error, onState);
+ this.log("warn", "box failed", { key: this.key, error });
+ return this;
+ }
+
+ get ready(): boolean {
+ return this.state === "ready";
+ }
+
+ /** The image the container runs (pin, digest, stack) as recorded at creation. */
+ image(): { ref: string | null; digest: string | null; id: string | null; stack: string | null; created_at?: string } {
+ return readJson(path.join(this.home, "chains", this.key, "image.json")) ?? { ref: null, digest: null, id: this.imageId ?? null, stack: null };
+ }
+
+ /** The package-manager wrappers, installed inside (their install.sh), and the env they need. */
+ async installShims(): Promise<void> {
+ const res = await client.exec(this.endpoint!, ["/bin/sh", `${SHIMS_DIR}-src/install.sh`, SHIMS_DIR, `${RUN_DIR}/ledger.jsonl`, `${RUN_DIR}/state`], { timeoutMs: 30_000 });
+ if (res.code !== 0) throw new Error(firstLine(res.stderr) || `install.sh exited ${res.code}`);
+ const lines: string[] = [];
+ for (const raw of res.stdout.split("\n")) {
+ const match = /^([A-Z_][A-Z0-9_]*)=(.*)$/.exec(raw.trim());
+ if (!match) continue;
+ const [, name, value] = match;
+ // `dir:$PATH`, `dir${PYTHONPATH:+:$PYTHONPATH}`: our part only (boxd adds PATH itself).
+ const own = value!.replace(/\$\{[A-Z_]+:\+[^}]*\}/g, "").replace(/:?\$[A-Z_]+$/, "").replace(/ \$\{NODE_OPTIONS[^}]*\}$/, "");
+ if (name === "PATH") this.pathPrefix = own;
+ else lines.push(`${name}=${own}`);
+ }
+ // boxd puts BOXD_PATH_PREFIX in front of the image's own PATH.
+ if (this.pathPrefix) lines.push(`BOXD_PATH_PREFIX=${this.pathPrefix}`);
+ writeFileSync(path.join(this.runFolder, "env"), `${lines.join("\n")}\n`, { mode: 0o644 });
+ this.writeRecord();
+ }
+
+ /** The prompt number the package-manager wrappers write into their lines. */
+ setTurn(turn: number): void {
+ try { writeFileSync(path.join(this.runFolder, "state", "turn"), `${turn}\n`); } catch { /* best effort */ }
+ }
+
+ /** Where the wrappers' lines land on this machine. */
+ get ledgerPath(): string {
+ return path.join(this.runFolder, "ledger.jsonl");
+ }
+
+ /** The record a session's snapshots folder starts with (record.json; environment.sandbox in uploads). */
+ describe() {
+ const image = this.image();
+ return {
+ schema: RECORD_SCHEMA,
+ kind: "omnirush-box",
+ box: { id: `box_${this.key}`, container: this.name, created_at: image.created_at ?? null },
+ 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() },
+ project: { host_root: this.root, container_root: this.croot },
+ user: { uid: this.uid ?? 0, gid: this.gid ?? 0, home: HOME_IN_BOX },
+ environment: { HOME: HOME_IN_BOX, shims: this.pathPrefix ? SHIMS_DIR : null },
+ excluded: { prefixes: NOISE_PREFIXES, keep: KEEP_PREFIXES, patterns: NOISE_PATTERNS.map(String), dependency_dirs: [...DEPENDENCY_DIRS] },
+ };
+ }
+
+ /** 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 };
+ }
+
+ /** Run a command in the box (toolchain probes, status). */
+ exec(argv: string[], opts: { cwd?: string; env?: Record<string, string>; timeoutMs?: number } = {}): Promise<client.ExecResult> {
+ return client.exec(this.endpoint!, argv, opts);
+ }
+
+ /**
+ * The checkpoint of turn `turn` for a session: what the box changed since
+ * the session's previous committed checkpoint in `dir` (all of it for the
+ * first). It is staged: `commit()` places it in `dir` and makes it the
+ * parent of the next one (`leaf`: placed, never a parent: `final`);
+ * `discard()` drops it (a turn that never came). Checkpoints are taken one
+ * at a time. Resolves { summary, commit, discard }.
+ */
+ checkpoint(dir: string, turn: number | null, opts: { label?: string | null; leaf?: boolean; deps?: boolean; tarMax?: number; depsMax?: number } = {}): Promise<Checkpoint> {
+ const work = this.queue.then(() => this.takeCheckpoint(dir, turn, opts));
+ this.queue = work.catch(() => undefined);
+ return work;
+ }
+
+ private async takeCheckpoint(dir: string, turn: number | null, { label: asked = null, leaf = false, deps = this.env.OMNIRUSH_BOX_DEPS !== "off", tarMax = Number(this.env.OMNIRUSH_BOX_TAR_MAX) || TAR_MAX_BYTES, depsMax = Number(this.env.OMNIRUSH_BOX_DEPS_MAX) || DEPS_MAX_BYTES }: { label?: string | null; leaf?: boolean; deps?: boolean; tarMax?: number; depsMax?: number } = {}): Promise<Checkpoint> {
+ if (!this.ready || !this.endpoint) throw new Error(`the sandbox is ${this.state}`);
+ const endpoint = this.endpoint;
+ const t0 = Date.now();
+ mkdirSync(dir, { recursive: true });
+ const chainFile = path.join(dir, ".chain.json");
+ let chain = readJson<Chain>(chainFile);
+ const full = !chain || chain.container !== this.containerId;
+ if (!chain || full) chain = { container: this.containerId ?? "", last: null, signatures: {} };
+
+ // What the box changed against its image: boxd's walk (fast, any runtime), else `diff`
+ // (overlay2's naive diff walks the whole image on most Linux kernels: ~1 s for 1 GB).
+ const mounts = [this.croot, RUN_DIR, `${SHIMS_DIR}-src`];
+ const walked = await client.changes(endpoint, NOISE_PREFIXES, KEEP_PREFIXES);
+ let entries: DiffEntry[];
+ let stats: BoxStat[];
+ let source = "boxd";
+ if (walked) {
+ entries = filterChanges(walked.map((entry) => ({ kind: entry.kind, path: entry.path })), { mounts });
+ const keptPaths = new Set(entries.map((entry) => entry.path));
+ 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 });
+ 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);
+ stats = present.length ? await client.stat(endpoint, present) : [];
+ }
+ const tDiff = Date.now();
+ // Project dependency folders, walked inside (they are in the bind mount, which `diff` never lists).
+ let depStats: BoxStat[] = [];
+ let depsInfo: { folders: number; entries: number; truncated: boolean } | null = null;
+ if (deps) {
+ const folders = dependencyFolders(this.root).map((folder) => path.posix.join(this.croot, path.relative(this.root, folder).split(path.sep).join("/")));
+ if (folders.length) {
+ const walkedDeps = await client.walk(endpoint, folders);
+ depStats = (walkedDeps.entries ?? []).filter((entry) => !NOISE_PATTERNS.some((pattern) => pattern.test(entry.path)) && !/\/node_modules\/\.cache(\/|$)/.test(entry.path));
+ depsInfo = { folders: folders.length, entries: depStats.length, truncated: Boolean(walkedDeps.truncated) };
+ }
+ }
+ const tStat = Date.now();
+ const now: Record<string, string> = {};
+ const sized = new Map<string, BoxStat>();
+ for (const entry of [...stats, ...depStats]) {
+ if (entry.type === "missing" || entry.type === "other") continue;
+ now[entry.path] = signature(entry);
+ sized.set(entry.path, entry);
+ }
+ const before = chain.signatures ?? {};
+ const isDep = (p: string) => p.startsWith(`${this.croot}/`);
+ const candidates = Object.keys(now).filter((p) => before[p] !== now[p]).sort();
+ const removed = topmost(Object.keys(before).filter((p) => !(p in now)));
+ // Caps: whole files past FILE_MAX left out; dependency folders up to depsMax; the tar up to tarMax.
+ const skipped: Array<{ path: string; size: number; reason: string }> = [];
+ let depBytes = 0;
+ let total = 0;
+ const changed: string[] = [];
+ let depsCut = false;
+ for (const p of [...candidates.filter((x) => !isDep(x)), ...candidates.filter(isDep)]) {
+ const entry = sized.get(p);
+ const size = entry?.type === "file" ? entry.size ?? 0 : 0;
+ if (size > FILE_MAX_BYTES) { skipped.push({ path: p, size, reason: "too_large" }); continue; }
+ if (isDep(p)) {
+ if (depsCut || depBytes + size > depsMax) { depsCut = true; skipped.push({ path: p, size, reason: "dependency_cap" }); continue; }
+ depBytes += size;
+ }
+ if (total + size > tarMax) { skipped.push({ path: p, size, reason: "tar_cap" }); continue; }
+ total += size;
+ changed.push(p);
+ }
+ const skippedSet = new Set(skipped.map((item) => item.path));
+ const label = asked ?? `turn-${turn}`;
+ const stage = path.join(dir, `.stage-${label}-${process.pid}-${randomBytes(3).toString("hex")}`);
+ mkdirSync(stage, { recursive: true });
+ let tarInfo: Awaited<ReturnType<typeof client.tarTo>> | null = null;
+ if (changed.length) tarInfo = await client.tarTo(endpoint, changed, path.join(stage, `${label}.tar`));
+ const tTar = Date.now();
+ // What a later checkpoint compares with: a path left out stays "unknown", so it is tried again.
+ const signatures: Record<string, string> = {};
+ for (const [p, sig] of Object.entries(now)) if (!skippedSet.has(p)) signatures[p] = sig;
+ const image = this.image();
+ const parent = full ? null : chain.last;
+ const id = `cp_${createHash("sha256").update(canonical({ schema: RECORD_SCHEMA, box: this.key, container: this.containerId, label, turn, parent, image: image.digest || image.id, changed, removed, sha256: tarInfo?.sha256 ?? null })).digest("hex")}`;
+ const summary: CheckpointSummary = {
+ schema: RECORD_SCHEMA,
+ label,
+ turn: turn ?? null,
+ tar: tarInfo ? `${label}.tar` : null,
+ bytes: tarInfo?.bytes ?? 0,
+ sha256: tarInfo?.sha256 ?? null,
+ full,
+ ...(leaf ? { leaf: true as const } : {}),
+ delta: { parent, changed, removed },
+ checkpoint: { schema: RECORD_SCHEMA, id, parent, turn: turn ?? null, image: { ref: image.ref ?? null, digest: image.digest ?? null }, status: "complete", capturedAt: new Date().toISOString() },
+ skipped,
+ ...(depsInfo ? { deps: { ...depsInfo, bytes: depBytes, cut: depsCut } } : {}),
+ stats: { source, diff_entries: entries.length, kept: Object.keys(now).length, copied: changed.length, removed: removed.length, diff_ms: tDiff - t0, stat_ms: tStat - tDiff, tar_ms: tTar - tStat, total_ms: Date.now() - t0, ...(tarInfo?.warning ? { warning: tarInfo.warning } : {}) },
+ };
+ writeJson(path.join(stage, `${label}.json`), summary, 0o600);
+ this.log("info", "box checkpoint", { label, full, copied: changed.length, removed: removed.length, bytes: summary.bytes, ms: summary.stats.total_ms });
+ let settled = false;
+ const record = this.describe();
+ return {
+ summary,
+ /** Place it in `to` (default: the folder it was taken for) and, unless a leaf, chain on from it. */
+ commit: (to = dir) => {
+ if (settled) return summary;
+ settled = true;
+ mkdirSync(to, { recursive: true });
+ const recordPath = path.join(to, "record.json");
+ if (!existsSync(recordPath)) writeJson(recordPath, record, 0o600);
+ rmSync(path.join(to, `${label}.tar`), { force: true });
+ for (const name of readdirSync(stage)) renameSync(path.join(stage, name), path.join(to, name));
+ rmSync(stage, { recursive: true, force: true });
+ if (!leaf) writeJson(path.join(to, ".chain.json"), { container: this.containerId, last: id, label, turn, signatures }, 0o600);
+ return summary;
+ },
+ discard: () => {
+ if (settled) return;
+ settled = true;
+ rmSync(stage, { recursive: true, force: true });
+ },
+ };
+ }
+
+ /** 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);
+ }
+}
+
+/** "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 };
+
+/** 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;
+}
+
+/** 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 });
+ rmSync(recordFile(home, key), { force: true });
+ rmSync(path.join(home, "chains", key), { recursive: true, force: true });
+ return { key, removed: res.code === 0 };
+}
+
+/**
+ * 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.
+ */
+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 });
+ 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) {
+ 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" });
+ }
+ return removed;
+}
+
+/** Count of complete turn checkpoints in a session's folder (resume continues after it). */
+export function savedTurns(dir: string): number {
+ try {
+ return readdirSync(dir).map((name) => /^turn-(\d+)\.json$/.exec(name)?.[1]).filter((n): n is string => Boolean(n)).map(Number).reduce((a, b) => Math.max(a, b), 0);
+ } catch {
+ return 0;
+ }
+}
diff --git a/apps/server/src/box/capture.ts b/apps/server/src/box/capture.ts
new file mode 100644
index 00000000..07fb195e
--- /dev/null
+++ b/apps/server/src/box/capture.ts
@@ -0,0 +1,37 @@
+/**
+ * The capture worker's side of a chat in a box (service.ts BoxCaptureInfo):
+ * the toolchain probes run in the box (CLI: launch.js boxSession
+ * probeRunner), reaching boxd through the project's record. The
+ * environment block of such a chat: session-uploader.ts boxEnvironment.
+ */
+import { exec } from "./client.js";
+import { boxHome, readRecord } from "./box.js";
+import { mapToBox } from "./launch.js";
+import type { BoxCaptureInfo } from "./service.js";
+
+export type BoxProbeResult = { code: number | null; stdout: string; stderr: string } | null;
+
+/**
+ * Runs a toolchain probe in the box of the project `cwd` is in, with no
+ * downloads and no ledger lines; null when that box is not ready (the probe
+ * then reports nothing rather than this machine's answer).
+ */
+export function boxProbeRunner(boxFor: (cwd: string) => BoxCaptureInfo | null, probeEnv: Record<string, string> = {}, env: NodeJS.ProcessEnv = process.env) {
+ return async (file: string, args: string[], { cwd, timeoutMs, maxBytes }: { cwd: string; timeoutMs: number; maxBytes: number }): Promise<BoxProbeResult> => {
+ const box = boxFor(cwd);
+ if (!box) return null;
+ const record = readRecord(boxHome(env), box.key);
+ if (!record || record.state !== "ready" || !record.port || !record.token) return null;
+ try {
+ const res = await exec({ host: record.host, port: record.port, token: record.token }, [file, ...args], {
+ cwd: mapToBox(cwd, box.root, box.croot),
+ env: { ...probeEnv, COREPACK_ENABLE_NETWORK: "0", COREPACK_ENABLE_AUTO_PIN: "0", OMNIRUSH_LEDGER_OFF: "1", NPM_CONFIG_UPDATE_NOTIFIER: "false", PIP_DISABLE_PIP_VERSION_CHECK: "1" },
+ timeoutMs,
+ });
+ if (res.code >= 125 && res.code <= 127) return null;
+ return { code: res.code, stdout: res.stdout.slice(0, maxBytes), stderr: res.stderr.slice(0, maxBytes) };
+ } catch {
+ return null;
+ }
+ };
+}
diff --git a/apps/server/src/box/client.ts b/apps/server/src/box/client.ts
new file mode 100644
index 00000000..5b138890
--- /dev/null
+++ b/apps/server/src/box/client.ts
@@ -0,0 +1,165 @@
+// Ported from the CLI (omnirush-cli src/box/client.js, feat/local-box);
+// keep the two in step. Only types were added here.
+//
+// The host side of boxd's wire format (box/go/proto): one TCP connection per
+// operation, a JSON request line, then type+length frames. The engine's
+// shell calls go through the native client (boxsh); this one is for the
+// launcher: readiness, the snapshot's stat/walk/tar, and toolchain probes.
+
+import { createHash } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import net from "node:net";
+
+export const PROTO_VERSION = 1;
+const T = { stdout: 0x6f, stderr: 0x65, exit: 0x78, data: 0x64, fail: 0x45, stdinEof: 0x63, signal: 0x73 };
+
+export type BoxEndpoint = { host?: string; port: number; token: string };
+export type BoxRequest = { op: string; argv?: string[]; cwd?: string; env?: Record<string, string>; paths?: string[]; wait?: number };
+export type BoxExit = { code: number; ms?: number };
+export type BoxReply = { exit: BoxExit; stdout: string; stderr: string; data: Buffer };
+export type BoxStat = { path: string; type: string; mode?: number; size?: number; uid?: number; gid?: number; link?: string; mtime_ns?: number | string; ctime_ns?: number | string };
+export type BoxChange = BoxStat & { kind: "A" | "C" | "D" };
+
+function frame(kind: number, payload = Buffer.alloc(0)): Buffer {
+ const head = Buffer.alloc(5);
+ head[0] = kind;
+ head.writeUInt32BE(payload.length, 1);
+ return Buffer.concat([head, payload]);
+}
+
+/**
+ * One operation: resolves { exit, stdout, stderr, data } where data is the
+ * concatenated Data frames (unless onData takes them). Rejects when the box
+ * cannot be reached or closes early.
+ */
+export function request(
+ box: BoxEndpoint,
+ req: BoxRequest,
+ { onData, onStdout, onStderr, timeoutMs = 30_000, signal }: { onData?: (chunk: Buffer) => void; onStdout?: (chunk: Buffer) => void; onStderr?: (chunk: Buffer) => void; timeoutMs?: number; signal?: AbortSignal } = {},
+): Promise<BoxReply> {
+ return new Promise((resolve, reject) => {
+ const socket = net.connect({ host: box.host || "127.0.0.1", port: box.port });
+ socket.setNoDelay(true);
+ let buffered: Buffer = Buffer.alloc(0);
+ const out: Buffer[] = [];
+ const err: Buffer[] = [];
+ const data: Buffer[] = [];
+ let settled = false;
+ const finish = <V>(fn: (value: V) => void, value: V) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ signal?.removeEventListener?.("abort", onAbort);
+ socket.destroy();
+ fn(value);
+ };
+ const onAbort = () => finish(reject, new Error("aborted"));
+ signal?.addEventListener?.("abort", onAbort, { once: true });
+ const timer = setTimeout(() => finish(reject, new Error(`box ${req.op} timed out after ${timeoutMs} ms`)), timeoutMs);
+ socket.once("connect", () => {
+ socket.write(`${JSON.stringify({ v: PROTO_VERSION, token: box.token, ...req })}\n`);
+ if (req.op === "exec") socket.write(frame(T.stdinEof));
+ });
+ socket.on("error", (error) => finish(reject, error));
+ socket.on("close", () => finish(reject, new Error(`box closed the ${req.op} connection early`)));
+ socket.on("data", (chunk: Buffer) => {
+ buffered = buffered.length ? Buffer.concat([buffered, chunk]) : chunk;
+ while (buffered.length >= 5) {
+ const size = buffered.readUInt32BE(1);
+ if (buffered.length < 5 + size) break;
+ const kind = buffered[0];
+ const payload = buffered.subarray(5, 5 + size);
+ buffered = buffered.subarray(5 + size);
+ if (kind === T.stdout) (onStdout ? onStdout(payload) : out.push(Buffer.from(payload)));
+ else if (kind === T.stderr || kind === T.fail) (onStderr ? onStderr(payload) : err.push(Buffer.from(payload)));
+ else if (kind === T.data) {
+ if (onData) {
+ try { onData(payload); } catch (error) { finish(reject, error); return; }
+ } else data.push(Buffer.from(payload));
+ } else if (kind === T.exit) {
+ let exit: BoxExit = { code: 0 };
+ try { exit = JSON.parse(payload.toString("utf8")); } catch { /* keep */ }
+ finish(resolve, { exit, stdout: Buffer.concat(out).toString("utf8"), stderr: Buffer.concat(err).toString("utf8"), data: Buffer.concat(data) });
+ return;
+ }
+ }
+ });
+ });
+}
+
+/** boxd's identity, or null when it does not answer. */
+export async function ping(box: BoxEndpoint, { timeoutMs = 2_000 }: { timeoutMs?: number } = {}): Promise<Record<string, unknown> | null> {
+ try {
+ const result = await request(box, { op: "ping" }, { timeoutMs });
+ return JSON.parse(result.data.toString("utf8"));
+ } catch {
+ return null;
+ }
+}
+
+export type ExecResult = { code: number; stdout: string; stderr: string; ms?: number };
+
+/** Run a command in the box: { code, stdout, stderr, ms }. */
+export async function exec(box: BoxEndpoint, argv: string[], { cwd, env, timeoutMs = 60_000 }: { cwd?: string; env?: Record<string, string>; timeoutMs?: number } = {}): Promise<ExecResult> {
+ const result = await request(box, { op: "exec", argv, ...(cwd ? { cwd } : {}), ...(env ? { env } : {}) }, { timeoutMs });
+ return { code: result.exit.code, stdout: result.stdout, stderr: result.stderr, ms: result.exit.ms };
+}
+
+/** lstat of each path, in order (type "missing" for a path that is gone). */
+export async function stat(box: BoxEndpoint, paths: string[], { timeoutMs = 60_000 }: { timeoutMs?: number } = {}): Promise<BoxStat[]> {
+ const out: BoxStat[] = [];
+ for (let i = 0; i < paths.length; i += 20_000) {
+ const result = await request(box, { op: "stat", paths: paths.slice(i, i + 20_000) }, { timeoutMs });
+ out.push(...JSON.parse(result.data.toString("utf8")));
+ }
+ return out;
+}
+
+/**
+ * What differs from the image ({ kind: A|C|D, path, ...stat }), walked by
+ * boxd against the index it took at the box's first start; `skip` folders
+ * are not walked (their `keep` subfolders are). Null when boxd cannot (an
+ * older box with no index): the caller uses the runtime's `diff`.
+ */
+export async function changes(box: BoxEndpoint, skip: string[], keep: string[], { timeoutMs = 120_000 }: { timeoutMs?: number } = {}): Promise<BoxChange[] | null> {
+ try {
+ const result = await request(box, { op: "changes", paths: skip, env: { keep: keep.join(",") } }, { timeoutMs });
+ if (result.exit.code !== 0) return null;
+ return JSON.parse(result.data.toString("utf8"));
+ } catch {
+ return null;
+ }
+}
+
+/** Every entry below the folders, stat fields included. */
+export async function walk(box: BoxEndpoint, roots: string[], { max = 400_000, timeoutMs = 120_000 }: { max?: number; timeoutMs?: number } = {}): Promise<{ entries?: BoxStat[]; truncated?: boolean }> {
+ const result = await request(box, { op: "walk", paths: roots, wait: max }, { timeoutMs });
+ return JSON.parse(result.data.toString("utf8"));
+}
+
+/** Tar exactly these paths into `file`: { bytes, sha256, ms, warning }. */
+export async function tarTo(box: BoxEndpoint, paths: string[], file: string, { timeoutMs = 15 * 60_000 }: { timeoutMs?: number } = {}): Promise<{ bytes: number; sha256: string; ms?: number; warning: string | null }> {
+ const stream = createWriteStream(file, { mode: 0o600 });
+ const hash = createHash("sha256");
+ let bytes = 0;
+ let pending: Promise<unknown> = Promise.resolve();
+ const opened = new Promise((resolve, reject) => { stream.once("open", resolve); stream.once("error", reject); });
+ await opened;
+ let result: BoxReply;
+ try {
+ result = await request(box, { op: "tar", paths }, {
+ timeoutMs,
+ onData: (chunk) => {
+ const copy = Buffer.from(chunk);
+ hash.update(copy);
+ bytes += copy.length;
+ if (!stream.write(copy)) pending = new Promise<void>((resolve) => stream.once("drain", () => resolve()));
+ },
+ });
+ } finally {
+ await pending;
+ await new Promise<void>((resolve) => stream.end(() => resolve()));
+ }
+ if (result.exit.code !== 0) throw new Error(`box tar failed: ${result.stderr.trim() || result.exit.code}`);
+ return { bytes, sha256: hash.digest("hex"), ms: result.exit.ms, warning: result.stderr.trim() || null };
+}
diff --git a/apps/server/src/box/desktop.ts b/apps/server/src/box/desktop.ts
new file mode 100644
index 00000000..3465c1c1
--- /dev/null
+++ b/apps/server/src/box/desktop.ts
@@ -0,0 +1,58 @@
+/**
+ * The server's one BoxService (service.ts) per ServerConfig, with the
+ * workspace settings in the workspace's OmniRush config row
+ * (`localBox: { mode: "on" | "off", offered: true }`).
+ */
+import { omnirushPluginPath } from "../omnirush-extensions-plugin-path.js";
+import { readOmniRushWorkspaceConfig, writeOmniRushWorkspaceConfig } from "../omnirush-workspace-config-store.js";
+import { runtimeStorageDir } from "../runtime-db.js";
+import type { ServerConfig } from "../types.js";
+import type { BoxLog } from "./box.js";
+import type { ProjectBoxMode } from "./launch.js";
+import { BoxService, nativeShell } from "./service.js";
+
+export const BOX_SETTINGS_KEY = "localBox";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+ return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** The workspace's own choice: "on", "off", or null (the server's default). */
+export function readBoxSettings(omnirush: Record<string, unknown>): { mode: ProjectBoxMode; offered: boolean } {
+ const block = isRecord(omnirush[BOX_SETTINGS_KEY]) ? omnirush[BOX_SETTINGS_KEY] : {};
+ const mode = block.mode === "on" || block.mode === "off" ? block.mode : null;
+ return { mode, offered: block.offered === true };
+}
+
+const services = new WeakMap<ServerConfig, BoxService>();
+
+export function boxServiceFor(config: ServerConfig, log?: BoxLog): BoxService {
+ let service = services.get(config);
+ if (service) {
+ if (log) service.useLog(log);
+ return service;
+ }
+ // boxsh runs this shell for every call that is not for a box (Windows: Git for Windows' bash).
+ const shell = process.env.OMNIRUSH_BOX_REAL_SHELL ? null : nativeShell();
+ if (shell) process.env.OMNIRUSH_BOX_REAL_SHELL = shell;
+ service = new BoxService({
+ stateDir: runtimeStorageDir(config),
+ readSettings: async (workspaceId) => readBoxSettings(await readOmniRushWorkspaceConfig(config, workspaceId)),
+ writeSettings: async (workspaceId, update) => {
+ await writeOmniRushWorkspaceConfig(config, workspaceId, (current) => {
+ const block = isRecord(current[BOX_SETTINGS_KEY]) ? { ...current[BOX_SETTINGS_KEY] } : {};
+ if (update.mode !== undefined) {
+ if (update.mode === null) delete block.mode;
+ else block.mode = update.mode;
+ }
+ if (update.offered !== undefined) block.offered = update.offered;
+ return { ...current, [BOX_SETTINGS_KEY]: block };
+ });
+ },
+ workspaces: () => config.workspaces,
+ pluginPath: () => omnirushPluginPath("omnirush-box"),
+ ...(log ? { log } : {}),
+ });
+ services.set(config, service);
+ return service;
+}
diff --git a/apps/server/src/box/images.json b/apps/server/src/box/images.json
new file mode 100644
index 00000000..0c4bc6b6
--- /dev/null
+++ b/apps/server/src/box/images.json
@@ -0,0 +1,11 @@
+{
+ "version": "2026.10.1",
+ "registry": "ghcr.io/omnirush-ai",
+ "images": {
+ "base": { "ref": "ghcr.io/omnirush-ai/box-base:2026.10.1", "digest": null, "approx_mb": 190 },
+ "go": { "ref": "ghcr.io/omnirush-ai/box-go:2026.10.1", "digest": null, "approx_mb": 270 },
+ "rust": { "ref": "ghcr.io/omnirush-ai/box-rust:2026.10.1", "digest": null, "approx_mb": 330 },
+ "java": { "ref": "ghcr.io/omnirush-ai/box-java:2026.10.1", "digest": null, "approx_mb": 290 },
+ "ruby": { "ref": "ghcr.io/omnirush-ai/box-ruby:2026.10.1", "digest": null, "approx_mb": 220 }
+ }
+}
diff --git a/apps/server/src/box/images.ts b/apps/server/src/box/images.ts
new file mode 100644
index 00000000..1de896c7
--- /dev/null
+++ b/apps/server/src/box/images.ts
@@ -0,0 +1,58 @@
+// Ported from the CLI (omnirush-cli src/box/images.js + images.json,
+// feat/local-box); keep the two in step. images.json is a copy of the CLI's.
+//
+// The prebuilt box images (box/images/<stack>/Dockerfile in the CLI repo,
+// published to GHCR by its box-images workflow) and which one a project
+// starts on. `base` has the build tools plus Python and Node (the two stacks
+// most projects mix); the others add one toolchain on top of it.
+//
+// A pin's digest is null until the image is published: the tag is used and
+// the digest the runtime pulled is recorded in the box record instead.
+// OMNIRUSH_BOX_IMAGE (every stack) or OMNIRUSH_BOX_IMAGE_<STACK> overrides.
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+import bundledPins from "./images.json" with { type: "json" };
+
+export const STACKS = ["base", "go", "rust", "java", "ruby"];
+
+export type ImagePin = { ref: string; digest: string | null; approx_mb?: number | null };
+export type ImagePins = { version?: string; registry?: string; images: Record<string, ImagePin> };
+export type BoxImage = { stack: string; ref: string; digest: string | null; pull: string; override?: true; approxMb?: number | null };
+
+/** Manifest files that pick a stack, checked in this order (first hit wins). */
+const MARKERS: Array<[string, string[]]> = [
+ ["go", ["go.mod", "go.work"]],
+ ["rust", ["Cargo.toml"]],
+ ["java", ["pom.xml", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "gradlew", "mvnw"]],
+ ["ruby", ["Gemfile", ".ruby-version"]],
+];
+
+export function loadPins(): ImagePins {
+ return bundledPins;
+}
+
+/** The stack of a project folder from its top-level manifests (else `base`). */
+export function detectStack(root: string, { exists = existsSync }: { exists?: (file: string) => boolean } = {}): string {
+ for (const [stack, files] of MARKERS) {
+ if (files.some((name) => exists(path.join(root, name)))) return stack;
+ }
+ return "base";
+}
+
+/**
+ * The image a new box starts on: { stack, ref, digest, pull } where `pull`
+ * is what to pull/run (ref@digest when pinned).
+ */
+export function imageFor(stack: string, { env = process.env, pins = loadPins() }: { env?: NodeJS.ProcessEnv; pins?: ImagePins } = {}): BoxImage {
+ const name = STACKS.includes(stack) ? stack : "base";
+ const override = String(env[`OMNIRUSH_BOX_IMAGE_${name.toUpperCase()}`] || env.OMNIRUSH_BOX_IMAGE || "").trim();
+ if (override) {
+ const at = override.indexOf("@sha256:");
+ return { stack: name, ref: at > 0 ? override.slice(0, at) : override, digest: at > 0 ? override.slice(at + 1) : null, pull: override, override: true };
+ }
+ const pin = pins.images[name] ?? pins.images.base!;
+ const digest = typeof pin.digest === "string" && /^sha256:[0-9a-f]{64}$/.test(pin.digest) ? pin.digest : null;
+ return { stack: name, ref: pin.ref, digest, pull: digest ? `${pin.ref.replace(/:[^/:]+$/, "")}@${digest}` : pin.ref, approxMb: pin.approx_mb ?? null };
+}
diff --git a/apps/server/src/box/launch.ts b/apps/server/src/box/launch.ts
new file mode 100644
index 00000000..c2918dbc
--- /dev/null
+++ b/apps/server/src/box/launch.ts
@@ -0,0 +1,286 @@
+// 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).
+//
+// 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
+// trace label.
+//
+// Never blocking: the runtime probe and the image check are bounded; a
+// missing image starts a download in the background and the project runs on
+// this machine meanwhile (one line says so); the box itself starts in the
+// 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 path from "node:path";
+
+import { boxKey, containerName, inspectImage, installShell, openBox, recordFile, savedTurns, type Box, type BoxLabel, type BoxLog, type BoxRuntime, type CheckpointSummary } from "./box.js";
+import { detectStack, imageFor, type BoxImage } from "./images.js";
+import { detectRuntime, runCommand, type RunCommand, type RuntimeResult } from "./runtime.js";
+
+export const MODES = ["off", "offer", "on"] as const;
+export type ServerBoxDefault = (typeof MODES)[number];
+/** A project's own choice: "on", "off", or none (the server's default). */
+export type ProjectBoxMode = "on" | "off" | null;
+
+function isMode(value: unknown): value is ServerBoxDefault {
+ return MODES.some((mode) => mode === value);
+}
+
+// --- the server's default -----------------------------------------------------------
+
+/** The server's switch as last seen (GET /collect/capabilities -> local_box.default). */
+export function serverDefault(stateDir: string): ServerBoxDefault {
+ try {
+ const value = JSON.parse(readFileSync(path.join(stateDir, "box-server.json"), "utf8"));
+ return isMode(value?.default) ? value.default : "off";
+ } catch {
+ return "off";
+ }
+}
+
+/** Remembers local_box.default of a capabilities answer; whether it 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 value = isMode(fields.default) ? fields.default : "off";
+ const before = serverDefault(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 });
+ } catch { /* best effort */ }
+ return before !== value;
+}
+
+/**
+ * On or off for a project, and why: OMNIRUSH_BOX=1|0 (every project), then
+ * the project's setting, then the server's default ("on"; "offer" shows a
+ * one-line offer until the project was offered it once; "off").
+ */
+export function resolveMode({ env = process.env, project, server, offered = false }: { env?: NodeJS.ProcessEnv; project: ProjectBoxMode; server: ServerBoxDefault; offered?: boolean }): { on: boolean; source: "env" | "project" | "server" | "default"; offer: boolean } {
+ const asked = String(env.OMNIRUSH_BOX ?? "").trim().toLowerCase();
+ if (["1", "on", "true"].includes(asked)) return { on: true, source: "env", offer: false };
+ if (["0", "off", "false"].includes(asked)) return { on: false, source: "env", offer: false };
+ if (project === "on" || project === "off") return { on: project === "on", source: "project", offer: false };
+ if (server === "on") return { on: true, source: "server", offer: false };
+ return { on: false, source: server === "offer" ? "server" : "default", offer: server === "offer" && !offered };
+}
+
+// --- background download ---------------------------------------------------------------
+
+function pullMarker(home: string, image: string): string {
+ return path.join(home, "pulls", `${image.replace(/[^a-zA-Z0-9._-]+/g, "_")}.pid`);
+}
+
+/** Whether a background download of `image` is running. */
+export function pulling(home: string, image: string): boolean {
+ try {
+ const pid = Number(readFileSync(pullMarker(home, image), "utf8"));
+ if (!pid) return false;
+ process.kill(pid, 0);
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/** 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);
+ 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, ["pull", image], { detached: true, stdio: "ignore", windowsHide: true });
+ child.unref?.();
+ try { writeFileSync(marker, String(child.pid ?? "")); } catch { /* best effort */ }
+ return { started: true, pid: child.pid };
+}
+
+// --- one project -----------------------------------------------------------------------
+
+export type ReadyPlan = {
+ box: { key: string; home: string; root: string; runtime: BoxRuntime };
+ notice: null;
+ shell: string;
+ /** Open the box (once); resolves the Box (state "ready" or "failed"). */
+ start: () => Promise<Box>;
+};
+export type NativePlan = { box: null; notice: string | null; runtime: RuntimeResult | null; image?: BoxImage; downloading?: boolean };
+export type BoxPlan = ReadyPlan | NativePlan;
+
+/**
+ * Plan the box of the project at `root` (the project's box is on). Returns
+ * { 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> {
+ 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" });
+ if (!runtime.ok) {
+ log("info", "box unavailable", { reason: runtime.reason });
+ return { box: null, notice: `Sandbox off for now: ${runtime.reason}.`, runtime };
+ }
+ let shell: string;
+ try {
+ shell = installShell(home, { env });
+ } catch (error) {
+ 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(run(runtime.bin, ["container", "inspect", containerName(key, env), "--format", "{{.Id}}"], { timeoutMs: probeMs }), probeMs, { code: -1, stdout: "", stderr: "" });
+ if (existing.code !== 0) {
+ const image = imageFor(detectStack(root), { env });
+ const present = await bounded(inspectImage(runtime, image.pull, { run }), 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 };
+ }
+ }
+ let opening: Promise<Box> | null = null;
+ return {
+ box: { key, home, root, runtime },
+ notice: null,
+ shell,
+ start: () => {
+ opening ??= openBox({ root, runtime, env, home, log, pull: false, shims });
+ return opening;
+ },
+ };
+}
+
+/** The package-manager wrappers' source folder (phase 1), mounted read-only when present. */
+export function shimsDir(env: NodeJS.ProcessEnv = process.env): string | null {
+ const asked = String(env.OMNIRUSH_BOX_SHIMS_DIR || "").trim();
+ if (asked) return existsSync(path.join(asked, "install.sh")) ? path.resolve(asked) : null;
+ return null;
+}
+
+/** Engine config additions for box runs: the shell and the plugin. */
+export function engineConfig(bits: { shell: string; plugin: string } | null, config: Record<string, unknown>): Record<string, unknown> {
+ if (!bits) return config;
+ const plugins = Array.isArray(config.plugin) ? config.plugin : [];
+ return {
+ ...config,
+ shell: bits.shell,
+ plugin: [...plugins, bits.plugin],
+ };
+}
+
+/** Turn the record off (the project went on without the box). */
+export function recordOff(home: string, key: string, reason: string): void {
+ try {
+ const file = recordFile(home, key);
+ const rec = JSON.parse(readFileSync(file, "utf8"));
+ writeFileSync(file, JSON.stringify({ ...rec, state: "off", error: reason, updated: Date.now() }), { mode: 0o600 });
+ } catch { /* none */ }
+}
+
+// --- the box during a run ------------------------------------------------------------
+
+export type Frozen = {
+ label: string;
+ turn: number | null;
+ copied: number;
+ carried: number;
+ save: (outDir?: string) => Promise<{ label: string; changed: number; bytes: number }>;
+ discard: () => Promise<null>;
+};
+
+export type BoxRun = {
+ key: string;
+ container: string;
+ runtimeBin: string;
+ root: string;
+ readonly native: boolean;
+ readonly box: Box | null;
+ ready: () => Promise<Box | null>;
+ /** environment.sandbox for a chat's uploads; null while it is not (or no longer) the chat's. */
+ label: (sessionId: string) => BoxLabel | null;
+ setTurn: (turn: number) => void;
+ freeze: (label: string, options: { sessionId: string; turn?: number | null; chain?: string | null }) => Promise<Frozen | null>;
+};
+
+/**
+ * What the capture wiring drives for one project's box: readiness, the
+ * per-turn freeze, the label uploads carry (the toolchain probes run from
+ * the capture worker: capture.ts). A box that
+ * fails before any chat's first checkpoint turns the project native (record
+ * "off"; the shell runs on this machine, its chats are not labelled); later
+ * failures are logged and that turn has no checkpoint.
+ */
+export function boxRun(plan: ReadyPlan, { log = () => {}, readyWaitMs = 30_000, onNative = () => {}, tmpRoot }: { log?: BoxLog; readyWaitMs?: number; onNative?: (reason: string) => void; tmpRoot?: string } = {}): BoxRun {
+ const { key, home, runtime, root } = plan.box;
+ let box: Box | null = null;
+ let native = false;
+ const checkpoints = new Map<string, number>();
+ const opening = plan.start().then((opened) => { box = opened; return opened; });
+ const goNative = (reason: string) => {
+ if (native) return;
+ native = true;
+ recordOff(home, key, reason);
+ log("warn", "box off for this project", { reason });
+ onNative(reason);
+ };
+ const ready = async (): Promise<Box | null> => {
+ if (native) return null;
+ const opened = await Promise.race([opening, new Promise<null>((resolve) => setTimeout(() => resolve(null), readyWaitMs))]);
+ if (opened?.ready) return opened;
+ if ([...checkpoints.values()].every((count) => count === 0)) goNative(opened?.error || "the sandbox did not start in time");
+ return null;
+ };
+ const pending = tmpRoot ?? path.join(home, "pending");
+ return {
+ key,
+ container: containerName(key),
+ runtimeBin: runtime.bin,
+ root,
+ get native() { return native; },
+ get box() { return box; },
+ ready,
+ label: (sessionId) => (box?.ready && !native && (checkpoints.get(sessionId) ?? 0) > 0 ? box.label() : null),
+ setTurn: (turn) => box?.setTurn(turn),
+ /**
+ * The old sandbox's freeze(label, { turn, chain }) -> { save(dir), discard() } | null:
+ * the checkpoint is taken now and placed by save(); `final` (the state a
+ * chat ends with) is a leaf, so a resumed chat chains on from its last turn.
+ */
+ freeze: async (label, { sessionId, turn = null, chain = null }) => {
+ const opened = await ready();
+ if (!opened) return null;
+ const n = Number(turn ?? /^turn-(\d+)$/.exec(label)?.[1] ?? 0) || null;
+ const name = n ? `turn-${n}` : label;
+ const dir = chain ?? path.join(pending, `${process.pid}-${Date.now()}`);
+ const taken = await opened.checkpoint(dir, n, { label: name, leaf: !n });
+ checkpoints.set(sessionId, (checkpoints.get(sessionId) ?? 0) + 1);
+ const summary: CheckpointSummary = taken.summary;
+ return {
+ label: name,
+ turn: n,
+ copied: summary.stats.copied,
+ carried: Math.max(0, summary.stats.kept - summary.stats.copied),
+ save: async (outDir) => {
+ taken.commit(outDir ?? dir);
+ return { label: name, changed: summary.delta.changed.length, bytes: summary.bytes };
+ },
+ discard: async () => { taken.discard(); return null; },
+ };
+ },
+ };
+}
+
+/** A host path under the project, as the box sees it. */
+export function mapToBox(p: string, root: string, croot: string): string {
+ if (root === croot) return p;
+ const rel = path.relative(root, p);
+ if (rel.startsWith("..") || path.isAbsolute(rel)) return croot;
+ return rel ? `${croot}/${rel.split(path.sep).join("/")}` : croot;
+}
+
+export { savedTurns };
diff --git a/apps/server/src/box/plugin-lib.ts b/apps/server/src/box/plugin-lib.ts
new file mode 100644
index 00000000..674157be
--- /dev/null
+++ b/apps/server/src/box/plugin-lib.ts
@@ -0,0 +1,78 @@
+// Ported from the CLI (omnirush-cli src/box/plugin-lib.js, feat/local-box);
+// keep the two in step. Desktop: types, and desktopProjects() (below).
+//
+// Helpers of the box engine plugin (opencode-plugins/omnirush-box.ts), apart
+// because the engine calls every function a plugin module exports.
+import { readFileSync, realpathSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { createHash } from "node:crypto";
+
+export const FILE_TOOLS = new Set(["read", "write", "edit", "glob", "grep", "list", "ls", "apply_patch", "patch", "multiedit"]);
+
+export function boxHome(): string {
+ return path.resolve(String(process.env.OMNIRUSH_BOX_HOME || "").trim() || path.join(os.homedir(), ".omnirush", "box"));
+}
+
+export function keyOf(dir: string): string {
+ let resolved = path.resolve(dir);
+ try { resolved = realpathSync.native(resolved); } catch { /* keep */ }
+ if (process.platform === "win32") resolved = resolved.toLowerCase();
+ return createHash("sha256").update(resolved).digest("hex").slice(0, 12);
+}
+
+export function record(key: string): { state?: string; uid?: number } | null {
+ try { return JSON.parse(readFileSync(path.join(boxHome(), "boxes", `${key}.json`), "utf8")); } catch { return null; }
+}
+
+/**
+ * Desktop: the projects whose box the desktop's engine uses
+ * (<box home>/desktop-projects.json, written by the desktop server). The CLI
+ * shares the box home and its records; a project's record alone (left by a
+ * CLI run) never turns the box on for a desktop chat.
+ */
+export const DESKTOP_PROJECTS_FILE = "desktop-projects.json";
+
+export function desktopProjects(): Set<string> {
+ try {
+ const value = JSON.parse(readFileSync(path.join(boxHome(), DESKTOP_PROJECTS_FILE), "utf8"));
+ return new Set(Array.isArray(value?.keys) ? value.keys.filter((key: unknown): key is string => typeof key === "string") : []);
+ } catch {
+ return new Set();
+ }
+}
+
+export function within(child: string, parent: string): boolean {
+ const a = process.platform === "win32" ? child.toLowerCase() : child;
+ const b = process.platform === "win32" ? parent.toLowerCase() : parent;
+ return a === b || a.startsWith(b.endsWith(path.sep) ? b : b + path.sep);
+}
+
+/** The engine's own folders (config, data incl. truncated tool output, cache, state). */
+export function engineDirs(): string[] {
+ const home = os.homedir();
+ const xdg = (name: string, fallback: string[]) => path.join(process.env[name] || path.join(home, ...fallback), "omnirush");
+ return [
+ xdg("XDG_CONFIG_HOME", [".config"]), xdg("XDG_DATA_HOME", [".local", "share"]),
+ xdg("XDG_CACHE_HOME", [".cache"]), xdg("XDG_STATE_HOME", [".local", "state"]),
+ ];
+}
+
+function patchPaths(text: unknown): string[] {
+ const out: string[] = [];
+ for (const match of String(text || "").matchAll(/^\*\*\* (?:Add|Update|Delete) File: (.+)$|^\*\*\* Move to: (.+)$/gm)) out.push((match[1] || match[2] || "").trim());
+ return out;
+}
+
+export function toolPaths(tool: string, args: Record<string, unknown> = {}): string[] {
+ if (tool === "apply_patch" || tool === "patch") return patchPaths(args.patchText ?? args.patch);
+ if (tool === "multiedit") return [args.filePath].filter((value): value is string => typeof value === "string" && Boolean(value));
+ return [args.filePath, args.path, args.file_path].filter((value): value is string => typeof value === "string" && Boolean(value));
+}
+
+export const BOX_NOTE = (root: string, uid = 0): string => [
+ `Sandbox: shell commands run in a Linux (Debian) container, ${uid === 0 ? "as root" : "as a user with passwordless sudo"}, with HOME=/root.`,
+ `The project folder ${root} is the same folder inside the container (same path); changes to it are visible on both sides.`,
+ "Files outside the project folder (/tmp, HOME, system folders) exist only inside the container: read and change them with shell commands, not with the file tools.",
+ "Install what the task needs with the usual package managers (apt-get, pip, npm, cargo, go, ...); installs persist in this project's container across sessions.",
+].join("\n");
diff --git a/apps/server/src/box/runtime.ts b/apps/server/src/box/runtime.ts
new file mode 100644
index 00000000..237086f3
--- /dev/null
+++ b/apps/server/src/box/runtime.ts
@@ -0,0 +1,310 @@
+// Ported from the CLI (omnirush-cli src/box/runtime.js, feat/local-box);
+// 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
+// probe has a short time limit, its result is cached, and "none" means the
+// session runs on this machine with one line saying why.
+//
+// The old sandbox (CLI 2.2.3 to 2.3.6) failed users here: Docker Desktop's
+// ~/.docker/bin not on PATH, a Windows docker.exe reached from WSL through
+// /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 os from "node:os";
+import path from "node:path";
+
+/** 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>;
+
+export type RuntimeCandidate = { name: string; bin: string; skipped?: string };
+export type RuntimeInfo = {
+ ok: true;
+ name: string;
+ bin: string;
+ version: string;
+ os: string;
+ arch: string;
+ rootless: boolean;
+ flavor: string;
+ vm: boolean;
+ cached?: boolean;
+};
+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). */
+export function isWsl(env: Env = process.env, release = os.release()): boolean {
+ return Boolean(env.WSL_DISTRO_NAME || env.WSL_INTEROP) || /microsoft/i.test(release);
+}
+
+/** Folders a runtime's CLI is installed in beyond PATH, per platform. */
+export function searchDirs({ platform = process.platform, home = os.homedir(), env = process.env }: { platform?: NodeJS.Platform; home?: string; env?: Env } = {}): string[] {
+ if (platform === "darwin") {
+ return [
+ "/usr/local/bin", "/opt/homebrew/bin", path.posix.join(home, ".docker", "bin"),
+ "/Applications/Docker.app/Contents/Resources/bin", path.posix.join(home, ".orbstack", "bin"),
+ path.posix.join(home, ".rd", "bin"), "/opt/podman/bin", "/opt/local/bin",
+ ];
+ }
+ if (platform === "win32") {
+ const pf = env.ProgramFiles || "C:\\Program Files";
+ const local = env.LOCALAPPDATA || path.win32.join(home, "AppData", "Local");
+ return [
+ path.win32.join(pf, "Docker", "Docker", "resources", "bin"),
+ path.win32.join(pf, "RedHat", "Podman"),
+ path.win32.join(local, "Programs", "Rancher Desktop", "resources", "resources", "win32", "bin"),
+ path.win32.join(pf, "Rancher Desktop", "resources", "resources", "win32", "bin"),
+ ];
+ }
+ return ["/usr/bin", "/usr/local/bin", "/snap/bin", path.posix.join(home, ".local", "bin"), path.posix.join(home, "bin"), path.posix.join(home, ".docker", "bin")];
+}
+
+/** A Windows binary seen from WSL (/mnt/c/...): it cannot mount this Linux's folders. */
+export function windowsBinaryInWsl(file: string): boolean {
+ return /^\/mnt\/[a-z](\/|$)/i.test(String(file));
+}
+
+/**
+ * Runtime CLIs to try, best first: OMNIRUSH_BOX_RUNTIME (docker, podman or a
+ * path) alone when set; else on Linux Podman then Docker (rootless Podman
+ * keeps files owned by the user with no daemon), on macOS and Windows Docker
+ * then Podman (Docker Desktop, OrbStack, colima, Rancher all speak docker).
+ */
+export function candidates({ platform = process.platform, home = os.homedir(), env = process.env, exists = existsSync, wsl = platform === "linux" && isWsl(env) }: { platform?: NodeJS.Platform; home?: string; env?: Env; exists?: (file: string) => boolean; wsl?: boolean } = {}): RuntimeCandidate[] {
+ const ext = platform === "win32" ? ".exe" : "";
+ const sep = platform === "win32" ? ";" : ":";
+ const join = platform === "win32" ? path.win32.join : path.posix.join;
+ const pathDirs = String(env.PATH || env.Path || "").split(sep).filter(Boolean);
+ const dirs = [...pathDirs, ...searchDirs({ platform, home, env })];
+ const asked = String(env.OMNIRUSH_BOX_RUNTIME || "").trim();
+ const out: RuntimeCandidate[] = [];
+ const seen = new Set<string>();
+ const add = (name: string, file: string, skipped?: string) => {
+ if (seen.has(file)) return;
+ seen.add(file);
+ out.push({ name, bin: file, ...(skipped ? { skipped } : {}) });
+ };
+ if (asked && /[\\/]/.test(asked)) {
+ add(/podman/i.test(path.basename(asked)) ? "podman" : "docker", asked);
+ return out;
+ }
+ const names = asked ? [asked] : platform === "linux" ? ["podman", "docker"] : ["docker", "podman"];
+ for (const name of names) {
+ for (const dir of dirs) {
+ const file = join(dir, name + ext);
+ if (!exists(file)) continue;
+ if (wsl && windowsBinaryInWsl(file)) {
+ add(name, file, "a Windows program seen from WSL; install Docker in WSL or turn on Docker Desktop's WSL integration");
+ continue;
+ }
+ add(name, file);
+ }
+ }
+ 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) ?? "";
+}
+
+/** A user-facing reason for a failed probe, from what the runtime printed. */
+export function explainFailure(name: string, result: Partial<RunResult>, { platform = process.platform }: { platform?: NodeJS.Platform } = {}): string {
+ const said = firstLine(result.stderr) || firstLine(result.stdout);
+ if (result.error === "ENOENT") return `${name} is not installed`;
+ if (result.error === "timeout") return `${name} did not answer in time (is it starting?)`;
+ if (/permission denied/i.test(said) && /docker\.sock|docker daemon socket/i.test(said)) {
+ return "Docker refused this user (add it to the docker group: `sudo usermod -aG docker $USER`, then log in again), or use rootless Podman";
+ }
+ if (/cannot connect to the docker daemon|is the docker daemon running|error during connect|docker_engine/i.test(said)) {
+ return platform === "linux" ? "the Docker daemon is not running" : "Docker is installed but not running (start Docker Desktop, OrbStack or colima)";
+ }
+ if (/podman machine|cannot connect to podman|unable to connect to podman/i.test(said)) return "Podman is installed but its machine is not running (`podman machine start`)";
+ if (said) return `${name}: ${said.slice(0, 200)}`;
+ return `${name} exited with ${result.code}`;
+}
+
+type Info = Record<string, unknown> & {
+ OperatingSystem?: unknown;
+ Name?: unknown;
+ host?: { distribution?: { distribution?: unknown }; os?: unknown; arch?: unknown; security?: { rootless?: unknown } };
+ version?: { Version?: unknown };
+ OSType?: unknown;
+ ServerErrors?: unknown;
+ SecurityOptions?: unknown;
+ ServerVersion?: unknown;
+ Architecture?: unknown;
+};
+
+/** What kind of installation answered (shown in status; recorded in uploads). */
+export function flavorOf({ name, info = {}, platform = process.platform, wsl = false }: { name: string; info?: Info; platform?: NodeJS.Platform; wsl?: boolean }): string {
+ const system = String(info.OperatingSystem || info.host?.distribution?.distribution || "");
+ const host = String(info.Name || "");
+ if (/docker desktop/i.test(system)) return "desktop";
+ if (/orbstack/i.test(system) || /orbstack/i.test(host)) return "orbstack";
+ if (/colima/i.test(host) || /colima/i.test(system)) return "colima";
+ if (/rancher/i.test(system)) return "rancher";
+ if (name === "podman" && platform !== "linux") return "podman-machine";
+ if (wsl) return "wsl";
+ return "engine";
+}
+
+/**
+ * Probe one runtime CLI: { ok: true, name, bin, version, os, arch, flavor,
+ * rootless, vm } or { ok: false, name, bin, reason }.
+ */
+export async function probe(candidate: RuntimeCandidate, { run = runCommand, env = process.env, platform = process.platform, wsl = platform === "linux" && isWsl(env), timeoutMs = 8_000 }: { run?: RunCommand; env?: Env; platform?: NodeJS.Platform; wsl?: boolean; timeoutMs?: number } = {}): Promise<RuntimeResult> {
+ const { name, bin } = candidate;
+ if (candidate.skipped) return { ok: false, name, bin, reason: `${bin}: ${candidate.skipped}` };
+ if (name === "docker") {
+ const host = String(env.DOCKER_HOST || "");
+ if (/^(ssh|tcp|https?):\/\//i.test(host) && env.OMNIRUSH_BOX_ALLOW_REMOTE !== "1") {
+ 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 result = await run(bin, args, { env, timeoutMs });
+ if (result.code !== 0) return { ok: false, name, bin, reason: explainFailure(name, result, { platform }) };
+ let info: Info;
+ try {
+ info = JSON.parse(result.stdout);
+ } catch {
+ return { ok: false, name, bin, reason: `could not read \`${name} info\`` };
+ }
+ if (name === "podman") {
+ const hostInfo = info.host ?? {};
+ return {
+ ok: true, name, bin,
+ version: String(info.version?.Version ?? ""),
+ os: String(hostInfo.os ?? "linux"),
+ arch: String(hostInfo.arch ?? ""),
+ rootless: Boolean(hostInfo.security?.rootless),
+ flavor: flavorOf({ name, info, platform, wsl }),
+ vm: platform !== "linux",
+ };
+ }
+ const osType = String(info.OSType ?? "linux");
+ if (osType !== "linux") return { ok: false, name, bin, reason: `Docker is set to ${osType} containers; switch it to Linux containers` };
+ if (Array.isArray(info.ServerErrors) && info.ServerErrors.length) return { ok: false, name, bin, reason: explainFailure(name, { code: 1, stderr: String(info.ServerErrors[0]) }, { platform }) };
+ const security = Array.isArray(info.SecurityOptions) ? info.SecurityOptions.join(",") : "";
+ const flavor = flavorOf({ name, info, platform, wsl });
+ return {
+ ok: true, name, bin,
+ version: String(info.ServerVersion ?? ""),
+ os: osType,
+ arch: String(info.Architecture ?? ""),
+ rootless: /rootless/.test(security),
+ flavor,
+ // Docker Desktop, OrbStack, colima: files cross into a VM; ownership is mapped there.
+ vm: platform !== "linux" || flavor === "desktop",
+ };
+}
+
+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.
+ */
+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);
+ }
+ 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;
+}
diff --git a/apps/server/src/box/service.ts b/apps/server/src/box/service.ts
new file mode 100644
index 00000000..040fa267
--- /dev/null
+++ b/apps/server/src/box/service.ts
@@ -0,0 +1,372 @@
+/**
+ * The desktop's Linux sandbox ("box", ported from the CLI: see launch.ts):
+ * one per server, for every local workspace whose box is on. It keeps
+ *
+ * - the per-workspace choice in the workspace's OmniRush settings
+ * (`localBox: { mode: "on" | "off", offered }`; no mode: the server's
+ * default from /collect/capabilities -> local_box.default);
+ * - the engine bits (the shell, named bash, and the box plugin) that go
+ * into the one engine config when any workspace may use a box;
+ * - <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.
+ *
+ * Nothing here blocks opening a project: probes are bounded, a missing image
+ * downloads in the background, a box that cannot start leaves its project
+ * on this machine.
+ *
+ * Not to be confused with the OpenWork worker sandbox (`sandboxBackend`).
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { delimiter, dirname, join } from "node:path";
+
+import { boxHome, boxKey, boxSnapshotsDir, containerName, inspectImage, installShell, listBoxes, readRecord, resetBox, savedTurns, type BoxLabel, type BoxLog } from "./box.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 { DESKTOP_PROJECTS_FILE } from "./plugin-lib.js";
+import { detectRuntime, 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 = {
+ key: string;
+ root: string;
+ croot: string;
+ container: string;
+ runtimeBin: string;
+ /** environment.sandbox of the chat's uploads. */
+ label: BoxLabel;
+};
+
+export type BoxWorkspace = { id: string; path: string; directory?: string; workspaceType: string };
+
+export type BoxStatus = {
+ /** The project's own choice (null: the server's default). */
+ mode: ProjectBoxMode;
+ serverDefault: ServerBoxDefault;
+ /** Whether the project's chats should run in its box. */
+ on: boolean;
+ source: "env" | "project" | "server" | "default";
+ /** The server offers the box and this project was not offered it yet. */
+ 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;
+ 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). */
+ notice: string | null;
+ error: string | null;
+};
+
+export type BoxServiceOptions = {
+ /** The capture state dir: the server default is remembered here, snapshots go under sandbox/snapshots. */
+ stateDir: string;
+ readSettings: (workspaceId: string) => Promise<{ mode: ProjectBoxMode; offered: boolean }>;
+ writeSettings: (workspaceId: string, update: { mode?: ProjectBoxMode; offered?: boolean }) => Promise<void>;
+ workspaces: () => BoxWorkspace[];
+ /** The engine plugin file (opencode-plugins/omnirush-box). */
+ pluginPath: () => string;
+ log?: BoxLog;
+ env?: NodeJS.ProcessEnv;
+};
+
+type Project = { run: BoxRun | null; notice: string | null; planning: Promise<BoxRun | null> | null; nextPlanAt: number };
+
+/** A project whose image is downloading is planned again at most this often. */
+const REPLAN_MS = 15_000;
+/** A prompt waits at most this long for its turn's checkpoint. */
+const FREEZE_WAIT_MS = 90_000;
+
+export function boxRoot(workspace: BoxWorkspace): string {
+ return workspace.directory?.trim() || workspace.path;
+}
+
+/** The shell boxsh runs when a call is not for a box (Windows: Git for Windows' bash when it is there). */
+export function nativeShell(env: NodeJS.ProcessEnv = process.env, platform: NodeJS.Platform = process.platform): string | null {
+ if (platform !== "win32") return null;
+ for (const dir of String(env.PATH || env.Path || "").split(delimiter)) {
+ if (!dir || !existsSync(join(dir, "git.exe"))) continue;
+ const bash = join(dirname(dirname(dir)), "bin", "bash.exe");
+ if (existsSync(bash)) return bash;
+ }
+ return null;
+}
+
+export class BoxService {
+ private readonly projects = new Map<string, Project>();
+ private readonly turns = new Map<string, number>();
+ private readonly home: string;
+ private readonly env: NodeJS.ProcessEnv;
+ private log: BoxLog;
+ private projectsWrite: Promise<void> = Promise.resolve();
+
+ constructor(private readonly options: BoxServiceOptions) {
+ this.env = options.env ?? process.env;
+ this.home = boxHome(this.env);
+ this.log = options.log ?? (() => {});
+ }
+
+ /** Logs go here from now on (the server's logger, once it exists). */
+ useLog(log: BoxLog): void {
+ this.log = log;
+ }
+
+ get snapshotsDir(): string {
+ return boxSnapshotsDir(this.options.stateDir);
+ }
+
+ serverDefault(): ServerBoxDefault {
+ return serverDefault(this.options.stateDir);
+ }
+
+ private async mode(workspace: BoxWorkspace) {
+ const settings = await this.options.readSettings(workspace.id).catch(() => ({ mode: null, offered: false }));
+ const server = this.serverDefault();
+ return { settings, server, ...resolveMode({ env: this.env, project: settings.mode, server, offered: settings.offered }) };
+ }
+
+ /**
+ * The engine config additions (`shell` and the plugin), or null: only when
+ * some local workspace has its box on or the server's default is on or
+ * offer, and the helpers for this machine are installed.
+ */
+ async engineBits(): Promise<{ shell: string; plugin: string } | null> {
+ let wanted = this.serverDefault() !== "off" || ["1", "on", "true"].includes(String(this.env.OMNIRUSH_BOX ?? "").trim().toLowerCase());
+ for (const workspace of this.options.workspaces()) {
+ if (wanted) break;
+ if (workspace.workspaceType !== "local") continue;
+ wanted = (await this.mode(workspace)).on;
+ }
+ if (!wanted) return null;
+ try {
+ return { shell: installShell(this.home, { env: this.env }), plugin: this.options.pluginPath() };
+ } catch (error) {
+ this.log("info", "box engine bits unavailable", { error: error instanceof Error ? error.message : String(error) });
+ return null;
+ }
+ }
+
+ /**
+ * The project's run when its box is on and can start (planned once, in
+ * the background; a downloading image is looked at again later), else null.
+ */
+ ensure(workspace: BoxWorkspace): Promise<BoxRun | null> {
+ if (workspace.workspaceType !== "local") return Promise.resolve(null);
+ const root = boxRoot(workspace);
+ const key = boxKey(root);
+ const project = this.projects.get(key) ?? { run: null, notice: null, planning: null, nextPlanAt: 0 };
+ this.projects.set(key, project);
+ if (project.planning) return project.planning;
+ project.planning = (async () => {
+ const { on } = await this.mode(workspace);
+ if (!on) {
+ project.run = null;
+ project.notice = null;
+ await this.writeProjects();
+ return null;
+ }
+ 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) });
+ if (!plan.box) {
+ project.run = null;
+ project.notice = plan.notice;
+ project.nextPlanAt = Date.now() + REPLAN_MS;
+ await this.writeProjects();
+ return null;
+ }
+ project.notice = null;
+ project.run = boxRun(plan, {
+ log: this.log,
+ tmpRoot: join(this.home, "pending"),
+ onNative: (reason) => {
+ project.notice = `Sandbox off for now: ${reason}.`;
+ project.nextPlanAt = Date.now() + REPLAN_MS;
+ void this.writeProjects();
+ },
+ });
+ await this.writeProjects();
+ return project.run;
+ })().finally(() => {
+ project.planning = null;
+ });
+ return project.planning;
+ }
+
+ /** Plans every local workspace whose box is on (server start, a changed default); never throws. */
+ async ensureAll(): Promise<void> {
+ await Promise.allSettled(this.options.workspaces().map((workspace) => this.ensure(workspace)));
+ }
+
+ /** The projects the plugin routes to their box: on, planned, not gone native. */
+ private writeProjects(): Promise<void> {
+ const keys = [...this.projects.entries()].filter(([, project]) => project.run && !project.run.native).map(([key]) => key).sort();
+ const file = join(this.home, DESKTOP_PROJECTS_FILE);
+ const write = async () => {
+ const content = `${JSON.stringify({ keys, updated: Date.now() })}\n`;
+ await mkdir(this.home, { recursive: true });
+ const tmp = `${file}.${process.pid}.tmp`;
+ await writeFile(tmp, content, { mode: 0o600 });
+ await rename(tmp, file);
+ };
+ this.projectsWrite = this.projectsWrite.then(write, write).catch((error) => {
+ this.log("warn", "box projects file not written", { error: error instanceof Error ? error.message : String(error) });
+ });
+ return this.projectsWrite;
+ }
+
+ /** The keys the plugin reads now (tests). */
+ async listedProjects(): Promise<string[]> {
+ await this.projectsWrite;
+ try {
+ const value = JSON.parse(await readFile(join(this.home, DESKTOP_PROJECTS_FILE), "utf8"));
+ return Array.isArray(value?.keys) ? value.keys : [];
+ } catch {
+ return [];
+ }
+ }
+
+ async setMode(workspace: BoxWorkspace, mode: ProjectBoxMode): Promise<BoxStatus> {
+ await this.options.writeSettings(workspace.id, { mode, offered: true });
+ const project = this.projects.get(boxKey(boxRoot(workspace)));
+ if (project) project.nextPlanAt = 0;
+ // Planned in the background: a missing image starts downloading now.
+ void this.ensure(workspace).catch(() => null);
+ return this.status(workspace);
+ }
+
+ async status(workspace: BoxWorkspace, { fresh = false }: { fresh?: boolean } = {}): Promise<BoxStatus> {
+ const { settings, server, on, source, offer } = await this.mode(workspace);
+ const root = boxRoot(workspace);
+ 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 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)),
+ ]);
+ 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 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);
+ container = { name, exists: Boolean(mine), running: Boolean(mine?.running) };
+ }
+ const downloading = runtime.ok && pulling(this.home, image.pull);
+ const record = readRecord(this.home, key);
+ const run = project?.run ?? null;
+ const state: BoxStatus["state"] = !on ? "off"
+ : !runtime.ok ? "unavailable"
+ : run && !run.native ? (run.box?.ready ? "ready" : run.box?.state === "failed" ? "failed" : "starting")
+ : downloading || (!present && !container?.exists) ? "downloading"
+ : project?.notice ? "unavailable" : "starting";
+ return {
+ ...base,
+ state,
+ runtime: runtimeView,
+ image: { ref: image.pull, stack: image.stack, present, downloading },
+ container,
+ notice: on ? project?.notice ?? (runtime.ok ? null : `Sandbox off for now: ${runtime.reason}.`) : null,
+ error: run?.box?.error ?? (record?.state === "off" || record?.state === "failed" ? record.error || null : null),
+ };
+ }
+
+ /** Remove the project's container (installs gone); the next chat starts a fresh one. */
+ 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 project = this.projects.get(key);
+ if (project) {
+ project.run = null;
+ project.nextPlanAt = 0;
+ }
+ await this.writeProjects();
+ if (!runtime.ok) return { removed: false };
+ const result = await resetBox(runtime, root, { env: this.env, home: this.home });
+ void this.ensure(workspace).catch(() => null);
+ return { removed: result.removed };
+ }
+
+ /** 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 });
+ 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);
+ return true;
+ }
+
+ private snapshotDir(sessionId: string): string {
+ return join(this.snapshotsDir, sessionId);
+ }
+
+ /**
+ * A prompt of `sessionId` is about to reach the engine: the turn's
+ * checkpoint (what the box changed since the chat's previous one) is
+ * taken and saved where the project archive reads it, and the chat's box
+ * label returned for its uploads. Null when the chat runs natively. Never
+ * throws; waits at most FREEZE_WAIT_MS.
+ */
+ async beforePrompt(sessionId: string, workspace: BoxWorkspace, { capture = true }: { capture?: boolean } = {}): Promise<BoxCaptureInfo | null> {
+ if (!/^[A-Za-z0-9._:-]{8,128}$/.test(sessionId)) return null;
+ const run = await this.ensure(workspace).catch(() => null);
+ if (!run || run.native) return null;
+ if (!capture) return null;
+ const turn = (this.turns.get(sessionId) ?? savedTurns(this.snapshotDir(sessionId))) + 1;
+ const started = Date.now();
+ try {
+ const frozen = await Promise.race([
+ run.freeze(`turn-${turn}`, { sessionId, turn, chain: this.snapshotDir(sessionId) }),
+ new Promise<null>((resolve) => setTimeout(() => resolve(null), FREEZE_WAIT_MS)),
+ ]);
+ if (frozen) {
+ const saved = await frozen.save(this.snapshotDir(sessionId));
+ this.turns.set(sessionId, turn);
+ run.setTurn(turn);
+ this.log("info", "box checkpoint saved", { sessionId, turn, changed: saved.changed, bytes: saved.bytes, ms: Date.now() - started });
+ }
+ } catch (error) {
+ this.log("warn", "box checkpoint failed", { sessionId, turn, error: error instanceof Error ? error.message : String(error) });
+ }
+ 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, label };
+ }
+
+ /** Whether chats ran in a box during this run (they get a `final` checkpoint at quit). */
+ hasChats(): boolean {
+ return this.turns.size > 0;
+ }
+
+ /** At quit: every chat with checkpoints gets its `final` leaf (bounded); the sessions that got one. */
+ async finals({ budgetMs = 20_000 }: { budgetMs?: number } = {}): Promise<string[]> {
+ const done: string[] = [];
+ const work = (async () => {
+ for (const sessionId of this.turns.keys()) {
+ const run = [...this.projects.values()].map((project) => project.run).find((candidate) => candidate?.label(sessionId));
+ if (!run) continue;
+ try {
+ const frozen = await run.freeze("final", { sessionId, chain: this.snapshotDir(sessionId) });
+ if (frozen) {
+ await frozen.save(this.snapshotDir(sessionId));
+ done.push(sessionId);
+ }
+ } catch (error) {
+ this.log("warn", "box final checkpoint failed", { sessionId, error: error instanceof Error ? error.message : String(error) });
+ }
+ }
+ })();
+ await Promise.race([work, new Promise((resolve) => setTimeout(resolve, budgetMs).unref?.())]);
+ return done;
+ }
+}
diff --git a/apps/server/src/capture-client.ts b/apps/server/src/capture-client.ts
index 8746118b..47131dad 100644
--- a/apps/server/src/capture-client.ts
+++ b/apps/server/src/capture-client.ts
@@ -16,6 +16,7 @@ import { resolve } from "node:path";
import { START_GATE_MS } from "./session-archive/capture-v2.js";
import { LATE_WRITES_CAP_MS } from "./session-archive/late-writes.js";
import type { FilesUsedStatus } from "./session-archive/index.js";
+import type { BoxCaptureInfo } from "./box/service.js";
import { CaptureHost, type CaptureDiagnostics, type CaptureHostOptions, type EngineReplacement, type EngineTarget, type LateWritesGate, type PromptRecord } from "./capture-host.js";
import {
@@ -79,6 +80,8 @@ export type CaptureService = {
/** Whether the session uploader is tracking this session (started and not finished). */
hasSession(sessionId: string): boolean;
startSession(sessionId: string, workspaceId: string, root: string): void;
+ /** The chat's prompts run in its project's Linux sandbox (box/service.ts), or no longer (null); before startSession. */
+ boxSession(sessionId: string, box: BoxCaptureInfo | null): void;
recordTrace(sessionId: string, type: string, data?: unknown): void;
flushTrace(sessionId: string, finalTrace?: unknown): void;
finishSession(sessionId: string, finalTrace?: unknown): void;
@@ -193,6 +196,10 @@ class CaptureClient implements CaptureService {
this.send({ kind: "call", id: null, method: "startSession", args: [sessionId, workspaceId, root] });
}
+ boxSession(sessionId: string, box: BoxCaptureInfo | null): void {
+ this.send({ kind: "call", id: null, method: "boxSession", args: [sessionId, box] });
+ }
+
recordTrace(sessionId: string, type: string, data?: unknown): void {
this.send({ kind: "call", id: null, method: "recordTrace", args: data === undefined ? [sessionId, type] : [sessionId, type, data] });
}
diff --git a/apps/server/src/capture-host.ts b/apps/server/src/capture-host.ts
index 4e6b508f..974571c7 100644
--- a/apps/server/src/capture-host.ts
+++ b/apps/server/src/capture-host.ts
@@ -28,6 +28,10 @@ import type { CaptureStopOptions } from "./capture-protocol.js";
import { SessionArchiver, type FilesUsedStatus, type SessionArchiverOptions } from "./session-archive/index.js";
import { ProjectArchiveLifecycle, type ArchiveLifecycleLog, type LateWrites } from "./session-archive/lifecycle.js";
import { settleLateWriters, type SettleResult } from "./session-archive/late-writes.js";
+import { isAbsolute, relative, sep } from "node:path";
+import { boxSnapshotsDir } from "./box/box.js";
+import type { BoxCaptureInfo } from "./box/service.js";
+import { sandboxFilesUsed, type FilesUsedSandbox } from "./session-archive/files-used-sandbox.js";
import { SessionUploader, type RecoveredTurn, type TraceCapabilities, type UploadMetrics, type UploadRequestOptions, type UploadWebVisit } from "./session-uploader.js";
export type { EngineReplacement, EngineTarget } from "./session-upload-observer.js";
@@ -113,6 +117,11 @@ export type CaptureDiagnostics = {
cache: { roots: number; entries: number };
};
+function outsideRoot(root: string, path: string): boolean {
+ const rel = relative(root, path);
+ return rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel);
+}
+
function requestPayload(body: Uint8Array | null): unknown {
if (!body || body.byteLength > MAX_TRACED_REQUEST_BYTES) return undefined;
try {
@@ -135,9 +144,14 @@ export class CaptureHost {
private readonly promptAt = new Map<string, number>();
/** The latest prompt's wait for the turn before's background processes, when it found any ("turn.late"). */
private readonly lateSettles = new Map<string, SettleResult>();
+ /** Chats in a Linux sandbox: their files used outside the project are read in the container (one view per container). */
+ private readonly boxViews = new Map<string, FilesUsedSandbox>();
+ private readonly boxChats = new Map<string, string>();
+ private readonly log: CaptureLog;
constructor(options: CaptureHostOptions) {
this.engineTarget = options.engineTarget;
+ this.log = options.log;
this.sessionUploader = new SessionUploader({
...options.sessionUploader,
stateDir: options.stateDir,
@@ -155,7 +169,13 @@ export class CaptureHost {
...(options.installLog ? { installLog: options.installLog } : {}),
...(options.onSessionClosed ? { onSessionClosed: options.onSessionClosed } : {}),
// The touched-files archive hears of every path a session touches, here on the same thread.
- onPathTouched: (sessionId, path) => this.archive.pathTouched(sessionId, path),
+ onPathTouched: (sessionId, path) => {
+ // A chat in a box: a path outside the project names a file in the container, not on this
+ // machine; the box's turn checkpoints carry those.
+ const root = this.sessionRoots.get(sessionId);
+ if (root && this.sessionUploader.inBox(sessionId) && isAbsolute(path) && outsideRoot(root, path)) return;
+ this.archive.pathTouched(sessionId, path);
+ },
// Capture v2: a binary file is never sent as text; the project archive keeps it byte for byte.
onBinaryFile: (sessionId, path) => this.archive.binaryFile(sessionId, path),
});
@@ -165,6 +185,12 @@ export class CaptureHost {
archiver: new SessionArchiver({
stateDir: options.stateDir,
excludedDirs,
+ // The Linux sandbox's turn checkpoints (box/service.ts saves them there).
+ sandboxSnapshotsDir: boxSnapshotsDir(options.stateDir),
+ filesUsedSandbox: (sessionId) => {
+ const container = this.boxChats.get(sessionId);
+ return container ? this.boxViews.get(container) ?? null : null;
+ },
folderGate,
log: options.log,
...auth,
@@ -187,6 +213,20 @@ export class CaptureHost {
this.sessionUploader.startSession(sessionId, workspaceId, root);
}
+ /** The chat's prompts run in its project's box (or no longer: null); sent before its startSession. */
+ boxSession(sessionId: string, box: BoxCaptureInfo | null): void {
+ this.sessionUploader.setBox(sessionId, box);
+ if (!box) {
+ this.boxChats.delete(sessionId);
+ return;
+ }
+ 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, log: this.log });
+ if (view) this.boxViews.set(box.container, view);
+ }
+ }
+
recordTrace(sessionId: string, type: string, data?: unknown): void {
this.sessionUploader.recordTrace(sessionId, type, data);
}
diff --git a/apps/server/src/capture-protocol.ts b/apps/server/src/capture-protocol.ts
index 44cd9dd4..3b7c5524 100644
--- a/apps/server/src/capture-protocol.ts
+++ b/apps/server/src/capture-protocol.ts
@@ -8,6 +8,7 @@
* bodies travel as transferred buffers.
*/
import type { CaptureHost, EngineReplacement, EngineTarget, LateWritesGate, PromptRecord } from "./capture-host.js";
+import type { BoxCaptureInfo } from "./box/service.js";
import type { FolderGateOptions } from "./session-archive/detect.js";
import type { TraceCapabilities, UploadRequestOptions, UploadWebVisit } from "./session-uploader.js";
@@ -17,6 +18,7 @@ export type CaptureStopOptions = { archiveFinals: boolean };
/** CaptureHost methods callable from the main thread, with their arguments. */
export type CaptureCalls = {
startSession: [sessionId: string, workspaceId: string, root: string];
+ boxSession: [sessionId: string, box: BoxCaptureInfo | null];
recordTrace: [sessionId: string, type: string, data?: unknown];
flushTrace: [sessionId: string, finalTrace?: unknown];
finishSession: [sessionId: string, finalTrace?: unknown];
@@ -162,6 +164,8 @@ export function invokeCapture(host: CaptureHost, call: CaptureCall): unknown {
switch (call.method) {
case "startSession":
return host.startSession(...call.args);
+ case "boxSession":
+ return host.boxSession(...call.args);
case "recordTrace":
return host.recordTrace(...call.args);
case "flushTrace":
diff --git a/apps/server/src/cli.ts b/apps/server/src/cli.ts
index f0d25f5b..e3ac43ca 100644
--- a/apps/server/src/cli.ts
+++ b/apps/server/src/cli.ts
@@ -3,6 +3,8 @@
import { randomUUID } from "node:crypto";
import { managedDesktopPolicy } from "./managed-desktop-policy.js";
import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { setToolsRoot } from "./box/box.js";
import { parseCliArgs, printHelp, resolveServerConfig } from "./config.js";
import {
@@ -80,6 +82,8 @@ if (!config.opencodeBaseUrl && process.env.OMNIRUSH_MANAGE_OPENCODE === "1") {
// Server-managed config file: the engine re-reads it from disk on every
// instance rebuild, and keepOmniRushRuntimeConfigFileFresh synchronizes it
// on every runtime-DB write — so disposes always pick up current state.
+ // The Linux sandbox's helpers ship beside the engine (sidecars/box/); the config names its shell.
+ if (process.env.OMNIRUSH_OPENCODE_BIN?.trim()) setToolsRoot(dirname(process.env.OMNIRUSH_OPENCODE_BIN.trim()));
const { path: runtimeConfigPath } = await writeOmniRushRuntimeConfigFile(config);
keepOmniRushRuntimeConfigFileFresh(config);
const managedOpencodeCwd = process.env.OMNIRUSH_MANAGED_OPENCODE_CWD?.trim() || workspace.path;
diff --git a/apps/server/src/embedded.ts b/apps/server/src/embedded.ts
index f3c88155..8e0f231a 100644
--- a/apps/server/src/embedded.ts
+++ b/apps/server/src/embedded.ts
@@ -9,6 +9,8 @@ import { randomUUID } from "node:crypto";
import { stopTaskRecovery } from "./task-recovery.js";
import { managedDesktopPolicy } from "./managed-desktop-policy.js";
import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { setToolsRoot } from "./box/box.js";
import { resolveServerConfig, type CliArgs } from "./config.js";
import {
buildEngineAuthProbeHeader,
@@ -241,6 +243,9 @@ export async function startEmbeddedServer(options: EmbeddedServerOptions): Promi
// Server-managed config file: the engine re-reads it from disk on every
// instance rebuild, and keepOmniRushRuntimeConfigFileFresh synchronizes it
// on every runtime-DB write — so disposes always pick up current state.
+ // The Linux sandbox's helpers ship beside the engine (sidecars/box/); the config names its shell.
+ const engineBin = options.opencodeBin || process.env.OMNIRUSH_OPENCODE_BIN;
+ if (engineBin?.trim()) setToolsRoot(dirname(engineBin.trim()));
const { path: runtimeConfigPath } = await writeOmniRushRuntimeConfigFile(config);
stopRuntimeConfigFileRefresh = keepOmniRushRuntimeConfigFileFresh(config);
const cwd = options.opencodeCwd
@@ -249,7 +254,7 @@ export async function startEmbeddedServer(options: EmbeddedServerOptions): Promi
await duringStartup(() => mkdir(cwd, { recursive: true }));
const opencodeModelsEnv = await duringStartup(() => resolveOpencodeModelsEnv());
- const opencodeBin = options.opencodeBin || process.env.OMNIRUSH_OPENCODE_BIN;
+ const opencodeBin = engineBin;
// Shared by the first spawn and by any later rollover standby, so a
// replacement engine is identical apart from its port.
const engineEnv: Record<string, string | undefined> = {
diff --git a/apps/server/src/managed-policy-rules.ts b/apps/server/src/managed-policy-rules.ts
index 8563c8e7..726d89a5 100644
--- a/apps/server/src/managed-policy-rules.ts
+++ b/apps/server/src/managed-policy-rules.ts
@@ -157,7 +157,7 @@ export function policyRequestActions(method: string, path: string): ManagedPolic
if (path === "/omnirush/subagent-model") actions.push("settings");
if (/^\/workspace\/[^/]+\/(?:cloud-plugins|claude-plugins|plugins|skills|commands|mcp)(?:\/|$)/.test(path)
&& !/\/mcp\/[^/]+\/(?:auth|managed\/connect)$/.test(path)) actions.push("extensions");
- if (/^\/workspace\/[^/]+\/(?:config|opencode-config|runtime-config|permissions|authorized-folders)(?:\/|$)/.test(path)) actions.push("settings");
+ if (/^\/workspace\/[^/]+\/(?:config|opencode-config|runtime-config|permissions|authorized-folders|box)(?:\/|$)/.test(path)) actions.push("settings");
if (path === "/experimental/engine-v2-preview") actions.push("settings");
if (/\/opencode-config$/.test(path)) actions.push("engine_config");
return actions;
diff --git a/apps/server/src/omnirush-gateway-broker.ts b/apps/server/src/omnirush-gateway-broker.ts
index 0726af39..c871a8e0 100644
--- a/apps/server/src/omnirush-gateway-broker.ts
+++ b/apps/server/src/omnirush-gateway-broker.ts
@@ -1490,6 +1490,7 @@ export class OmniRushGatewayBroker {
...(triggers ? { triggers } : {}),
// The install log switch, passed on as the server said it (context/install-log.ts reads it).
...(installLog ? { install_log: { enabled: installLog.enabled === true, sample_percent: typeof installLog.sample_percent === "number" ? installLog.sample_percent : 100 } } : {}),
+ ...(isRecord(payload.local_box) ? { local_box: { default: String(payload.local_box.default ?? "off"), max_turn_bytes: typeof payload.local_box.max_turn_bytes === "number" ? payload.local_box.max_turn_bytes : null } } : {}),
};
} catch {
return none;
diff --git a/apps/server/src/omnirush-runtime-config.ts b/apps/server/src/omnirush-runtime-config.ts
index 4528ed2d..f953b6a0 100644
--- a/apps/server/src/omnirush-runtime-config.ts
+++ b/apps/server/src/omnirush-runtime-config.ts
@@ -53,6 +53,8 @@ import {
type OmniRushModelCatalog,
} from "./omnirush-model-catalog.js";
import { writeFileAtomic } from "./atomic-write.js";
+import { boxServiceFor } from "./box/desktop.js";
+import { engineConfig as withBoxEngineConfig } from "./box/launch.js";
import {
OMNIRUSH_BEST_PRACTICES,
bestPracticesEnabled,
@@ -131,7 +133,7 @@ export async function buildOmniRushRuntimeConfigObject(
// engine through the dynamic push path instead.
const runtimeConfig = config ? await readGlobalRuntimeOpencodeConfig(config) : {};
const internalGateway = resolveConfiguredInternalGatewayRuntime(config);
- return buildOmniRushRuntimeConfigObjectFromSnapshot(
+ const built = buildOmniRushRuntimeConfigObjectFromSnapshot(
runtimeConfig,
internalGateway,
process.env,
@@ -139,6 +141,10 @@ export async function buildOmniRushRuntimeConfigObject(
config ? omnirushRuntimeSkillsDir(config) : undefined,
config ? omnirushBestPracticesSkillsDir(config) : undefined,
);
+ // The Linux sandbox (box/): the engine's shell is the box shell and the box plugin is
+ // loaded once any workspace may use a box; every other project's commands run natively
+ // through the same shell. The same bytes whichever workspace is active.
+ return config ? withBoxEngineConfig(await boxServiceFor(config).engineBits(), built) : built;
}
/**
diff --git a/apps/server/src/opencode-plugins/omnirush-box.ts b/apps/server/src/opencode-plugins/omnirush-box.ts
new file mode 100644
index 00000000..5377a0d9
--- /dev/null
+++ b/apps/server/src/opencode-plugins/omnirush-box.ts
@@ -0,0 +1,64 @@
+// Ported from the CLI (omnirush-cli assets/opencode-box-plugin.js,
+// feat/local-box); keep the two in step. Desktop: a project's box is used
+// only when the desktop lists it (box/plugin-lib.ts desktopProjects()).
+//
+// Engine plugin for a project whose OmniRush box is on (box/). The engine
+// runs here, on this machine; its shell tool runs in the box (the engine's
+// shell is boxsh, which reads OMNIRUSH_BOX_KEY). This plugin:
+//
+// - gives each shell call the box key (one engine serves several projects)
+// and the call and session ids the package-manager wrappers write into
+// their lines;
+// - keeps the engine's file tools to the project folder and the engine's own
+// folders: everything else is the box's (its /tmp, its HOME), which the
+// file tools would read from this machine instead. The agent is told to
+// use the shell for those. This machine's files outside the project
+// (keys, tokens, other projects) stay out of the session either way;
+// - says in the system prompt that commands run on Linux in a container,
+// with the project folder at the same path.
+//
+// A project whose box is off (not listed, no record, or state "off") is left
+// alone. The engine calls every function this module exports: export only
+// the plugin.
+
+import path from "node:path";
+
+import { BOX_NOTE, desktopProjects, engineDirs, FILE_TOOLS, keyOf, record, toolPaths, within } from "../box/plugin-lib.js";
+
+export const OmniRushBox = async ({ directory }: { directory?: string }) => {
+ const root = path.resolve(directory || process.cwd());
+ const key = keyOf(root);
+ const current = () => {
+ if (!desktopProjects().has(key)) return null;
+ const rec = record(key);
+ return rec && rec.state !== "off" ? rec : null;
+ };
+ const active = () => Boolean(current());
+ const allowed = [root, ...engineDirs()];
+ return {
+ "shell.env": async (input: { callID?: string; sessionID?: string }, output: { env: Record<string, string> }) => {
+ if (!active()) return;
+ output.env.OMNIRUSH_BOX_KEY = key;
+ if (input.callID) output.env.OMNIRUSH_CALL = String(input.callID);
+ if (input.sessionID) output.env.OMNIRUSH_SESSION = String(input.sessionID);
+ },
+ "tool.execute.before": async (input: { tool: string }, output: { args?: Record<string, unknown> }) => {
+ if (!FILE_TOOLS.has(input.tool) || !active()) return;
+ for (const raw of toolPaths(input.tool, output.args ?? {})) {
+ const full = path.resolve(root, raw);
+ if (allowed.some((dir) => within(full, dir))) continue;
+ throw new Error(`${raw} is outside the project folder. This session runs in a sandbox: files outside ${root} live inside the Linux container, not where this tool can see them. Use the shell tool (cat, ls, sed, tee, ...) to read or change them.`);
+ }
+ },
+ "experimental.chat.system.transform": async (_input: unknown, output: { system?: unknown }) => {
+ const rec = current();
+ if (!rec || !Array.isArray(output.system)) return;
+ // In place: the engine keeps its own reference to this array.
+ for (let i = 0; i < output.system.length; i += 1) {
+ const line = output.system[i];
+ if (typeof line === "string") output.system[i] = line.replace(/^(\s*Platform:\s*)(darwin|win32|linux)\s*$/m, "$1linux");
+ }
+ output.system.push(BOX_NOTE(root, Number(rec.uid) || 0));
+ },
+ };
+};
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 7250eb9d..b4d44a3e 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -175,6 +175,8 @@ import {
seedOmniRushWorkspaceConfigIfEmpty,
writeOmniRushWorkspaceConfig,
} from "./omnirush-workspace-config-store.js";
+import { boxServiceFor } from "./box/desktop.js";
+import { rememberServerDefault } from "./box/launch.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";
@@ -1137,6 +1139,17 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
},
});
captureServicesByServer.set(config, capture);
+ // The Linux sandbox (box/): every workspace whose box is on is planned in the background (a missing
+ // image starts downloading), and the server's default (local_box) is read for the engine config.
+ const boxes = boxServiceFor(config, (level, message, attributes) => logger.log(level, message, attributes));
+ void boxes.ensureAll();
+ if (gatewayBroker.enabled) {
+ void gatewayBroker.sessionUploadCapabilities().then(async (capabilities) => {
+ if (!rememberServerDefault(runtimeStorageDir(config), capabilities)) return;
+ await applyBoxEngineConfig(config, "local_box_default");
+ await boxes.ensureAll();
+ }).catch(() => undefined);
+ }
if (config.clearUploadQueue) {
// The user signed out: what the last account queued is deleted before anything else runs.
await Promise.race([capture.signOut(), new Promise((resolvePromise) => setTimeout(resolvePromise, 10_000).unref?.())]);
@@ -1584,7 +1597,13 @@ export async function startServer(config: ServerConfig): Promise<ServeResult> {
// archive part uploads in flight are aborted before anything else runs.
// The project archive packs its final archives only while the account
// is still stored (an app quit, a restart), never after a sign-out.
- const captureStopped = capture.stop({ archiveFinals: accountStillStored() });
+ // Before them, each chat in a box gets its last checkpoint (bounded; only when chats ran in a
+ // box this run, and the account answers it is still stored within a second).
+ const archiveFinals = accountStillStored();
+ if (boxes.hasChats() && await Promise.race([archiveFinals.catch(() => false), new Promise<false>((resolvePromise) => setTimeout(() => resolvePromise(false), 1_000).unref?.())])) {
+ await boxes.finals({ budgetMs: 10_000 }).catch(() => []);
+ }
+ const captureStopped = capture.stop({ archiveFinals });
bestPracticesReloads.stop();
let recoveryError: unknown;
try { await taskRecovery?.stop(); } catch (error) { recoveryError = error; }
@@ -1779,10 +1798,15 @@ export async function proxyOpencodeV2Request(input: {
? sessionId
: null;
const engine = capture && uploadedSessionId ? engineTarget(input.connection.url, headers, target.search, "v2") : null;
+ // The Linux sandbox (box/): a prompt of a workspace whose box is on starts the box, and takes the turn's checkpoint when it is captured.
+ const boxInfo = promptDispatch && sessionId
+ ? await boxServiceFor(input.config).beforePrompt(sessionId, input.workspace, { capture: Boolean(uploadedSessionId && engine) })
+ : null;
if (capture && uploadedSessionId && engine) {
// The turn before's background processes finish writing (at most 10 s after it ended), then
// capture v2's session-start manifest is taken before the prompt reaches the engine (at most about 3 s).
await capture.archiveStartGate(uploadedSessionId, input.workspace.path, lateWritesGate(input.workspace));
+ capture.boxSession(uploadedSessionId, boxInfo);
capture.startSession(uploadedSessionId, input.workspace.id, input.workspace.path);
capture.recordPrompt(uploadedSessionId, { method, path: routePath, body: requestBody, engine: "v2", root: input.workspace.path, attachments: true, dispatchedAt: Date.now() });
capture.captureSnapshot(uploadedSessionId, "prompt");
@@ -2145,12 +2169,18 @@ export async function proxyOpencodeRequest(input: {
// A chat the engine does not have (a stale tab, a deleted chat) is not
// started: its prompt is refused, and it would only leave an empty start
// and end snapshot behind.
- if (capture?.uploadEnabled && uploadedSessionId && workspace && workspace.workspaceType !== "remote"
- && (capture.hasSession(uploadedSessionId) || await engineHasSession(baseUrl, auth, directory, uploadedSessionId))) {
+ const captured = Boolean(capture?.uploadEnabled && uploadedSessionId && workspace && workspace.workspaceType !== "remote"
+ && (capture.hasSession(uploadedSessionId) || await engineHasSession(baseUrl, auth, directory, uploadedSessionId)));
+ // The Linux sandbox (box/): a prompt of a workspace whose box is on starts the box, and takes the turn's checkpoint when it is captured.
+ const boxInfo = workspace && uploadedSessionId && isUploadPromptDispatch(method, proxyPath)
+ ? await boxServiceFor(input.config).beforePrompt(uploadedSessionId, workspace, { capture: captured })
+ : null;
+ if (capture && captured && uploadedSessionId && workspace) {
const promptDispatch = isUploadPromptDispatch(method, proxyPath);
// The turn before's background processes finish writing (at most 10 s after it ended), then
// capture v2's session-start manifest is taken before the prompt reaches the engine (at most about 3 s).
if (promptDispatch) await capture.archiveStartGate(uploadedSessionId, workspace.path, lateWritesGate(workspace, pool?.snapshot().generations.map((generation) => generation.pid) ?? []));
+ if (promptDispatch) capture.boxSession(uploadedSessionId, boxInfo);
capture.startSession(uploadedSessionId, workspace.id, workspace.path);
capture.recordPrompt(uploadedSessionId, {
method,
@@ -2712,6 +2742,26 @@ function sanitizeProxyResponse(response: Response): Response {
});
}
+/**
+ * The Linux sandbox's engine bits (box/service.ts engineBits) may have
+ * changed: the engine config file is written again and, when it changed,
+ * the managed engine rolls over to it (as for a best-practices change).
+ */
+async function applyBoxEngineConfig(config: ServerConfig, reason: string): Promise<{ status: "unchanged" | "applied" | "deferred" | "failed" | "unmanaged" }> {
+ try {
+ const written = await writeOmniRushRuntimeConfigFile(config);
+ if (!written.changed) return { status: "unchanged" };
+ const pool = enginePoolForConfig(config);
+ const workspaces = config.workspaces.filter((workspace) => resolveWorkspaceOpencodeConnection(config, workspace).baseUrl?.trim());
+ const workspace = findManagedEngineWorkspace(workspaces) ?? workspaces[0];
+ if (!pool || !workspace) return { status: "unmanaged" };
+ const outcome = await pool.requestRollover({ reason, workspace, manual: true });
+ return { status: outcome.action === "coalesced" ? "deferred" : outcome.action === "skipped" ? "failed" : "applied" };
+ } catch {
+ return { status: "failed" };
+ }
+}
+
function jsonResponse(data: unknown, status = 200) {
return new Response(JSON.stringify(data), {
status,
@@ -3712,6 +3762,35 @@ function createRoutes(
return jsonResponse({ ok: true, changed: result.changed, ...resolveApprovalMode(result.config) });
});
+ // The Linux sandbox (box/): a workspace's choice, its status, and its reset.
+ addRoute(routes, "GET", "/workspace/:id/box", "client", async (ctx) => {
+ const workspace = await resolveWorkspace(config, ctx.params.id);
+ return jsonResponse(await boxServiceFor(config).status(workspace, { fresh: ctx.url.searchParams.get("fresh") === "1" }));
+ });
+
+ addRoute(routes, "PUT", "/workspace/:id/box", "client", async (ctx) => {
+ ensureWritable(config);
+ requireClientScope(ctx, "collaborator");
+ 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");
+ }
+ if (workspace.workspaceType !== "local") throw new ApiError(400, "box_unsupported", "The sandbox is for folders on this computer");
+ const status = await boxServiceFor(config).setMode(workspace, mode);
+ // The engine gets the box shell and plugin when the first workspace turns its box on.
+ const engine = await applyBoxEngineConfig(config, "local_box");
+ return jsonResponse({ ...status, engine });
+ });
+
+ addRoute(routes, "POST", "/workspace/:id/box/reset", "client", async (ctx) => {
+ ensureWritable(config);
+ requireClientScope(ctx, "collaborator");
+ const workspace = await resolveWorkspace(config, ctx.params.id);
+ return jsonResponse(await boxServiceFor(config).reset(workspace));
+ });
+
// Files used (session-archive/files-used.ts): what omnirush.ai says, for the app's one-time notice of its line.
addRoute(routes, "GET", "/runtime-config/files-used", "client", async () => {
const status = await captureServicesByServer.get(config)?.filesUsedStatus().catch(() => null);
diff --git a/apps/server/src/session-archive/files-used-sandbox.ts b/apps/server/src/session-archive/files-used-sandbox.ts
new file mode 100644
index 00000000..85a7bf42
--- /dev/null
+++ b/apps/server/src/session-archive/files-used-sandbox.ts
@@ -0,0 +1,349 @@
+/**
+ * Files used in the Docker sandbox (CLI only): the files a sandboxed agent
+ * uses outside the project live in its container (its /tmp, its HOME,
+ * anything it made elsewhere or copied in with `omnirush-host`), not on this
+ * machine. A path there is read in the container, as the agent sees it,
+ * never from a file of this machine at the same path. Only the project
+ * folders the sandbox mounts at the same path are read on this machine.
+ *
+ * A small Python program (the sandbox image's /usr/bin/python3, isolated
+ * mode, as the container's user, one process for the run) answers each
+ * step, with every path of the step on one line of its stdin: real folder (the file itself never
+ * followed), type, size, SHA-256; the bytes of the files to keep; or the
+ * files changed during a call under the temp folders it named. When that
+ * fails (no Python in the image, the container gone, a timeout), every path
+ * of the step is `unreadable`: the tracker lists it as not captured and
+ * never guesses from this machine.
+ */
+import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
+
+/** A path as the container holds it. `unreadable`: the step could not ask the container. */
+export type ViewFacts =
+ | { canonical: string; kind: "missing" | "dir" | "other" | "unreadable" }
+ | { canonical: string; kind: "file"; size: number; sha256: string | null; mtimeMs: number };
+
+/** Where the tracker reads a path that is not on this machine (the sandbox's container). */
+export type FilesUsedView = {
+ /** Each path's real folder and what is there (hashing files of at most `hashBytes`). */
+ inspect(paths: readonly string[], hashBytes: number): Promise<Map<string, ViewFacts>>;
+ /** The bytes of each regular file of at most `maxBytes` (`too_large` past it; null: not there, not a file, unreadable). */
+ read(paths: readonly string[], maxBytes: number): Promise<Map<string, Buffer | "too_large" | null>>;
+ /** The regular files under these folders changed (mtime or ctime) within [low, high] ms (bounded walk). */
+ changed(dirs: readonly string[], low: number, high: number): Promise<string[]>;
+};
+
+/** The sandbox as the tracker sees it. */
+export type FilesUsedSandbox = {
+ /** HOME inside the sandbox: `~` and the home config the agent reads are the container's. */
+ home: string;
+ /** The user's home on this machine: a file the agent copied in from it sits at its host path in the container. */
+ hostHome: string | null;
+ /** Folders mounted from this machine at the same path (the project): read on this machine. */
+ mounted: readonly string[];
+ /** The container's temp folders (default /tmp and /var/tmp). */
+ temps?: readonly string[];
+ view: FilesUsedView;
+};
+
+/** The program the container runs (exported for its tests). */
+export const FILES_USED_VIEW_SCRIPT = String.raw`
+import base64, hashlib, json, os, stat, sys
+def handle(req):
+ out = {}
+ def canon(p):
+ d, b = os.path.split(p)
+ r = os.path.realpath(d)
+ return os.path.join(r, b) if os.path.isdir(r) else None
+ def opened(p):
+ fd = os.open(p, os.O_RDONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_NONBLOCK", 0))
+ st = os.fstat(fd)
+ if not stat.S_ISREG(st.st_mode):
+ os.close(fd)
+ return None, st
+ return fd, st
+ if req["op"] == "inspect":
+ for p in req["paths"]:
+ c = canon(p)
+ if c is None:
+ out[p] = {"canonical": p, "kind": "missing"}
+ continue
+ try:
+ st = os.lstat(c)
+ except (FileNotFoundError, NotADirectoryError):
+ out[p] = {"canonical": c, "kind": "missing"}
+ continue
+ except OSError:
+ out[p] = {"canonical": c, "kind": "unreadable"}
+ continue
+ if stat.S_ISDIR(st.st_mode):
+ out[p] = {"canonical": c, "kind": "dir"}
+ continue
+ if not stat.S_ISREG(st.st_mode):
+ out[p] = {"canonical": c, "kind": "other"}
+ continue
+ item = {"canonical": c, "kind": "file", "size": st.st_size, "sha256": None, "mtimeMs": st.st_mtime * 1000}
+ if st.st_size <= req["hash"]:
+ try:
+ fd, fst = opened(c)
+ if fd is not None:
+ h = hashlib.sha256()
+ with os.fdopen(fd, "rb") as f:
+ for chunk in iter(lambda: f.read(1 << 20), b""):
+ h.update(chunk)
+ item["sha256"] = h.hexdigest()
+ item["size"] = fst.st_size
+ except OSError:
+ pass
+ out[p] = item
+ elif req["op"] == "read":
+ for p in req["paths"]:
+ try:
+ fd, st = opened(p)
+ except OSError:
+ out[p] = None
+ continue
+ if fd is None:
+ out[p] = None
+ continue
+ with os.fdopen(fd, "rb") as f:
+ if st.st_size > req["max"]:
+ out[p] = "too_large"
+ continue
+ data = f.read(req["max"] + 1)
+ out[p] = "too_large" if len(data) > req["max"] else base64.b64encode(data).decode("ascii")
+ elif req["op"] == "changed":
+ found = []
+ entries = [0]
+ lo, hi = req["low"] / 1000, req["high"] / 1000
+ def walk(d, depth):
+ if depth > 3 or len(found) >= 128:
+ return
+ try:
+ children = sorted(os.scandir(d), key=lambda e: e.name)
+ except OSError:
+ return
+ for e in children:
+ entries[0] += 1
+ if len(found) >= 128 or entries[0] > 4000:
+ return
+ try:
+ if e.is_dir(follow_symlinks=False):
+ if e.name not in ("node_modules", ".git", ".venv"):
+ walk(e.path, depth + 1)
+ continue
+ if not e.is_file(follow_symlinks=False):
+ continue
+ st = e.stat(follow_symlinks=False)
+ if lo <= max(st.st_mtime, st.st_ctime) <= hi:
+ found.append(e.path)
+ except OSError:
+ pass
+ for d in req["dirs"]:
+ c = os.path.realpath(d)
+ if os.path.isdir(c) and not os.path.islink(d):
+ walk(c, 0)
+ out = {"files": found}
+
+ return out
+for line in sys.stdin.buffer:
+ if not line.strip():
+ continue
+ try:
+ answer = handle(json.loads(line))
+ except Exception:
+ answer = {"error": True}
+ sys.stdout.write(json.dumps(answer) + "\n")
+ sys.stdout.flush()
+`;
+
+const STEP_TIMEOUT_MS = 20_000;
+/** The container's helper ends after this long without a step. */
+const IDLE_MS = 60_000;
+/** Paths per exec, at most: a step past it is split. */
+const PATHS_PER_EXEC = 512;
+
+type RunResult = { code: number | null; stdout: Buffer };
+export type ViewRunner = (request: unknown, maxOutputBytes: number) => Promise<RunResult>;
+
+/**
+ * One long-lived `docker exec -i <container> /usr/bin/python3 -I -c <program>`
+ * answering one JSON line per request (a fresh exec per step is too slow to
+ * keep a file a later call deletes at once). Requests run one at a time; a
+ * 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): 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();
+ let idle: ReturnType<typeof setTimeout> | null = null;
+ const end = (current: Live) => {
+ if (live === current) live = null;
+ try {
+ current.child.kill("SIGKILL");
+ } catch {
+ // Gone.
+ }
+ const waiting = current.waiting;
+ current.waiting = null;
+ waiting?.(null);
+ };
+ /** An idle helper never keeps the launcher running; one with a step in flight does. */
+ const hold = (current: Live, on: boolean) => {
+ for (const handle of [current.child, current.child.stdin, current.child.stdout] as unknown as Array<{ ref?: () => void; unref?: () => void }>) {
+ if (on) handle.ref?.();
+ else handle.unref?.();
+ }
+ };
+ const start = (): Live | null => {
+ let child: ChildProcessWithoutNullStreams;
+ try {
+ child = spawn(docker, ["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;
+ }
+ const current: Live = { child, buffer: [], size: 0, waiting: null };
+ child.stdout.on("data", (chunk: Buffer) => {
+ let rest = chunk;
+ for (;;) {
+ const newline = rest.indexOf(10);
+ if (newline < 0) break;
+ const line = Buffer.concat([...current.buffer, rest.subarray(0, newline)]);
+ current.buffer = [];
+ current.size = 0;
+ rest = rest.subarray(newline + 1);
+ const waiting = current.waiting;
+ current.waiting = null;
+ waiting?.(line);
+ }
+ if (rest.length > 0) {
+ current.buffer.push(rest);
+ current.size += rest.length;
+ }
+ });
+ child.on("error", () => end(current));
+ child.on("close", () => end(current));
+ child.stdin.on("error", () => end(current));
+ hold(current, false);
+ return current;
+ };
+ return (request, maxOutputBytes) => {
+ const run = tail.then(() => new Promise<RunResult>((resolvePromise) => {
+ const current = live ?? (live = start());
+ if (idle) clearTimeout(idle);
+ if (!current) {
+ resolvePromise({ code: null, stdout: Buffer.alloc(0) });
+ return;
+ }
+ let settled = false;
+ hold(current, true);
+ const timer = setTimeout(() => end(current), timeoutMs);
+ timer.unref?.();
+ const guard = setInterval(() => {
+ if (current.size > maxOutputBytes) end(current);
+ }, 50);
+ guard.unref?.();
+ current.waiting = (line) => {
+ if (settled) return;
+ settled = true;
+ clearTimeout(timer);
+ clearInterval(guard);
+ hold(current, false);
+ resolvePromise(line && line.length <= maxOutputBytes ? { code: 0, stdout: line } : { code: null, stdout: Buffer.alloc(0) });
+ if (!line) return;
+ if (line.length > maxOutputBytes) end(current);
+ // An idle helper goes after a while; the next step starts another.
+ idle = setTimeout(() => end(current), IDLE_MS);
+ idle.unref?.();
+ };
+ try {
+ current.child.stdin.write(`${JSON.stringify(request)}\n`);
+ } catch {
+ end(current);
+ }
+ }));
+ tail = run.catch(() => undefined);
+ return run;
+ };
+}
+
+function chunked<T>(items: readonly T[], size: number): T[][] {
+ const out: T[][] = [];
+ for (let index = 0; index < items.length; index += size) out.push(items.slice(index, index + size));
+ return out;
+}
+
+/** A FilesUsedView over a runner (dockerExecRunner for a live container). `onFailure` hears each step that could not ask it. */
+export function containerFilesUsedView(run: ViewRunner, onFailure?: (op: string) => void): FilesUsedView {
+ const ask = async (request: Record<string, unknown>, maxOutputBytes: number): Promise<Record<string, unknown> | null> => {
+ try {
+ const result = await run(request, maxOutputBytes);
+ if (result.code !== 0) throw new Error("exec failed");
+ const parsed: unknown = JSON.parse(result.stdout.toString("utf8"));
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("bad answer");
+ return parsed as Record<string, unknown>;
+ } catch {
+ onFailure?.(String(request.op));
+ return null;
+ }
+ };
+ return {
+ async inspect(paths, hashBytes) {
+ const out = new Map<string, ViewFacts>();
+ for (const part of chunked([...new Set(paths)], PATHS_PER_EXEC)) {
+ const answer = await ask({ op: "inspect", paths: part, hash: hashBytes }, 1024 + part.length * 8_192);
+ for (const path of part) {
+ const value = answer?.[path] as Record<string, unknown> | undefined;
+ const canonical = typeof value?.canonical === "string" && value.canonical.startsWith("/") ? value.canonical : path;
+ if (value?.kind === "file" && typeof value.size === "number") {
+ out.set(path, { canonical, kind: "file", size: value.size, sha256: typeof value.sha256 === "string" && /^[0-9a-f]{64}$/.test(value.sha256) ? value.sha256 : null, mtimeMs: typeof value.mtimeMs === "number" ? value.mtimeMs : 0 });
+ } else if (value?.kind === "missing" || value?.kind === "dir" || value?.kind === "other") out.set(path, { canonical, kind: value.kind });
+ else out.set(path, { canonical, kind: "unreadable" });
+ }
+ }
+ return out;
+ },
+ async read(paths, maxBytes) {
+ const out = new Map<string, Buffer | "too_large" | null>();
+ // One file per exec: each answer is bounded by the per-file cap.
+ for (const path of new Set(paths)) {
+ const answer = await ask({ op: "read", paths: [path], max: maxBytes }, Math.ceil(maxBytes * 4 / 3) + 8_192);
+ const value = answer?.[path];
+ out.set(path, value === "too_large" ? "too_large" : typeof value === "string" ? Buffer.from(value, "base64") : null);
+ }
+ return out;
+ },
+ async changed(dirs, low, high) {
+ if (dirs.length === 0) return [];
+ const answer = await ask({ op: "changed", dirs: [...new Set(dirs)], low, high }, 1024 * 1024);
+ const files = answer?.files;
+ return Array.isArray(files) ? files.filter((file): file is string => typeof file === "string" && file.startsWith("/")) : [];
+ },
+ };
+}
+
+/**
+ * The tracker's sandbox for a sandboxed engine (`server.sandbox` of
+ * src/engine-opencode.js): its container, HOME and mounted folders from the
+ * record. Null without a container.
+ */
+export function sandboxFilesUsed(input: {
+ container: string | null | undefined;
+ manifest: unknown;
+ cwd: string;
+ hostHome: string | null;
+ docker?: string;
+ log?: (level: "info" | "warn", message: string, attributes?: Record<string, unknown>) => void;
+}): FilesUsedSandbox | null {
+ if (!input.container) return null;
+ const manifest = typeof input.manifest === "object" && input.manifest !== null ? input.manifest as { home?: unknown; workspaces?: unknown } : {};
+ 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"), (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 });
+ });
+ return { home, hostHome: input.hostHome, mounted: [...new Set([input.cwd, ...workspaces])], view };
+}
diff --git a/apps/server/src/session-archive/files-used.ts b/apps/server/src/session-archive/files-used.ts
index da2c7dab..d00325be 100644
--- a/apps/server/src/session-archive/files-used.ts
+++ b/apps/server/src/session-archive/files-used.ts
@@ -13,7 +13,7 @@
import { createHash } from "node:crypto";
import { lstat, mkdir, open, readFile, readdir, realpath, rm, writeFile, rename } from "node:fs/promises";
import { homedir, tmpdir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { stateKey } from "./files.js";
import { HASH_READ_BYTES, OPEN_ENTRY_FLAGS, isArchiveCredentialPath, statFields, type ScannedEntry } from "./manifest.js";
@@ -28,12 +28,51 @@ import {
type FilesUsedLimits,
type FilesUsedOp,
type PendingUse,
+ type UseClass,
type UseContext,
} from "./files-used-policy.js";
import { shellCommandUses } from "./files-used-shell.js";
import { sseFrames } from "./tool-start.js";
import { lockfileEcosystem, MANIFEST_NAMES, MAX_LOCKFILE_BYTES, MAX_TOOLCHAIN_PROJECTS, sortToolchainProjects, toolchainProject, type ToolchainProject } from "./deps.js";
import { redactUploadContent } from "../session-uploader.js";
+import type { FilesUsedSandbox, ViewFacts } from "./files-used-sandbox.js";
+
+export { containerFilesUsedView, dockerExecRunner, sandboxFilesUsed, type FilesUsedSandbox, type FilesUsedView } from "./files-used-sandbox.js";
+
+/** A regular file's bytes (never a link followed): `too_large` past `maxBytes`, null when it is not there or unreadable. */
+async function readLocalFile(absolute: string, maxBytes: number): Promise<Buffer | "too_large" | null> {
+ let stats;
+ try {
+ stats = await lstat(absolute);
+ } catch {
+ return null;
+ }
+ if (!stats.isFile()) return null;
+ if (stats.size > maxBytes) return "too_large";
+ try {
+ const handle = await open(absolute, OPEN_ENTRY_FLAGS);
+ try {
+ return await handle.readFile();
+ } finally {
+ await handle.close().catch(() => undefined);
+ }
+ } catch {
+ return null;
+ }
+}
+
+/** A container path's facts as fileFacts gives them (`unreadable`: the sandbox could not be asked). */
+function viewFacts(facts: ViewFacts | undefined): FileFacts | "missing" | "not_file" | "unreadable" {
+ if (!facts || facts.kind === "unreadable") return "unreadable";
+ if (facts.kind === "missing") return "missing";
+ if (facts.kind !== "file") return "not_file";
+ return { size: facts.size, sha256: facts.sha256, mtimeMs: facts.mtimeMs, dev: 0, ino: 0 };
+}
+
+function inside(parent: string, child: string): boolean {
+ const rel = relative(resolve(parent), resolve(child));
+ return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
export * from "./files-used-policy.js";
@@ -516,8 +555,20 @@ export type FilesUsedTrackerOptions = {
now?: () => number;
/** Tests: the temp folders (tempRoots() by default). */
temps?: readonly string[];
+ /**
+ * A chat in the Linux sandbox (box/; CLI: `sandbox`, files-used-sandbox.ts):
+ * `~` is the container's HOME, the temp folders are the container's, and
+ * every path outside the mounted project is read in the container, never here.
+ */
+ sandboxFor?: (sessionId: string) => FilesUsedSandbox | null;
};
+/** The sandbox's temp folders when the launcher names none. */
+const SANDBOX_TEMPS = ["/tmp", "/var/tmp"];
+
+/** A path the tracker looked at: where it really is, whether it is read on this machine, and (in the container) what is there. */
+type Resolved = { absolute: string; local: boolean; facts?: ViewFacts };
+
type TrackedSession = {
/** Calls whose files were kept at their end, by call id. */
done: Set<string>;
@@ -566,7 +617,7 @@ export class FilesUsedTracker {
return run;
}
- private async useContext(root: string): Promise<UseContext> {
+ private async useContext(root: string, sandbox: FilesUsedSandbox | null = null): Promise<UseContext> {
this.context ??= (async () => ({
roots: [],
home: this.home,
@@ -576,9 +627,14 @@ export class FilesUsedTracker {
isCredentialPath: isArchiveCredentialPath,
}))();
const base = await this.context;
+ if (sandbox) return { ...base, home: sandbox.home, temps: [...(sandbox.temps ?? SANDBOX_TEMPS)], roots: await pathForms(root) };
return { ...base, roots: await pathForms(root) };
}
+ private sandbox(sessionId: string): FilesUsedSandbox | null {
+ return this.options.sandboxFor?.(sessionId) ?? null;
+ }
+
/** Asked at every step (cheap): the user's switch takes effect at the next tool call. */
private async active(sessionId: string): Promise<boolean> {
const store = this.options.archive.filesUsed;
@@ -603,26 +659,87 @@ export class FilesUsedTracker {
const key = call.callId ?? `${call.tool}:${call.start ?? ""}:${JSON.stringify(call.input).slice(0, 200)}`;
if (state.done.has(key)) return 0;
state.done.add(key);
- const context = await this.useContext(root);
- let staged = 0;
- for (const use of await this.callFiles(call, root, context)) {
- const absolute = (await canonicalFile(use.path)) ?? use.path;
- if (call.callId && !state.firstCall.has(absolute)) state.firstCall.set(absolute, call.callId);
- const kind = classifyUse(absolute, context);
- if (kind?.plan === "stage" && (await this.stageFile(sessionId, absolute, kind.archivePath!, kind.scrub)) !== null) staged += 1;
+ const sandbox = this.sandbox(sessionId);
+ const context = await this.useContext(root, sandbox);
+ const uses = await this.callFiles(call, root, context, sandbox);
+ const resolved = await this.resolvePaths(uses.map((use) => use.path), sandbox);
+ const toStage: Array<{ where: Resolved; kind: UseClass }> = [];
+ for (const use of uses) {
+ const where = resolved.get(use.path)!;
+ if (call.callId && !state.firstCall.has(where.absolute)) state.firstCall.set(where.absolute, call.callId);
+ const kind = this.classify(where, context, sandbox);
+ if (kind?.plan === "stage") toStage.push({ where, kind });
}
+ let staged = 0;
+ for (const result of await this.stageFiles(sessionId, toStage, sandbox)) if (result !== null) staged += 1;
return staged;
}
+ /** Whether a path is read on this machine: always without the sandbox; in it, only inside a folder mounted at the same path. */
+ private isLocal(absolute: string, sandbox: FilesUsedSandbox | null): boolean {
+ return !sandbox || sandbox.mounted.some((dir) => inside(dir, absolute));
+ }
+
+ /**
+ * Where each path really is (its folder as a real path, the file never
+ * followed). In the sandbox a path outside the mounted project, or one
+ * whose real folder leaves it, is resolved and inspected in the container.
+ */
+ private async resolvePaths(paths: readonly string[], sandbox: FilesUsedSandbox | null): Promise<Map<string, Resolved>> {
+ const out = new Map<string, Resolved>();
+ const remote: string[] = [];
+ for (const path of new Set(paths)) {
+ if (!this.isLocal(path, sandbox)) {
+ remote.push(path);
+ continue;
+ }
+ const absolute = (await canonicalFile(path)) ?? resolve(path);
+ if (this.isLocal(absolute, sandbox)) out.set(path, { absolute, local: true });
+ else remote.push(path);
+ }
+ if (remote.length > 0 && sandbox) {
+ const store = this.options.archive.filesUsed;
+ const facts = await sandbox.view.inspect(remote, store?.currentLimits.maxFileBytes ?? DEFAULT_FILES_USED_LIMITS.maxFileBytes);
+ for (const path of remote) {
+ const found = facts.get(path) ?? { canonical: path, kind: "unreadable" as const };
+ // A container path whose real folder is the mounted project is that project file (the same bytes here).
+ out.set(path, this.isLocal(found.canonical, sandbox) ? { absolute: found.canonical, local: true } : { absolute: found.canonical, local: false, facts: found });
+ }
+ }
+ return out;
+ }
+
+ /**
+ * Where a file is and what may happen to its bytes (files-used-policy.ts).
+ * In the sandbox the agent's home is the container's; a container file
+ * outside the project is never scanned here: its bytes are kept from the
+ * container (staged), like a temp file.
+ */
+ private classify(where: Resolved, context: UseContext, sandbox: FilesUsedSandbox | null): UseClass | null {
+ let kind = classifyUse(where.absolute, context);
+ if (!sandbox || where.local || !kind) return kind;
+ if (kind.scope === "outside" && sandbox.hostHome) kind = classifyUse(where.absolute, { ...context, home: sandbox.hostHome }) ?? kind;
+ if (kind.plan === "scan") kind = { ...kind, plan: "stage" };
+ return kind;
+ }
+
/** A call's files: what it names, and the files changed during it in a temp folder it names. */
- private async callFiles(call: UsedToolCall, root: string, context: UseContext): Promise<Array<{ path: string; op: FilesUsedOp; implicit?: true }>> {
- const uses = toolCallUses(call, root, this.home);
+ private async callFiles(call: UsedToolCall, root: string, context: UseContext, sandbox: FilesUsedSandbox | null = null): Promise<Array<{ path: string; op: FilesUsedOp; implicit?: true }>> {
+ const uses = toolCallUses(call, root, context.home);
if (!SHELL_TOOLS.has(call.tool) || call.start === null) return uses;
const out = [...uses];
const seen = new Set(uses.map((use) => use.path));
+ const end = call.end ?? this.now();
+ const inTemp = (path: string) => context.temps.some((temp) => path !== temp && path.startsWith(`${temp}/`));
+ const containerDirs: string[] = [];
for (const use of uses) {
+ if (!this.isLocal(use.path, sandbox)) {
+ // The container's temp folders: walked there, in one step for the call.
+ if (inTemp(use.path)) containerDirs.push(use.path);
+ continue;
+ }
const real = (await canonicalFile(use.path)) ?? use.path;
- if (!context.temps.some((temp) => real !== temp && real.startsWith(`${temp}/`))) continue;
+ if (!inTemp(real) || !this.isLocal(real, sandbox)) continue;
let stats;
try {
stats = await lstat(real);
@@ -630,7 +747,15 @@ export class FilesUsedTracker {
continue;
}
if (!stats.isDirectory()) continue;
- for (const file of await changedInFolder(real, call.start, call.end ?? this.now())) {
+ for (const file of await changedInFolder(real, call.start, end)) {
+ if (!seen.has(file)) {
+ seen.add(file);
+ out.push({ path: file, op: "write" });
+ }
+ }
+ }
+ if (containerDirs.length > 0 && sandbox) {
+ for (const file of await sandbox.view.changed(containerDirs, call.start - CALL_WINDOW_SLACK_MS, end + CALL_WINDOW_SLACK_MS)) {
if (!seen.has(file)) {
seen.add(file);
out.push({ path: file, op: "write" });
@@ -640,30 +765,24 @@ export class FilesUsedTracker {
return out;
}
- /** Keeps a copy of a temp file, or the scrubbed copy of an allowlisted home config; null when nothing was kept. */
- private async stageFile(sessionId: string, absolute: string, archivePath: string, scrub?: Parameters<typeof scrubHomeConfig>[0]): Promise<{ size: number; sha256: string } | "too_large" | null> {
+ /** Keeps a copy of each temp file or allowlisted home config (scrubbed); per file, what was kept, or null when nothing was. */
+ private async stageFiles(sessionId: string, files: ReadonlyArray<{ where: Resolved; kind: UseClass }>, sandbox: FilesUsedSandbox | null): Promise<Array<{ size: number; sha256: string } | "too_large" | null>> {
const store = this.options.archive.filesUsed;
- if (!store) return null;
+ if (!store || files.length === 0) return files.map(() => null);
const limits = store.currentLimits;
- let stats;
- try {
- stats = await lstat(absolute);
- } catch {
- return null;
- }
- if (!stats.isFile()) return null;
- if (stats.size > limits.maxFileBytes) return "too_large";
- let bytes: Buffer;
- try {
- const handle = await open(absolute, OPEN_ENTRY_FLAGS);
- try {
- bytes = await handle.readFile();
- } finally {
- await handle.close().catch(() => undefined);
- }
- } catch {
- return null;
+ const remote = files.filter(({ where }) => !where.local && where.facts?.kind === "file").map(({ where }) => where.absolute);
+ const remoteBytes = remote.length > 0 && sandbox ? await sandbox.view.read(remote, limits.maxFileBytes) : new Map<string, Buffer | "too_large" | null>();
+ const out: Array<{ size: number; sha256: string } | "too_large" | null> = [];
+ for (const { where, kind } of files) {
+ const bytes = where.local ? await readLocalFile(where.absolute, limits.maxFileBytes) : remoteBytes.get(where.absolute) ?? null;
+ out.push(bytes === null || bytes === "too_large" ? bytes : await this.stageBytes(sessionId, where.absolute, kind.archivePath!, bytes, kind.scrub));
}
+ return out;
+ }
+
+ private async stageBytes(sessionId: string, absolute: string, archivePath: string, bytes: Buffer, scrub?: Parameters<typeof scrubHomeConfig>[0]): Promise<{ size: number; sha256: string } | "too_large" | null> {
+ const store = this.options.archive.filesUsed;
+ if (!store) return null;
if (scrub) {
const scrubbed = scrubHomeConfig(scrub, bytes.toString("utf8"));
if (scrubbed === null) return null;
@@ -692,20 +811,24 @@ export class FilesUsedTracker {
if (!(await this.active(sessionId))) return result;
const store = this.options.archive.filesUsed!;
state.turn += 1;
- const context = await this.useContext(root);
+ const sandbox = this.sandbox(sessionId);
+ const context = await this.useContext(root, sandbox);
const limits = store.currentLimits;
- const uses = new Map<string, { op: FilesUsedOp; callId: string | null; implicit: boolean }>();
+ const uses = new Map<string, { op: FilesUsedOp; callId: string | null; implicit: boolean; where: Resolved }>();
const calls = usedToolCalls(messages);
+ const named: Array<{ use: { path: string; op: FilesUsedOp; implicit?: true }; callId: string | null }> = [];
for (const call of calls) {
result.staged += await this.keepCall(sessionId, root, call);
- for (const use of await this.callFiles(call, root, context)) {
- const absolute = (await canonicalFile(use.path)) ?? resolve(use.path);
- const known = uses.get(absolute);
- if (known) {
- known.op = strongerOp(known.op, use.op);
- known.implicit &&= use.implicit === true;
- } else if (uses.size < MAX_FILES_USED_ITEMS) uses.set(absolute, { op: use.op, callId: state.firstCall.get(absolute) ?? call.callId, implicit: use.implicit === true });
- }
+ for (const use of await this.callFiles(call, root, context, sandbox)) named.push({ use, callId: call.callId });
+ }
+ const resolved = await this.resolvePaths(named.map(({ use }) => use.path), sandbox);
+ for (const { use, callId } of named) {
+ const where = resolved.get(use.path)!;
+ const known = uses.get(where.absolute);
+ if (known) {
+ known.op = strongerOp(known.op, use.op);
+ known.implicit &&= use.implicit === true;
+ } else if (uses.size < MAX_FILES_USED_ITEMS) uses.set(where.absolute, { op: use.op, callId: state.firstCall.get(where.absolute) ?? callId, implicit: use.implicit === true, where });
}
// The end-of-turn snapshot: files of the project created or changed during the turn (gitignored ones
// too) that no call named. A stat walk, bounded by entries and by the turn-end budget.
@@ -714,26 +837,31 @@ export class FilesUsedTracker {
const realRoot = (await pathForms(root)).at(-1) ?? root;
for (const file of await changedSince(realRoot, since, Math.min(deadline, started + SNAPSHOT_BUDGET_MS))) {
if (uses.has(file) || uses.size >= MAX_FILES_USED_ITEMS) continue;
- uses.set(file, { op: "write", callId: null, implicit: false });
+ uses.set(file, { op: "write", callId: null, implicit: false, where: { absolute: file, local: true } });
result.snapshot += 1;
}
}
const items: PendingUse[] = [];
for (const [absolute, use] of uses) {
- const kind = classifyUse(absolute, context);
+ const kind = this.classify(use.where, context, sandbox);
if (!kind) continue;
// A file the chain will hold gets its hash from the chain's own scan (index.ts); a hash-only one is
- // hashed here while the budget lasts; a denylisted one never is.
+ // hashed here while the budget lasts; a denylisted one never is. A container file: as the box answered.
const hashBytes = kind.plan === "hold" && kind.reason !== "denylisted" && this.now() < deadline ? limits.maxFileBytes : -1;
- const facts = await fileFacts(absolute, hashBytes);
+ const facts = use.where.local ? await fileFacts(absolute, hashBytes) : viewFacts(use.where.facts);
// A config a program loads without naming it is listed only when it is there.
- if (facts === "not_file" || (facts === "missing" && use.implicit)) continue;
+ if (facts === "not_file" || ((facts === "missing" || facts === "unreadable") && use.implicit)) continue;
+ if (facts === "unreadable") {
+ // The sandbox could not be asked: listed, never guessed from this machine.
+ items.push({ path: kind.path, scope: kind.scope, op: use.op, size: null, sha256: null, plan: "hold", reason: kind.plan === "hold" ? kind.reason : "missing", turn: state.turn, ...(kind.archivePath ? { archive_path: kind.archivePath } : {}), ...(use.callId ? { call_id: use.callId } : {}) });
+ continue;
+ }
const present = facts !== "missing";
let size = present ? facts.size : null;
let sha256 = present ? facts.sha256 : null;
let reason = kind.reason;
if (kind.plan === "stage" && present) {
- const staged = await this.stageFile(sessionId, absolute, kind.archivePath!, kind.scrub);
+ const staged = (await this.stageFiles(sessionId, [{ where: use.where, kind }], sandbox))[0] ?? null;
if (staged === "too_large") reason = "too_large";
else if (staged) {
// The archived copy (for a home config, the scrubbed one): its size and hash.
diff --git a/apps/server/src/session-archive/index.ts b/apps/server/src/session-archive/index.ts
index 642437cd..cac0de07 100644
--- a/apps/server/src/session-archive/index.ts
+++ b/apps/server/src/session-archive/index.ts
@@ -12,7 +12,8 @@
* presigned multipart URLs. The embedded server drives it through
* lifecycle.ts; see README.md.
*/
-import { randomBytes, randomUUID } from "node:crypto";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createReadStream } from "node:fs";
import { lstat, mkdir, readdir, readFile, realpath, rename, rm, stat, statfs } from "node:fs/promises";
import { isAbsolute, join, resolve } from "node:path";
import { z } from "zod";
@@ -43,6 +44,7 @@ import {
manifestSource,
parseBaselineText,
readArchiveGit,
+ SANDBOX_ROOT_NAME,
scanArchiveTree,
statFields,
type ArchiveEntry,
@@ -84,6 +86,7 @@ import {
safeHome,
tempRoots,
type FilesUsedItem,
+ type FilesUsedSandbox,
type PendingUse,
type TurnFilesUsed,
type UsedToolCall,
@@ -118,6 +121,19 @@ function withChainHashes(items: FilesUsedItem[], pending: readonly PendingUse[],
});
}
+/** A box turn checkpoint larger than this is not archived (sandboxEntries). */
+const SANDBOX_SNAPSHOT_MAX_BYTES = 1024 * 1024 * 1024;
+
+async function sha256Path(path: string): Promise<string> {
+ return await new Promise((resolvePromise, reject) => {
+ const hash = createHash("sha256");
+ const stream = createReadStream(path);
+ stream.on("data", (chunk) => hash.update(chunk));
+ stream.on("error", reject);
+ stream.on("end", () => resolvePromise(hash.digest("hex")));
+ });
+}
+
/** Capture v2 (#14): a touched file the folder scan did not hold larger than this is left out, with its path, size and hash. */
const MAX_TOUCHED_FILE_BYTES = 1024 * 1024 * 1024;
import {
@@ -208,6 +224,15 @@ export type SessionArchiverOptions = {
touchedFlushMs?: number;
/** Conservative bound for queued plus currently packing archive bytes. */
pendingByteBudget?: number;
+ /**
+ * The Linux sandbox (box/): where the server saves each chat's turn
+ * checkpoints (<dir>/<session>/{record,turn-N,final}.{json,tar}). A chat
+ * with checkpoints carries them as opaque files, and its paths outside the
+ * project are the box's, never read on this machine.
+ */
+ sandboxSnapshotsDir?: string;
+ /** Files used: a chat in the Linux sandbox reads its files outside the project in the container (files-used-sandbox.ts). */
+ filesUsedSandbox?: (sessionId: string) => FilesUsedSandbox | null;
/** Required free space before and during packing. */
minimumFreeDiskBytes?: number;
/** Tests and diagnostics: override the filesystem free-space probe. */
@@ -492,6 +517,7 @@ export class SessionArchiver {
private readonly random: { uuid(): string; bytes(n: number): Buffer };
private readonly retry: RetryPolicy;
private readonly pendingByteBudget: number;
+ private readonly sandboxSnapshotsDir: string | null;
private readonly minimumFreeDiskBytes: number;
private readonly freeDiskBytes: (path: string) => Promise<number>;
private readonly accountId?: () => Promise<string | null>;
@@ -557,6 +583,7 @@ export class SessionArchiver {
...options.retry,
};
this.pendingByteBudget = archiveDiskBytes(options.pendingByteBudget, "OMNIRUSH_ARCHIVE_PENDING_BYTE_BUDGET", DEFAULT_PENDING_BYTE_BUDGET);
+ this.sandboxSnapshotsDir = options.sandboxSnapshotsDir ? resolve(options.sandboxSnapshotsDir) : null;
this.minimumFreeDiskBytes = archiveDiskBytes(options.minimumFreeDiskBytes, "OMNIRUSH_ARCHIVE_MIN_FREE_DISK_BYTES", DEFAULT_MIN_FREE_DISK_BYTES);
this.accountId = options.accountId;
this.freeDiskBytes = options.freeDiskBytes ?? (async (path) => {
@@ -577,7 +604,7 @@ export class SessionArchiver {
this.appDirs = [stateDir, ...(options.excludedDirs ?? []).map((dir) => resolve(dir))];
this.includeCredentials = options.archiveIncludeCredentialFiles === true;
this.filesUsed = new FilesUsedStore(join(this.dir, "files-used"));
- this.filesUsedTracker = new FilesUsedTracker({ archive: this, appDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, log: this.log });
+ this.filesUsedTracker = new FilesUsedTracker({ archive: this, appDirs: this.appDirs, includeCredentialFiles: this.includeCredentials, log: this.log, ...(options.filesUsedSandbox ? { sandboxFor: options.filesUsedSandbox } : {}) });
this.attachments = new AttachmentStore(join(this.dir, "attachments"), (path) => !this.includeCredentials && isUploadPathDenied(path), { appDirs: this.appDirs, includeCredentialFiles: this.includeCredentials });
this.touched = new TouchedPathStore(this.dirs.touched, {
ready: () => this.start(),
@@ -1464,6 +1491,7 @@ export class SessionArchiver {
// The files outside the workspace the session touched (outside.ts).
mergeScans(scan, await this.scanOutside(state, baseline, signal, filesUsed));
if (v2) mergeScans(scan, await this.attachmentEntries(sessionId));
+ mergeScans(scan, await this.sandboxEntries(sessionId));
if (filesUsed) mergeStaged(scan, await this.filesUsed.entries(sessionId));
if (options.trigger === "pre_tool" && options.before !== undefined) scanAsOf(scan.entries, new Map(baseline.map((entry) => [entry.path, entry])), options.before);
const change = touchedChange(baseline, scan);
@@ -1494,6 +1522,7 @@ export class SessionArchiver {
// The files outside the workspace the session touched (outside.ts).
mergeScans(scan, await this.scanOutside(state, baseline, signal, filesUsed));
if (v2) mergeScans(scan, await this.attachmentEntries(sessionId));
+ mergeScans(scan, await this.sandboxEntries(sessionId));
if (filesUsed) mergeStaged(scan, await this.filesUsed.entries(sessionId));
// Capture v2: the .git of the repository above a session folder (enclosing.ts).
if (v2) {
@@ -1840,6 +1869,37 @@ export class SessionArchiver {
});
}
+ /** A chat's checkpoint folder when it ran in a box (box/), else null. */
+ private async sandboxFolder(sessionId: string): Promise<string | null> {
+ if (!this.sandboxSnapshotsDir || !/^[A-Za-z0-9._:-]{8,128}$/.test(sessionId)) return null;
+ const folder = join(this.sandboxSnapshotsDir, sessionId);
+ return (await stat(folder).catch(() => null))?.isDirectory() ? folder : null;
+ }
+
+ /** The box's turn checkpoints of the chat, carried as opaque project files (CLI: the same). */
+ private async sandboxEntries(sessionId: string): Promise<TouchedScanResult> {
+ const none = (): TouchedScanResult => ({ entries: [], gone: new Set(), excluded: emptyExcludedCounts(), ignored: 0 });
+ const folder = await this.sandboxFolder(sessionId);
+ if (!folder) return none();
+ const names = (await readdir(folder).catch(() => [])).filter((name) => /^(?:record|final|turn-[0-9]+)\.(?:json|tar)$/.test(name)).sort();
+ const entries: ScannedEntry[] = [];
+ for (const name of names) {
+ const source = join(folder, name);
+ const info = await lstat(source, { bigint: true });
+ if (!info.isFile() || info.isSymbolicLink()) throw new Error(`sandbox snapshot ${name} is not a regular file`);
+ const size = Number(info.size);
+ if (!Number.isSafeInteger(size)) throw new Error(`sandbox snapshot ${name} is too large`);
+ // One checkpoint tar past this is left on the machine: sent, it would hold up
+ // every later archive of the chat. Its .json (size, sha256, paths) still goes.
+ if (name.endsWith(".tar") && size > SANDBOX_SNAPSHOT_MAX_BYTES) {
+ this.log("warn", "OmniRush sandbox snapshot is too large to archive; left on this machine", { sessionId, name, size });
+ continue;
+ }
+ entries.push({ path: `${SANDBOX_ROOT_NAME}/${sessionId}/${name}`, type: "file", size, sha256: await sha256Path(source), source, ...statFields(info), mode: 0o600 });
+ }
+ return { entries, gone: new Set(), excluded: emptyExcludedCounts(), ignored: 0 };
+ }
+
/** Capture v2 (#11): the session's staged attachments as archive entries read from their staged copies. */
private async attachmentEntries(sessionId: string): Promise<TouchedScanResult> {
const entries: ScannedEntry[] = [];
@@ -1863,6 +1923,9 @@ export class SessionArchiver {
* apart from the root's, which a whole-folder scan prunes to what it saw.
*/
private async scanOutside(state: SessionState, baseline: readonly ArchiveEntry[], signal?: AbortSignal, filesUsed = false): Promise<TouchedScanResult | null> {
+ // A chat in a box: a path outside the project names a file in the container, not on this machine. Its bytes
+ // come from the box's checkpoints and from files used (read in the container); this machine's file is never read.
+ if (await this.sandboxFolder(state.session_id)) return null;
let paths = new Set([...(await this.touched.outside(state.session_id)), ...outsideSourcesOf(baseline.map((entry) => entry.path))]);
// Files used: temp files and home config come from their staged copies only (scrubbed config, a temp file kept
// when its call ended), and home settings off the allowlist are never read; the scan keeps the rest.
diff --git a/apps/server/src/session-archive/manifest.ts b/apps/server/src/session-archive/manifest.ts
index b031ba3b..96831e15 100644
--- a/apps/server/src/session-archive/manifest.ts
+++ b/apps/server/src/session-archive/manifest.ts
@@ -28,6 +28,8 @@ export const OUTSIDE_ROOT_NAME = "__outside__";
export { ATTACHMENTS_ROOT_NAME };
/** Capture v2: the `.git` of the repository above the session folder (enclosing.ts); a workspace entry of that name is reserved too. */
export const ENCLOSING_REPO_ROOT_NAME = "__enclosing_repo__";
+/** The Linux sandbox's turn checkpoints (box/, index.ts sandboxEntries); a workspace entry of that name is reserved too. */
+export const SANDBOX_ROOT_NAME = "__sandbox__";
/** A git config file larger than this is left out (`too_large`): it is never read whole to scrub it, and never archived raw. */
const MAX_SCRUBBED_CONFIG_BYTES = 1024 * 1024;
export const STAT_CONCURRENCY = 64;
@@ -684,7 +686,7 @@ export async function scanArchiveTree(root: string, options: ScanOptions = {}):
for (const bytes of raw) {
const name = decodeName(bytes);
if (name === null) excluded.non_utf8 += 1;
- else if (!dir.rel && (name === RESERVED_ROOT_NAME || name === OUTSIDE_ROOT_NAME || name === ATTACHMENTS_ROOT_NAME || name === ENCLOSING_REPO_ROOT_NAME)) {
+ else if (!dir.rel && (name === RESERVED_ROOT_NAME || name === OUTSIDE_ROOT_NAME || name === ATTACHMENTS_ROOT_NAME || name === ENCLOSING_REPO_ROOT_NAME || name === SANDBOX_ROOT_NAME)) {
excluded.reserved += 1;
note(name, "reserved", "dir");
}
diff --git a/apps/server/src/session-uploader.ts b/apps/server/src/session-uploader.ts
index 83ecd7b4..88a99260 100644
--- a/apps/server/src/session-uploader.ts
+++ b/apps/server/src/session-uploader.ts
@@ -27,7 +27,10 @@ import { SUBAGENT_MODEL_FALLBACK_TRACE } from "./omnirush-swarm.js";
import { writeFileAtomic } from "./atomic-write.js";
import { XCODE_CLT_MISSING, gitSkipReason } from "./command-guard.js";
import { ExcludedFiles, listGitIgnored, type HashCache } from "./excluded-files.js";
-import { ToolchainCache, type CollectOptions as ToolchainOptions, type UploadToolchain } from "./toolchain.js";
+import { PROBE_ENV_OVERRIDES, ToolchainCache, type CollectOptions as ToolchainOptions, type UploadToolchain } from "./toolchain.js";
+import { boxProbeRunner } from "./box/capture.js";
+import type { BoxLabel } from "./box/box.js";
+import type { BoxCaptureInfo } from "./box/service.js";
import { engine2ImportedFrom } from "./engine2/imported.js";
import { ContextCapture, captureContextEnabled, type ContextOptions } from "./context/index.js";
import { INSTALL_LOG_OFF, installLogGate, type InstallLogGate } from "./context/install-log.js";
@@ -277,8 +280,33 @@ export type UploadEnvironment = {
* here: its earlier turns are the 2.x engine's ("opencode 2.0.18").
*/
imported_from?: string;
+ /** A chat in the project's Linux sandbox (box/): the machine it ran on; `os` is then linux. */
+ host_os?: string;
+ host_arch?: string;
+ host_os_version?: string;
+ /** The box the chat's commands ran in (box/box.ts label()); absent when they ran on this machine. */
+ sandbox?: BoxLabel;
};
+/**
+ * A chat in a box (an OmniRush box label, `kind: "omnirush-box"`): it ran
+ * its commands on Linux in a container, so `os` is linux and the machine it
+ * ran on is `host_os` / `host_arch` / `host_os_version`. Pipelines route
+ * these to the Linux environment set, never the native Windows/macOS one.
+ * The same as the CLI's workspace-sync.ts boxEnvironment.
+ */
+export function boxEnvironment(environment: UploadEnvironment, sandbox: BoxLabel | null): Partial<UploadEnvironment> {
+ if (!sandbox || sandbox.kind !== "omnirush-box") return {};
+ return {
+ os: "linux",
+ host_os: sandbox.host_os || environment.os,
+ host_arch: sandbox.host_arch || environment.arch,
+ host_os_version: environment.os_version,
+ // The shell the agent's commands ran in.
+ shell: "bash",
+ };
+}
+
type TraceEvent = {
at: string;
type: string;
@@ -783,6 +811,8 @@ export type TraceCapabilities = {
triggers?: string[];
/** The install log switch (context/install-log.ts): absent is off. */
install_log?: { enabled: boolean; sample_percent: number };
+ /** The Linux sandbox's server default (box/launch.ts serverDefault): "off" | "offer" | "on". */
+ local_box?: { default: string; max_turn_bytes?: number | null };
};
@@ -4476,6 +4506,9 @@ export class SessionUploader {
private readonly snapshotMaxBytes: number;
private environmentCache: Promise<UploadEnvironment> | null = null;
private readonly toolchains: ToolchainCache | null;
+ /** Chats in their project's Linux sandbox (box/), and the toolchain probed in those boxes. */
+ private readonly boxes = new Map<string, BoxCaptureInfo>();
+ private readonly boxToolchains: ToolchainCache | null;
private readonly excludedHashes: HashCache = new Map();
private spoolCounter = 0;
private spoolTail: Promise<void> = Promise.resolve();
@@ -4574,6 +4607,18 @@ export class SessionUploader {
...(options.toolchain ?? {}),
scrub: (toolchain) => redactUploadJson(toolchain).value as UploadToolchain,
});
+ // A box's packages and toolchain are the chat's (probed inside, no downloads); this machine's are not.
+ this.boxToolchains = options.toolchain === false
+ ? null
+ : new ToolchainCache({
+ checks: { isSecretName: isSecretAssignmentKey, scrubText: (text) => redactUploadText(text).text, isDenied: isUploadPathDenied },
+ run: boxProbeRunner((cwd) => this.boxForPath(cwd), PROBE_ENV_OVERRIDES),
+ resolve: (command) => command,
+ env: {},
+ probeTimeoutMs: 20_000,
+ freezeTimeoutMs: 90_000,
+ scrub: (toolchain) => redactUploadJson(toolchain).value as UploadToolchain,
+ });
this.onSessionClosed = options.onSessionClosed;
this.onPathTouched = options.onPathTouched;
this.onBinaryFile = options.onBinaryFile;
@@ -4879,9 +4924,33 @@ export class SessionUploader {
*/
private async sessionEnvironment(root: string, sessionId: string, waitMs?: number): Promise<UploadEnvironment> {
const environment = await this.environment();
- const toolchain = this.toolchains ? await this.toolchains.get(root, waitMs).catch(() => null) : null;
+ const box = this.boxes.get(sessionId) ?? null;
+ const toolchains = box ? this.boxToolchains : this.toolchains;
+ const toolchain = toolchains ? await toolchains.get(root, waitMs).catch(() => null) : null;
const importedFrom = engine2ImportedFrom(sessionId);
- return { ...environment, ...(toolchain ? { toolchain } : {}), ...(importedFrom ? { imported_from: importedFrom } : {}) };
+ return { ...environment, ...boxEnvironment(environment, box?.label ?? null), ...(toolchain ? { toolchain } : {}), ...(box ? { sandbox: box.label } : {}), ...(importedFrom ? { imported_from: importedFrom } : {}) };
+ }
+
+ /**
+ * The chat's prompts run in its project's box (box/service.ts beforePrompt),
+ * or no longer (null). Set before startSession for a new chat.
+ */
+ setBox(sessionId: string, box: BoxCaptureInfo | null): void {
+ if (box) this.boxes.set(sessionId, box);
+ else this.boxes.delete(sessionId);
+ }
+
+ /** Whether the chat's commands run in a box (its paths outside the project are the box's). */
+ inBox(sessionId: string): boolean {
+ return this.boxes.has(sessionId);
+ }
+
+ private boxForPath(path: string): BoxCaptureInfo | null {
+ for (const box of this.boxes.values()) {
+ const rel = relative(box.root, path);
+ if (rel === "" || (!rel.startsWith("..") && !nodePath.isAbsolute(rel))) return box;
+ }
+ return null;
}
private negotiatedTraceSchema(force = false): Promise<2 | 3> {
@@ -4954,7 +5023,8 @@ export class SessionUploader {
startSession(sessionId: string, workspaceId: string, root: string): void {
if (!this.enabled || this.sessions.has(sessionId) || !/^[A-Za-z0-9._:-]{8,128}$/.test(sessionId)) return;
- void this.toolchains?.get(root).catch(() => null); // toolchain.ts: collected in the background
+ // toolchain.ts: collected in the background (a box chat's in its box).
+ void (this.boxes.has(sessionId) ? this.boxToolchains : this.toolchains)?.get(root).catch(() => null);
const state = this.newSessionState(sessionId, workspaceId, root, this.acquireCache(root));
state.ready = this.prepareSession(state);
this.sessions.set(sessionId, state);
@@ -4962,7 +5032,8 @@ export class SessionUploader {
// Capture context collects once the start snapshot is out.
let startSnapshotDone: () => void = () => undefined;
const startSnapshot = new Promise<void>((resolveStart) => (startSnapshotDone = resolveStart));
- this.context?.sessionStarted(sessionId, root, startSnapshot);
+ // A box chat: this machine's packages, services, processes and network are not the chat's.
+ if (!this.boxes.has(sessionId)) this.context?.sessionStarted(sessionId, root, startSnapshot);
this.enqueue(state, async () => {
await state.ready;
try {
diff --git a/apps/server/src/toolchain.ts b/apps/server/src/toolchain.ts
index 272dd21b..c518839a 100644
--- a/apps/server/src/toolchain.ts
+++ b/apps/server/src/toolchain.ts
@@ -378,7 +378,7 @@ function defaultIsFile(path: string): boolean {
export type RunResult = { code: number | null; stdout: string; stderr: string } | null;
export type RunCommand = (file: string, args: string[], options: { cwd: string; timeoutMs: number; maxBytes: number }) => Promise<RunResult>;
-const PROBE_ENV_OVERRIDES: Record<string, string> = {
+export const PROBE_ENV_OVERRIDES: Record<string, string> = {
NO_COLOR: "1",
TERM: "dumb",
PIP_DISABLE_PIP_VERSION_CHECK: "1",