loopat 0.1.2 → 0.1.4

package/README.md

@@ -2,6 +2,12 @@
 
 > **Self-hosted AI workspace built around context management — works solo, scales to teams**
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/loopat"><img src="https://img.shields.io/npm/v/loopat?logo=npm&color=cb3837" alt="npm version"></a>
+  <a href="https://github.com/simpx/loopat/pkgs/container/loopat"><img src="https://img.shields.io/badge/ghcr.io-simpx%2Floopat-2496ED?logo=docker&logoColor=white" alt="GHCR image"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-green" alt="License"></a>
+</p>
+
 <p align="center">
   <img src="docs/screenshot.png" alt="loopat — Loop view with chat, workdir, terminal, and team DM" width="100%">
 </p>
@@ -131,6 +137,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.4",
   "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
@@ -91,7 +100,12 @@ const LABEL_CONFIG_HASH = "loopat.config-hash"
 
 // Image used as the base for every loop container. Built locally from
 // server/templates/sandbox/Containerfile via ensureSandboxImage().
-export const SANDBOX_IMAGE = process.env.LOOPAT_SANDBOX_IMAGE || "loopat-sandbox:latest"
+// Per-workspace image name so multiple LOOPAT_HOMEs on one host don't share
+// (and can't accidentally delete) each other's images. `uninstall` finds them
+// by the loopat.workspace label, not this name — the name only prevents tag
+// collisions. Same-Containerfile builds still share overlay layers, so the
+// per-workspace tags don't multiply disk usage.
+export const SANDBOX_IMAGE = process.env.LOOPAT_SANDBOX_IMAGE || `loopat-sandbox-${WORKSPACE}:latest`
 
 // Container name: prefix with workspace to avoid collisions between loopat
 // instances running on the same host with different LOOPAT_HOME. Loop UUIDs
@@ -247,6 +261,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 +315,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
   }
@@ -347,7 +374,7 @@ export async function buildPodmanCreateArgs(opts: ContainerOptions): Promise<str
     "--device", "/dev/fuse",
     // Shared bridge network so the serve container can reach loop
     // containers by name (aardvark-dns). Outbound API calls via NAT.
-    "--network", "loopat",
+    "--network", LOOPAT_NETWORK,
     "--hostname", `loop-${opts.loopId.slice(0, 8)}`,
     // Container cwd at creation; per-exec we override with -w.
     "--workdir", V_LOOP_WORKDIR(opts.loopId),
