loopat 0.1.2 → 0.1.3

package/README.md

@@ -131,6 +131,14 @@ Loopat splits configuration along role lines — read whichever applies:
 
 ### Docker (recommended)
 
+Pull the prebuilt image from GHCR:
+
+```sh
+docker run -d --privileged -p 20001:10001 ghcr.io/simpx/loopat:latest
+```
+
+Or, to build from source and persist the workspace in a named volume:
+
 ```sh
 docker compose up -d
 ```

package/bin/loopat.mjs

@@ -19,6 +19,17 @@ const here = dirname(fileURLToPath(import.meta.url))
 const pkgRoot = join(here, "..")
 const serverEntry = join(pkgRoot, "server", "src", "index.ts")
 
+// Subcommand routing. `loopat uninstall` runs a standalone cleanup entry (never
+// boots the server); everything else starts the server. Kept here in the Node
+// shim so the uninstall path doesn't pull in any server-side init.
+const SUBCOMMANDS = {
+  uninstall: join(pkgRoot, "server", "src", "uninstall.ts"),
+}
+const sub = process.argv[2]
+const subEntry = Object.prototype.hasOwnProperty.call(SUBCOMMANDS, sub) ? SUBCOMMANDS[sub] : null
+const entry = subEntry ?? serverEntry
+const forwardArgs = subEntry ? process.argv.slice(3) : process.argv.slice(2)
+
 function resolveBun() {
   // 1. Explicit override.
   if (process.env.LOOPAT_BUN && existsSync(process.env.LOOPAT_BUN)) {
@@ -49,7 +60,7 @@ function resolveBun() {
 }
 
 const bun = resolveBun()
-const child = spawn(bun, [serverEntry, ...process.argv.slice(2)], {
+const child = spawn(bun, [entry, ...forwardArgs], {
   stdio: "inherit",
   env: process.env,
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "loopat",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Self-hosted AI workspace built around context management — works solo, scales to teams",
   "license": "Apache-2.0",
   "homepage": "https://github.com/simpx/loopat",

package/server/src/bootstrap.ts

@@ -22,16 +22,33 @@ import { listUsers } from "./auth"
 type Check = { ok: boolean; label: string; hint?: string }
 
 function checkPodman(): Check {
+  const isMac = process.platform === "darwin"
+  let version: string
   try {
-    const out = execFileSync("podman", ["--version"], { stdio: "pipe" }).toString().trim()
-    return { ok: true, label: `podman (sandbox): ${out}` }
+    version = execFileSync("podman", ["--version"], { stdio: "pipe" }).toString().trim()
   } catch {
     return {
       ok: false,
       label: "podman (sandbox)",
-      hint: "install with: sudo apt install podman uidmap fuse-overlayfs   (Linux only)",
+      hint: isMac
+        ? "brew install podman, then: podman machine init && podman machine start"
+        : "sudo apt install podman uidmap fuse-overlayfs   (Linux)",
     }
   }
+  // On macOS podman runs inside a Linux VM ("machine"). `--version` succeeds even
+  // when the machine is stopped — `podman info` is what actually needs the VM up.
+  if (isMac) {
+    try {
+      execFileSync("podman", ["info"], { stdio: "pipe", timeout: 8000 })
+    } catch {
+      return {
+        ok: false,
+        label: `podman (sandbox): ${version}`,
+        hint: "podman machine isn't running — start it: podman machine start   (run `podman machine init` first if you never have)",
+      }
+    }
+  }
+  return { ok: true, label: `podman (sandbox): ${version}` }
 }
 
 function checkClaudeBinary(): Check {
@@ -47,6 +64,21 @@ function checkClaudeBinary(): Check {
   }
 }
 
+function checkGitCrypt(): Check {
+  try {
+    const out = execFileSync("git-crypt", ["--version"], { stdio: "pipe" }).toString().trim()
+    return { ok: true, label: `git-crypt (personal vault): ${out}` }
+  } catch {
+    return {
+      ok: false,
+      label: "git-crypt (personal vault)",
+      hint: process.platform === "darwin"
+        ? "brew install git-crypt   (encrypts your personal vault)"
+        : "sudo apt install git-crypt   (encrypts your personal vault)",
+    }
+  }
+}
+
 
 function describeRemote(dir: string, url: string | undefined): string {
   if (!existsSync(dir)) return "missing"
@@ -92,6 +124,7 @@ export async function printBootstrapBanner(cfg: WorkspaceConfig) {
     { ok: existsSync(configPath()), label: `config: ${configPath()}` },
     checkPodman(),
     checkClaudeBinary(),
+    checkGitCrypt(),
   ]
 
   const bar = "─".repeat(60)

package/server/src/host-exec.ts

@@ -0,0 +1,129 @@
+/**
+ * host-cli proxy (POC). Some CLIs can only run on the host — macOS-only tools,
+ * or company tools bound to a specific machine. The sandbox can't run them, so
+ * we run them on the host *on behalf of* a loop:
+ *
+ *   sandbox:  `aone foo`  →  shim  →  loopat-host (forwarder)  →
+ *   server :  POST /api/host-exec  →  execFile("aone", ["foo"]) on the host
+ *
+ * Trust model (deliberately simple): mounting the socket into a sandbox IS the
+ * trust decision — a host that turns on host-cli for a loop already trusts that
+ * loop, so there is NO whitelist. The loop may run any host cli (it can call the
+ * forwarder directly with a hand-built command).
+ *
+ * The mise-generated shims aren't a whitelist either — they're the declarative
+ * ENTRY POINT. "Which clis did the loop declare in `[host].clis`" shows up as
+ * "which shim binaries exist on PATH"; that's a UX convention (what the AI can
+ * conveniently reach), not a security boundary. The only boundary is whether
+ * the socket is mounted at all.
+ *
+ *   - runs with HOST user permissions
+ *   - cwd is a per-loop host workdir (mirrors the loop's workdir); the cli
+ *     cannot see inside the sandbox
+ *   - execFile, never a shell — argv is an array
+ */
+import { execFile } from "node:child_process"
+import { mkdir, writeFile, chmod } from "node:fs/promises"
+import { existsSync, rmSync, mkdirSync } from "node:fs"
+import { join } from "node:path"
+import { loopDir, LOOPAT_HOME } from "./paths"
+
+/** A per-loop host workdir — the host-side mirror of the loop's own workdir. */
+export function hostWorkdir(loopId: string): string {
+  return join(loopDir(loopId), "host-workdir")
+}
+
+/** The dir that holds the host-exec unix socket. We mount the DIR (not the
+ *  socket file) into sandboxes so a server restart — which recreates the
+ *  socket inode — stays visible to already-running containers. */
+export function hostExecDir(): string {
+  return join(LOOPAT_HOME, "host-exec")
+}
+export function hostExecSocketPath(): string {
+  return join(hostExecDir(), "host-exec.sock")
+}
+
+export type HostExecResult =
+  | { ok: true; exitCode: number; stdout: string; stderr: string }
+  | { ok: false; error: string }
+
+/** Run a host-cli in the loop's host workdir, with host permissions. No
+ *  whitelist — mounting the socket into the sandbox is the trust decision. */
+export async function runHostCli(opts: {
+  cli: string
+  args: string[]
+  cwd: string
+  stdin?: string
+  timeoutMs?: number
+}): Promise<HostExecResult> {
+  await mkdir(opts.cwd, { recursive: true })
+  return new Promise((resolve) => {
+    const child = execFile(
+      opts.cli,
+      opts.args,
+      { cwd: opts.cwd, timeout: opts.timeoutMs ?? 120_000, maxBuffer: 16 * 1024 * 1024 },
+      (err: any, stdout, stderr) => {
+        if (err && err.code === "ENOENT") {
+          resolve({ ok: false, error: `host has no '${opts.cli}'` })
+          return
+        }
+        const exitCode = typeof err?.code === "number" ? err.code : err ? 1 : 0
+        resolve({ ok: true, exitCode, stdout: String(stdout), stderr: String(stderr) })
+      },
+    )
+    if (opts.stdin !== undefined && child.stdin) {
+      child.stdin.write(opts.stdin)
+      child.stdin.end()
+    }
+  })
+}
+
+/**
+ * Write a shim per declared host-cli into `binDir` (which the sandbox puts on
+ * PATH ahead of everything). Each shim just hands off to the forwarder.
+ */
+export async function writeHostShims(binDir: string, clis: string[]): Promise<void> {
+  await mkdir(binDir, { recursive: true })
+  // The `loopat-host` forwarder is baked into the sandbox image; here we only
+  // emit the per-cli shims — each just hands off to it.
+  for (const cli of clis) {
+    const p = join(binDir, cli)
+    await writeFile(p, `#!/bin/sh\n# loopat host-cli shim — forwards "${cli}" to the host\nexec loopat-host "${cli}" "$@"\n`)
+    await chmod(p, 0o755)
+  }
+}
+
+/**
+ * Unix-socket server that runs host-clis for loops. The sandbox's
+ * forwarder connects over the *mounted* socket — no TCP, no exposed port, and
+ * only a container that has the socket mounted can reach it (the mount itself
+ * is a layer of isolation). Reuses runHostCli. stdout/stderr come back base64
+ * so the sh forwarder can pull them out of the JSON without escaping pain.
+ */
+export function serveHostExec(socketPath: string, deps: { loopExists: (id: string) => Promise<boolean> }) {
+  try { mkdirSync(hostExecDir(), { recursive: true }) } catch {}
+  try { if (existsSync(socketPath)) rmSync(socketPath) } catch {}
+  return Bun.serve({
+    unix: socketPath,
+    async fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname !== "/host-exec" || req.method !== "POST") return new Response("not found", { status: 404 })
+      const b: any = await req.json().catch(() => ({}))
+      const loopId = typeof b.loopId === "string" ? b.loopId : ""
+      const cli = typeof b.cli === "string" ? b.cli : ""
+      const args = Array.isArray(b.args) ? b.args.map(String) : []
+      if (!loopId || !cli) return Response.json({ error: "loopId + cli required" })
+      if (!(await deps.loopExists(loopId))) return Response.json({ error: "unknown loop" })
+      const r = await runHostCli({
+        cli, args, cwd: hostWorkdir(loopId),
+        stdin: typeof b.stdin === "string" ? b.stdin : undefined,
+      })
+      if (!r.ok) return Response.json({ error: r.error })
+      return Response.json({
+        exitCode: r.exitCode,
+        stdout_b64: Buffer.from(r.stdout).toString("base64"),
+        stderr_b64: Buffer.from(r.stderr).toString("base64"),
+      })
+    },
+  })
+}

package/server/src/index.ts

@@ -55,6 +55,7 @@ import {
 import { loadConfig, loadPersonalConfig, savePersonalConfig, saveWorkspaceConfig, loadTokenUsage, getActiveProvider, readPersonalDiskRaw, savePersonalDisk, describeApiKeyRef, writeVaultEnv, deleteVaultEnv, type ProviderConfig, type ModelEntry } from "./config"
 import { listBoards, createBoard, renameBoard, listKanbanColumns, addCard, toggleCard, deleteCard, moveCard, updateCardMeta, updateCardBlock, reorderCards, createColumn, deleteColumn, readKanbanConfig, saveColumnOrder, setColumnColor, renameColumn, assignDriverForCard, createLoopFromCard, linkLoopToCard, kanbanUserCtx } from "./kanban"
 import { printBootstrapBanner } from "./bootstrap"
+import { serveHostExec, hostExecSocketPath } from "./host-exec"
 import {
   createUser,
   findUser,
@@ -3177,6 +3178,16 @@ await printBootstrapBanner(cfg)
 const backfilled = await backfillAllMounts()
 if (backfilled > 0) console.log(`[loopat] backfilled context mounts on ${backfilled} loop(s)`)
 
+// host-cli proxy: a unix socket the loop sandboxes mount + forward to, so
+// host-only clis (macOS / machine-bound) run on the host on behalf of a loop.
+try {
+  const sock = hostExecSocketPath()
+  serveHostExec(sock, { loopExists })
+  console.log(`[loopat] host-exec socket: ${sock}`)
+} catch (e: any) {
+  console.warn(`[loopat] host-exec socket failed: ${e?.message ?? e}`)
+}
+
 // Pull every imported personal repo from its remote on boot (best-effort).
 // personal is a per-user repo synced directly (not via loops), so a host that
 // was offline catches up here; settings edits then write-through on save.

package/server/src/podman.ts

@@ -36,7 +36,7 @@
 import { execFile, spawn } from "node:child_process"
 import { createHash } from "node:crypto"
 import { existsSync } from "node:fs"
-import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
 import { homedir, tmpdir } from "node:os"
 import { join } from "node:path"
 import { promisify } from "node:util"
@@ -59,6 +59,8 @@ import {
 } from "./paths"
 import { loadConfig } from "./config"
 import { DEFAULT_VAULT, listVaultHomeMounts } from "./vaults"
+import { hostExecDir, writeHostShims } from "./host-exec"
+import { parse as tomlParse, stringify as tomlStringify } from "smol-toml"
 
 const execFileP = promisify(execFile)
 
@@ -75,6 +77,13 @@ export const V_CONTEXT_PERSONAL_MEMORY = "/loopat/context/personal/memory"
 export const V_CONTEXT_REPOS = "/loopat/context/repos"
 export const V_CONTEXT_CHAT = "/loopat/context/chat"
 
+// host-cli proxy: the dir holding the host-exec unix socket, mounted in so the
+// loop's `loopat-host` forwarder can reach the host. Mount the DIR (not the
+// socket file) so a server restart that recreates the socket inode stays
+// visible inside running containers.
+export const V_HOST_EXEC_DIR = "/loopat/host-exec"
+export const V_HOST_EXEC_SOCK = "/loopat/host-exec/host-exec.sock"
+
 // $HOME inside the container. Deliberately NOT host's homedir — if we bound
 // host's $HOME at its real path, podman would auto-create parent dirs for
 // every nested bind (LOOPAT_HOME, LOOPAT_INSTALL_DIR, etc. all live under
@@ -247,6 +256,15 @@ export async function buildVolumeMounts(opts: ContainerOptions): Promise<VolumeM
     mounts.push({ src: chatDir, dst: V_CONTEXT_CHAT, ro: true })
   }
 
+  // host-cli proxy: mount the host-exec socket dir so the loop's `loopat-host`
+  // forwarder can reach the host. Mounting the socket IS the trust decision —
+  // a loop with this mount may run any host cli (see host-exec.ts). The dir is
+  // created by serveHostExec at boot; mount if present (bind-try semantics).
+  const hostExec = hostExecDir()
+  if (existsSync(hostExec)) {
+    mounts.push({ src: hostExec, dst: V_HOST_EXEC_DIR })
+  }
+
   // All-loops ro view (admin-gated): expose LOOPAT_HOME/loops/ at /loopat/loops.
   if (mountAllLoops) {
     mounts.push({ src: loopsDir(), dst: V_ALL_LOOPS, ro: true })
@@ -292,6 +310,10 @@ export async function buildContainerEnv(opts: ContainerOptions): Promise<Record<
   const out: Record<string, string> = {}
   // Sandbox $HOME is /loopat/home/<user> (see V_HOME comment).
   out.HOME = V_HOME(opts.createdBy)
+  // host-cli proxy: tell the loop's `loopat-host` forwarder where the mounted
+  // socket is and which loop it speaks for (server uses it for the workdir).
+  out.LOOPAT_HOST_SOCK = V_HOST_EXEC_SOCK
+  out.LOOPAT_LOOP_ID = opts.loopId
   for (const [k, v] of Object.entries(opts.extraEnv ?? {})) {
     out[k] = v
   }
@@ -508,12 +530,17 @@ export async function probePodman(): Promise<PodmanProbeResult> {
  *  through and invalidate stale child images.
  */
 export async function baseContainerfileHash(): Promise<string> {
-  const containerfile = join(LOOPAT_INSTALL_DIR, "server", "templates", "sandbox", "Containerfile")
+  const dir = join(LOOPAT_INSTALL_DIR, "server", "templates", "sandbox")
+  const containerfile = join(dir, "Containerfile")
   if (!existsSync(containerfile)) {
     throw new Error(`Containerfile not found at ${containerfile}`)
   }
-  const content = await readFile(containerfile, "utf8")
-  return createHash("sha256").update(content).digest("hex").slice(0, 16)
+  const h = createHash("sha256").update(await readFile(containerfile, "utf8"))
+  // Files COPY'd by the Containerfile also affect the image — hash them too so
+  // editing the forwarder rebuilds the base image.
+  const forwarder = join(dir, "loopat-host")
+  if (existsSync(forwarder)) h.update(await readFile(forwarder, "utf8"))
+  return h.digest("hex").slice(0, 16)
 }
 
 let _imageBuildInFlight: Promise<void> | null = null
@@ -649,19 +676,44 @@ export async function ensureLoopImage(loopId: string, opts?: { onProgress?: (msg
     opts?.onProgress?.("Installing tools from mise.toml…")
     const buildDir = await mkdtemp(join(tmpdir(), "loopat-img-"))
     try {
-      await copyFile(miseTomlPath, join(buildDir, "mise.toml"))
+      // A loopat-native `[host]` table declares host-only clis (macOS /
+      // machine-bound) the sandbox can't run natively. We bake a forwarding
+      // shim per cli into the image's mise shims dir (already first on PATH),
+      // and strip the table before mise sees it — mise would reject the
+      // unknown table. The shim just hands off to `loopat-host` (in the base
+      // image) → mounted socket → host execFile. See host-exec.ts.
+      let hostClis: string[] = []
+      let miseConfig = content
+      try {
+        const parsed: any = tomlParse(content)
+        if (parsed && Array.isArray(parsed.host?.clis)) {
+          hostClis = parsed.host.clis.filter((x: unknown): x is string => typeof x === "string" && !!x)
+        }
+        if (parsed && "host" in parsed) {
+          const { host: _host, ...rest } = parsed
+          miseConfig = tomlStringify(rest)
+        }
+      } catch {}
+      await writeFile(join(buildDir, "mise.toml"), miseConfig)
       // Override `mise trust` interactively by marking the config path
       // trusted via env. `mise install -y` installs everything in
       // mise.toml; `mise reshim` ensures /opt/loopat-mise/shims/ has a
       // shim for every tool.
-      const childContainerfile = [
+      const lines = [
         `FROM ${SANDBOX_IMAGE}`,
         `COPY mise.toml /opt/loopat-mise/config/config.toml`,
         `RUN MISE_TRUSTED_CONFIG_PATHS=/opt/loopat-mise/config/config.toml \\`,
         `    mise install -y \\`,
         ` && MISE_TRUSTED_CONFIG_PATHS=/opt/loopat-mise/config/config.toml \\`,
         `    mise reshim`,
-      ].join("\n") + "\n"
+      ]
+      if (hostClis.length) {
+        // Generate the shims into the build context, then COPY them in AFTER
+        // reshim so mise's own reshim can't clobber them.
+        await writeHostShims(join(buildDir, "host-bin"), hostClis)
+        lines.push(`COPY host-bin/ /opt/loopat-mise/shims/`)
+      }
+      const childContainerfile = lines.join("\n") + "\n"
       await writeFile(join(buildDir, "Containerfile"), childContainerfile)
 
       const r = await runPodman(
@@ -883,17 +935,26 @@ let _portProxyReady: Promise<void> | null = null
  */
 function findOccupiedPorts(lo: number, hi: number): Set<number> {
   const ports = new Set<number>()
+  const { execFileSync } = require("node:child_process")
+  const add = (port: number) => { if (port >= lo && port <= hi) ports.add(port) }
+  // Linux: ss reads /proc/net/tcp (every listening socket).
   try {
-    const { execFileSync } = require("node:child_process")
     const out = execFileSync("ss", ["-tlnH"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }) as string
     for (const line of out.split("\n")) {
       const parts = line.trim().split(/\s+/)
       if (parts.length < 4) continue
-      const addr = parts[3] // e.g. "0.0.0.0:8080" or "[::]:8080" or "127.0.0.1:8080"
+      const addr = parts[3] // "0.0.0.0:8080" | "[::]:8080" | "127.0.0.1:8080"
       const colonIdx = addr.lastIndexOf(":")
-      if (colonIdx === -1) continue
-      const port = Number(addr.slice(colonIdx + 1))
-      if (port >= lo && port <= hi) ports.add(port)
+      if (colonIdx !== -1) add(Number(addr.slice(colonIdx + 1)))
+    }
+    return ports
+  } catch {}
+  // macOS (no ss): lsof. NAME column looks like "*:8080" or "127.0.0.1:8080 (LISTEN)".
+  try {
+    const out = execFileSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN"], { encoding: "utf8", timeout: 3000, stdio: ["ignore", "pipe", "ignore"] }) as string
+    for (const line of out.split("\n")) {
+      const m = line.match(/:(\d+)\s*\(LISTEN\)/)
+      if (m) add(Number(m[1]))
     }
   } catch {}
   return ports

package/server/src/uninstall.ts

@@ -0,0 +1,146 @@
+/**
+ * `loopat uninstall` — clean removal of everything loopat itself created.
+ *
+ * Boundary (deliberate): we remove ONLY loopat's own resources — the per-loop
+ * sandbox containers, the sandbox images, the `loopat` podman network, and the
+ * workspace data dir (LOOPAT_HOME). We do NOT touch shared infrastructure the
+ * host may use for other things — the podman machine (a Linux VM on macOS) and
+ * the npx/bun cache are only PRINTED as hints. Deleting a shared VM out from
+ * under the user would be the opposite of a clean uninstall.
+ *
+ * Containers are found by the `loopat.workspace` label (set at create time in
+ * podman.ts), not by guessing name prefixes. Shared images/network are removed
+ * only once no loopat container remains anywhere, so a second workspace on the
+ * same host isn't collateral.
+ *
+ * Run via the launcher: `npx loopat uninstall [--yes]`.
+ */
+import { existsSync } from "node:fs"
+import { rm } from "node:fs/promises"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+import { homedir } from "node:os"
+import { join } from "node:path"
+import { LOOPAT_HOME, WORKSPACE } from "./paths"
+
+const execFileP = promisify(execFile)
+
+// Stable external contract values — kept in sync with podman.ts. (These are the
+// network name, container label key, and image repo prefix; they essentially
+// never change, so a local copy avoids pulling the whole podman module in.)
+const LABEL_WORKSPACE = "loopat.workspace"
+const LOOPAT_NETWORK = "loopat"
+const IMAGE_REF = "loopat-sandbox" // base `loopat-sandbox:latest` + child `loopat-sandbox-<hash>:latest`
+
+type Run = { code: number; out: string; err: string }
+async function podman(args: string[]): Promise<Run> {
+  try {
+    const { stdout, stderr } = await execFileP("podman", args, { maxBuffer: 16 * 1024 * 1024 })
+    return { code: 0, out: stdout, err: stderr }
+  } catch (e: any) {
+    return { code: typeof e?.code === "number" ? e.code : 1, out: e?.stdout ?? "", err: e?.stderr ?? String(e?.message ?? e) }
+  }
+}
+
+const lines = (s: string) => s.split("\n").map((x) => x.trim()).filter(Boolean)
+
+async function podmanAvailable(): Promise<boolean> {
+  return (await podman(["--version"])).code === 0
+}
+
+/** Containers belonging to THIS workspace. */
+async function workspaceContainers(): Promise<string[]> {
+  const r = await podman(["ps", "-aq", "--filter", `label=${LABEL_WORKSPACE}=${WORKSPACE}`])
+  return r.code === 0 ? lines(r.out) : []
+}
+
+/** Any loopat container (any workspace) — used to decide if shared resources are still in use. */
+async function anyLoopatContainers(): Promise<string[]> {
+  const r = await podman(["ps", "-aq", "--filter", `label=${LABEL_WORKSPACE}`])
+  return r.code === 0 ? lines(r.out) : []
+}
+
+async function loopatImageIds(): Promise<string[]> {
+  const r = await podman(["images", "--filter", `reference=${IMAGE_REF}*`, "--format", "{{.ID}}"])
+  return r.code === 0 ? [...new Set(lines(r.out))] : []
+}
+
+/** TTY confirm. Non-interactive (piped) without --yes → treated as "no". */
+function confirm(question: string): boolean {
+  const ans = prompt(question)
+  return ans !== null && /^y(es)?$/i.test(ans.trim())
+}
+
+export async function runUninstall(argv: string[]): Promise<void> {
+  const yes = argv.includes("--yes") || argv.includes("-y")
+  const hasPodman = await podmanAvailable()
+  const containers = hasPodman ? await workspaceContainers() : []
+  const dataExists = existsSync(LOOPAT_HOME)
+
+  // ── Plan (so the user sees the exact boundary before anything happens) ──
+  console.log(`loopat uninstall — workspace "${WORKSPACE}"`)
+  console.log("")
+  console.log("Will remove:")
+  console.log(`  • ${containers.length} sandbox container(s)`)
+  console.log(`  • sandbox images + the "${LOOPAT_NETWORK}" network (if no loopat container remains)`)
+  console.log(`  • data dir: ${LOOPAT_HOME}${dataExists ? "" : "  (absent)"}`)
+  if (!hasPodman) console.log("  • note: podman not found — skipping container/image/network cleanup")
+  console.log("")
+
+  if (!yes && !confirm("Proceed? This permanently deletes your workspace data. [y/N] ")) {
+    console.log("Aborted — nothing removed.")
+    return
+  }
+
+  // 1. Our containers (label-scoped).
+  if (hasPodman && containers.length) {
+    process.stdout.write(`Removing ${containers.length} container(s)… `)
+    await podman(["rm", "-f", ...containers])
+    console.log("done")
+  }
+
+  // 2. Shared images + network — only when no loopat container is left anywhere.
+  if (hasPodman) {
+    const remaining = await anyLoopatContainers()
+    if (remaining.length === 0) {
+      const imgs = await loopatImageIds()
+      if (imgs.length) {
+        process.stdout.write(`Removing ${imgs.length} image(s)… `)
+        await podman(["rmi", "-f", ...imgs])
+        console.log("done")
+      }
+      if ((await podman(["network", "exists", LOOPAT_NETWORK])).code === 0) {
+        process.stdout.write(`Removing network "${LOOPAT_NETWORK}"… `)
+        await podman(["network", "rm", LOOPAT_NETWORK])
+        console.log("done")
+      }
+    } else {
+      console.log(`Keeping shared images/network — ${remaining.length} loopat container(s) from other workspaces still present.`)
+    }
+  }
+
+  // 3. Workspace data.
+  if (dataExists) {
+    process.stdout.write(`Removing data dir ${LOOPAT_HOME}… `)
+    await rm(LOOPAT_HOME, { recursive: true, force: true })
+    console.log("done")
+  }
+
+  // 4. Second-layer hints — shared infra we deliberately do NOT touch.
+  console.log("")
+  console.log("Done. loopat's own resources are gone.")
+  console.log("")
+  console.log("Left untouched (remove yourself only if loopat was their only user):")
+  if (process.platform === "darwin") {
+    console.log("  • podman machine (Linux VM):  podman machine stop && podman machine rm")
+  }
+  console.log(`  • npx/bun cache:              rm -rf ${join(homedir(), ".npm", "_npx")}`)
+  console.log("")
+}
+
+if (import.meta.main) {
+  runUninstall(process.argv.slice(2)).catch((e) => {
+    console.error(`[loopat] uninstall failed: ${e?.message ?? e}`)
+    process.exit(1)
+  })
+}

package/server/templates/sandbox/Containerfile

@@ -104,6 +104,17 @@ RUN mkdir -p /opt/loopat-mise/shims /opt/loopat-mise/config /opt/loopat-mise/cac
  && chown -R loopat:loopat /opt/loopat-mise \
  && chmod -R 755 /opt/loopat-mise
 
+# Native host-cli forwarder. The sandbox's built-in way to run a host-only cli
+# (macOS-only, or a machine-bound company cli) on behalf of the loop:
+#   shim(<cli>) → loopat-host → mounted unix socket → host execFile
+# This forwarder is generic (same for every loop), so it's baked into the image.
+# Per-cli shims are generated per-loop from the loop's mise.toml `[host].clis`
+# and COPY'd into the mise shims dir (already first on PATH) by the per-loop
+# child build (ensureLoopImage). The socket dir is mounted in and the
+# LOOPAT_HOST_SOCK / LOOPAT_LOOP_ID env vars are injected at container create.
+COPY loopat-host /usr/local/bin/loopat-host
+RUN chmod 0755 /usr/local/bin/loopat-host
+
 # Switch to loopat. mise install (per-loop child build) and runtime
 # exec'd processes all run as this user.
 USER loopat

package/server/templates/sandbox/loopat-host

@@ -0,0 +1,28 @@
+#!/bin/sh
+# loopat-host <cli> [args...] — run <cli> on the HOST, on behalf of this loop,
+# via the mounted unix socket. The sandbox can't run host-only clis (macOS
+# tools, machine-bound company clis), so a shim hands off to this forwarder.
+#
+# Injected into the sandbox:
+#   LOOPAT_HOST_SOCK  — path to the mounted host-exec socket
+#   LOOPAT_LOOP_ID    — this loop's id (server uses it to pick the host workdir)
+#
+# POC notes: args are JSON-encoded naively (assumes no embedded quotes /
+# backslashes); stdout/stderr come back base64 so they're safe to pull out of
+# the JSON with grep. A hardened version would stream and length-prefix.
+cli="$1"; shift
+args=""
+for a in "$@"; do args="$args\"$a\","; done
+body="{\"loopId\":\"$LOOPAT_LOOP_ID\",\"cli\":\"$cli\",\"args\":[${args%,}]}"
+
+resp=$(curl -fsS --unix-socket "$LOOPAT_HOST_SOCK" -X POST http://localhost/host-exec \
+  -H "content-type: application/json" -d "$body") \
+  || { echo "loopat-host: cannot reach host socket" >&2; exit 127; }
+
+printf '%s' "$resp" | grep -o '"stdout_b64":"[^"]*"' | sed 's/.*"stdout_b64":"//; s/"$//' | base64 -d 2>/dev/null
+printf '%s' "$resp" | grep -o '"stderr_b64":"[^"]*"' | sed 's/.*"stderr_b64":"//; s/"$//' | base64 -d 2>/dev/null >&2
+
+err=$(printf '%s' "$resp" | grep -o '"error":"[^"]*"' | sed 's/.*"error":"//; s/"$//')
+if [ -n "$err" ]; then echo "loopat-host: $err" >&2; exit 126; fi
+
+exit "$(printf '%s' "$resp" | grep -o '"exitCode":[0-9]*' | grep -o '[0-9]*' || echo 0)"