@@ -508,12 +535,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
@@ -527,7 +559,7 @@ export async function ensureSandboxImage(opts?: { onProgress?: (msg: string) =>
 
     // Hash the Containerfile so the base image auto-rebuilds when it changes.
     const hash = await baseContainerfileHash()
-    const hashTag = `loopat-sandbox-${hash}:latest`
+    const hashTag = `loopat-sandbox-${WORKSPACE}-${hash}:latest`
 
     const present = await runPodman(["image", "exists", hashTag], { allowFail: true })
     if (present.code === 0) {
@@ -544,7 +576,7 @@ export async function ensureSandboxImage(opts?: { onProgress?: (msg: string) =>
     const buildDir = join(LOOPAT_INSTALL_DIR, "server", "templates", "sandbox")
     let lastStep = ""
     const r = await runPodman(
-      ["build", "-t", SANDBOX_IMAGE, "-t", hashTag, "-f", containerfile, buildDir],
+      ["build", "-t", SANDBOX_IMAGE, "-t", hashTag, "--label", `${LABEL_WORKSPACE}=${WORKSPACE}`, "-f", containerfile, buildDir],
       {
         onLine: (line) => {
           const m = line.match(/^STEP\s+(\d+)\/(\d+):\s+(.+)/)
@@ -633,7 +665,7 @@ export async function ensureLoopImage(loopId: string, opts?: { onProgress?: (msg
   // after the nested-podman base change shipped).
   const baseHash = await baseContainerfileHash()
   const hash = createHash("sha256").update(`base:${baseHash}\n`).update(content).digest("hex").slice(0, 16)
-  const tag = `loopat-sandbox-${hash}:latest`
+  const tag = `loopat-sandbox-${WORKSPACE}-${hash}:latest`
 
   const existing = _loopImageInFlight.get(tag)
   if (existing) return existing
@@ -649,23 +681,48 @@ 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(
-        ["build", "-t", tag, "-f", join(buildDir, "Containerfile"), buildDir],
+        ["build", "-t", tag, "--label", `${LABEL_WORKSPACE}=${WORKSPACE}`, "-f", join(buildDir, "Containerfile"), buildDir],
         {
           allowFail: true,
           onLine: (line) => {
@@ -771,7 +828,9 @@ export async function getEphemeralHostPort(
   return Number.isFinite(port) && port > 0 ? port : null
 }
 
-const LOOPAT_NETWORK = "loopat"
+// Per-workspace network (+ loopat.workspace label) so parallel LOOPAT_HOMEs
+// stay isolated and `uninstall` removes only its own.
+const LOOPAT_NETWORK = `loopat-${WORKSPACE}`
 const SERVE_CONTAINER = `loopat-${WORKSPACE}-serve`
 
 let _networkReady = false
@@ -783,7 +842,7 @@ export async function ensureLoopatNetwork(): Promise<void> {
   const r = await runPodman(["network", "exists", LOOPAT_NETWORK], { allowFail: true })
   if (r.code !== 0) {
     console.log(`[podman] creating network ${LOOPAT_NETWORK}`)
-    const create = await runPodman(["network", "create", LOOPAT_NETWORK])
+    const create = await runPodman(["network", "create", "--label", `${LABEL_WORKSPACE}=${WORKSPACE}`, LOOPAT_NETWORK])
     if (create.code !== 0) {
       throw new Error(`Failed to create podman network ${LOOPAT_NETWORK}: ${create.stderr}`)
     }
@@ -883,17 +942,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,133 @@
+/**
+ * `loopat uninstall` — clean removal of everything THIS workspace created.
+ *
+ * Every loopat resource is workspace-scoped: containers, images, and the
+ * network all carry a `loopat.workspace=<ws>` label, and the data dir IS this
+ * workspace's LOOPAT_HOME. So uninstall removes only its own — even when other
+ * LOOPAT_HOMEs exist on the same host, there's no cross-workspace collateral.
+ *
+ * Shared host infrastructure loopat merely uses — the podman machine (a Linux
+ * VM on macOS) and the npx/bun cache — is only PRINTED as a hint, never
+ * touched. Deleting a shared VM out from under the user would be the opposite
+ * of a clean uninstall.
+ *
+ * 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)
+
+// The label every loopat container/image/network carries (set at create/build
+// time in podman.ts). Deleting by label is exact — no name-prefix ambiguity
+// (e.g. workspace "foo" vs "foobar").
+const LABEL_WORKSPACE = "loopat.workspace"
+const labelFilter = `label=${LABEL_WORKSPACE}=${WORKSPACE}`
+
+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
+}
+
+async function workspaceContainers(): Promise<string[]> {
+  const r = await podman(["ps", "-aq", "--filter", labelFilter])
+  return r.code === 0 ? lines(r.out) : []
+}
+async function workspaceImageIds(): Promise<string[]> {
+  const r = await podman(["images", "--filter", labelFilter, "--format", "{{.ID}}"])
+  return r.code === 0 ? [...new Set(lines(r.out))] : []
+}
+async function workspaceNetworks(): Promise<string[]> {
+  const r = await podman(["network", "ls", "--filter", labelFilter, "--format", "{{.Name}}"])
+  return r.code === 0 ? 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 images = hasPodman ? await workspaceImageIds() : []
+  const networks = hasPodman ? await workspaceNetworks() : []
+  const dataExists = existsSync(LOOPAT_HOME)
+
+  // ── Plan (the user sees the exact boundary before anything happens) ──
+  console.log(`loopat uninstall — workspace "${WORKSPACE}"`)
+  console.log("")
+  console.log("Will remove (this workspace only):")
+  console.log(`  • ${containers.length} sandbox container(s)`)
+  console.log(`  • ${images.length} sandbox image(s)`)
+  console.log(`  • ${networks.length} network(s)${networks.length ? ` (${networks.join(", ")})` : ""}`)
+  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 this workspace's data. [y/N] ")) {
+    console.log("Aborted — nothing removed.")
+    return
+  }
+
+  // Every resource below is label-scoped to THIS workspace — no shared-resource
+  // guessing, so other workspaces on the host are never touched.
+  if (hasPodman && containers.length) {
+    process.stdout.write(`Removing ${containers.length} container(s)… `)
+    await podman(["rm", "-f", ...containers])
+    console.log("done")
+  }
+  if (hasPodman && images.length) {
+    // rmi by image ID removes this workspace's tags; shared overlay layers
+    // stay alive (refcounted) for any other workspace still using them.
+    process.stdout.write(`Removing ${images.length} image(s)… `)
+    await podman(["rmi", "-f", ...images])
+    console.log("done")
+  }
+  for (const net of networks) {
+    process.stdout.write(`Removing network "${net}"… `)
+    await podman(["network", "rm", net])
+    console.log("done")
+  }
+  if (dataExists) {
+    process.stdout.write(`Removing data dir ${LOOPAT_HOME}… `)
+    await rm(LOOPAT_HOME, { recursive: true, force: true })
+    console.log("done")
+  }
+
+  // Second-layer hints — shared infra we deliberately do NOT touch.
+  console.log("")
+  console.log("Done. This workspace's resources are gone.")
+  console.log("")
+  console.log("Left untouched (shared host infra — 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)
+  })
+}