@madarco/agentbox 0.4.1 → 0.5.0

package/runtime/relay/bin.cjs

@@ -10381,6 +10381,110 @@ var RELAY_EVENT_RING_SIZE = 1e3;
 var import_node_child_process = require("child_process");
 var import_node_http = require("http");
 
+// src/prompts.ts
+var import_node_crypto = require("crypto");
+var PendingPrompts = class {
+  entries = /* @__PURE__ */ new Map();
+  add(boxId, ev) {
+    return new Promise((resolve2) => {
+      this.entries.set(ev.id, {
+        ev,
+        boxId,
+        resolve: resolve2,
+        createdAt: (/* @__PURE__ */ new Date()).toISOString()
+      });
+    });
+  }
+  /**
+   * Idempotent: returns true if a pending entry was found + resolved, false
+   * otherwise. The /admin/prompts/answer handler uses the bool to decide
+   * 204 vs 404 — the wrapper treats both as "we're done."
+   */
+  resolve(id, answer, cancelled) {
+    const entry = this.entries.get(id);
+    if (!entry) return false;
+    this.entries.delete(id);
+    entry.resolve({ answer, cancelled });
+    return true;
+  }
+  /**
+   * Snapshot of all pending prompts for a given box; used to flush the
+   * backlog to a newly-attached SSE subscriber.
+   */
+  forBox(boxId) {
+    const out = [];
+    for (const entry of this.entries.values()) {
+      if (entry.boxId === boxId) out.push(entry.ev);
+    }
+    return out;
+  }
+  /** boxId that owns a pending prompt id, or null when unknown. */
+  boxFor(id) {
+    const entry = this.entries.get(id);
+    return entry ? entry.boxId : null;
+  }
+  size() {
+    return this.entries.size;
+  }
+};
+var PromptSubscribers = class {
+  byBox = /* @__PURE__ */ new Map();
+  add(boxId, res) {
+    let set = this.byBox.get(boxId);
+    if (!set) {
+      set = /* @__PURE__ */ new Set();
+      this.byBox.set(boxId, set);
+    }
+    set.add(res);
+  }
+  remove(boxId, res) {
+    const set = this.byBox.get(boxId);
+    if (!set) return;
+    set.delete(res);
+    if (set.size === 0) this.byBox.delete(boxId);
+  }
+  forBox(boxId) {
+    const set = this.byBox.get(boxId);
+    return set ? Array.from(set) : [];
+  }
+  /**
+   * Fire-and-forget broadcast. SSE writes that fail (closed socket) are
+   * swallowed — the `res.on('close')` handler in the server route already
+   * deregisters the dead subscriber.
+   */
+  broadcast(boxId, event, data) {
+    const set = this.byBox.get(boxId);
+    if (!set) return;
+    const payload = `event: ${event}
+data: ${JSON.stringify(data)}
+
+`;
+    for (const res of set) {
+      try {
+        res.write(payload);
+      } catch {
+      }
+    }
+  }
+};
+async function askPrompt(prompts, subscribers, boxId, params) {
+  if (process.env.AGENTBOX_PROMPT === "off") {
+    return { answer: "y" };
+  }
+  const ev = { id: (0, import_node_crypto.randomUUID)(), ...params };
+  const promise = prompts.add(boxId, ev);
+  subscribers.broadcast(boxId, "prompt-ask", ev);
+  return promise;
+}
+function isPromptAnswerBody(v) {
+  if (!v || typeof v !== "object") return false;
+  const o = v;
+  if (typeof o.id !== "string" || o.id.length === 0) return false;
+  if (o.answer !== "y" && o.answer !== "n") return false;
+  if (o.cancelled !== void 0 && typeof o.cancelled !== "boolean") return false;
+  return true;
+}
+
 // src/registry.ts
 var BoxRegistry = class {
   map = /* @__PURE__ */ new Map();
@@ -10447,8 +10551,16 @@ var EventBuffer = class {
 var import_promises = require("fs/promises");
 var import_node_os = require("os");
 var import_node_path = require("path");
-function boxStatusPathFor(boxId) {
-  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".agentbox", "boxes", boxId, "status.json");
+function sanitizeMnemonic(raw) {
+  return raw.toLowerCase().replace(/-/g, "_").replace(/[^a-z0-9_]+/g, "_").replace(/_+/g, "_").replace(/^_+|_+$/g, "").slice(0, 32) || "unnamed";
+}
+function boxRunDirFor(boxId, name, projectIndex) {
+  const mnemonic = sanitizeMnemonic(name);
+  const segment = typeof projectIndex === "number" && Number.isFinite(projectIndex) && projectIndex > 0 ? `${boxId}-${String(projectIndex)}-${mnemonic}` : `${boxId}-${mnemonic}`;
+  return (0, import_node_path.join)((0, import_node_os.homedir)(), ".agentbox", "boxes", segment);
+}
+function boxStatusPathFor(boxId, name, projectIndex) {
+  return (0, import_node_path.join)(boxRunDirFor(boxId, name, projectIndex), "status.json");
 }
 function isValidBoxStatus(payload) {
   if (typeof payload !== "object" || payload === null) return false;
@@ -10460,13 +10572,19 @@ var BoxStatusStore = class {
   get(boxId) {
     return this.map.get(boxId);
   }
-  /** Update the in-memory entry and best-effort persist it to disk. */
-  async set(boxId, status) {
+  /**
+   * Update the in-memory entry and best-effort persist it to disk. `name` is
+   * the box's user-facing name (from the registry); `projectIndex` is the
+   * 1-based per-project `N`. Together they form the on-disk dir
+   * `~/.agentbox/boxes/<id>-<n>-<mnemonic>/status.json` (or
+   * `<id>-<mnemonic>/` if N is absent — legacy boxes).
+   */
+  async set(boxId, name, projectIndex, status) {
     this.map.set(boxId, status);
-    const target = boxStatusPathFor(boxId);
+    const target = boxStatusPathFor(boxId, name, projectIndex);
     const tmp = `${target}.${String(process.pid)}.tmp`;
     try {
-      await (0, import_promises.mkdir)((0, import_node_path.join)((0, import_node_os.homedir)(), ".agentbox", "boxes", boxId), { recursive: true });
+      await (0, import_promises.mkdir)(boxRunDirFor(boxId, name, projectIndex), { recursive: true });
       await (0, import_promises.writeFile)(tmp, JSON.stringify(status), "utf8");
       await (0, import_promises.rename)(tmp, target);
     } catch {
@@ -10485,6 +10603,9 @@ var BOX_STATUS_EVENT = "box-status";
 var MAX_BODY_BYTES = 1024 * 1024;
 var GIT_RPC_TIMEOUT_MS = 12e4;
 var CHECKPOINT_RPC_TIMEOUT_MS = 6e5;
+var DOWNLOAD_RPC_TIMEOUT_MS = 6e5;
+var CP_RPC_TIMEOUT_MS = 3e5;
+var SSE_HEARTBEAT_MS = 15e3;
 function send(res, status, body, contentType = "application/json") {
   const text = body == null ? "" : typeof body === "string" ? body : JSON.stringify(body);
   res.statusCode = status;
@@ -10540,6 +10661,8 @@ function createRelayServer(opts) {
   const registry = new BoxRegistry();
   const events = new EventBuffer();
   const statusStore = new BoxStatusStore();
+  const prompts = new PendingPrompts();
+  const subscribers = new PromptSubscribers();
   const host = opts.host ?? "0.0.0.0";
   const server = (0, import_node_http.createServer)((req, res) => {
     handle(req, res).catch((err) => {
@@ -10575,7 +10698,7 @@ function createRelayServer(opts) {
           send(res, 400, { error: "invalid box-status payload" });
           return;
         }
-        await statusStore.set(reg.boxId, body.payload);
+        await statusStore.set(reg.boxId, reg.name, reg.projectIndex, body.payload);
         log(`box-status box=${reg.boxId}`);
         send(res, 202, { ok: true });
         return;
@@ -10599,12 +10722,78 @@ function createRelayServer(opts) {
         return;
       }
       log(`rpc box=${reg.boxId} method=${body.method}`);
-      if (body.method === "git.pull" || body.method === "git.push") {
+      if (body.method === "git.push" || body.method === "git.fetch") {
+        if (body.method === "git.push") {
+          const params = body.params;
+          const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
+            kind: "confirm",
+            message: `Allow git push from box ${reg.name}?`,
+            detail: `${params?.remote ?? "origin"} ${(params?.args ?? []).join(" ")}`.trim(),
+            defaultAnswer: "n",
+            context: {
+              command: "git push",
+              cwd: params?.path,
+              argv: params?.args
+            }
+          });
+          if (verdict.answer !== "y") {
+            send(res, 500, { exitCode: 10, stdout: "", stderr: "denied by user\n" });
+            return;
+          }
+        }
         const result = await handleGitRpc(reg, body.method, body.params);
         const status = result.exitCode === 0 ? 200 : 500;
         send(res, status, result);
         return;
       }
+      if (body.method === "cp.toHost" || body.method === "cp.fromHost") {
+        const params = body.params;
+        if (!params || typeof params.boxPath !== "string" || typeof params.hostPath !== "string") {
+          send(res, 400, { error: "cp.* requires {boxPath, hostPath} strings" });
+          return;
+        }
+        const direction = body.method === "cp.toHost" ? "box -> host" : "host -> box";
+        const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
+          kind: "confirm",
+          message: `Allow cp (${direction}) on ${reg.name}?`,
+          detail: body.method === "cp.toHost" ? `${params.boxPath} -> ${params.hostPath}` : `${params.hostPath} -> ${params.boxPath}`,
+          defaultAnswer: "n",
+          context: {
+            command: body.method,
+            argv: [params.boxPath, params.hostPath]
+          }
+        });
+        if (verdict.answer !== "y") {
+          send(res, 500, { exitCode: 10, stdout: "", stderr: "denied by user\n" });
+          return;
+        }
+        const result = await handleCpRpc(reg, body.method, params);
+        const status = result.exitCode === 0 ? 200 : 500;
+        send(res, status, result);
+        return;
+      }
+      if (body.method === "download.workspace" || body.method === "download.env" || body.method === "download.config" || body.method === "download.claude") {
+        const params = body.params;
+        const kind = body.method.split(".")[1] ?? "workspace";
+        const verdict = await askPrompt(prompts, subscribers, reg.boxId, {
+          kind: "confirm",
+          message: `Allow download (${kind}) from ${reg.name}?`,
+          detail: params?.hostPath ?? "(default host location)",
+          defaultAnswer: "n",
+          context: {
+            command: body.method,
+            argv: params?.hostPath ? [params.hostPath] : []
+          }
+        });
+        if (verdict.answer !== "y") {
+          send(res, 500, { exitCode: 10, stdout: "", stderr: "denied by user\n" });
+          return;
+        }
+        const result = await handleDownloadRpc(reg, kind);
+        const status = result.exitCode === 0 ? 200 : 500;
+        send(res, status, result);
+        return;
+      }
       if (body.method === "checkpoint.create") {
         const result = await handleCheckpointRpc(
           reg,
@@ -10629,6 +10818,7 @@ function createRelayServer(opts) {
         return;
       }
       const worktrees = sanitizeWorktrees(body.worktrees);
+      const projectIndex = typeof body.projectIndex === "number" && Number.isFinite(body.projectIndex) && body.projectIndex > 0 ? Math.trunc(body.projectIndex) : void 0;
       const reg = {
         boxId: body.boxId,
         token: body.token,
@@ -10636,6 +10826,7 @@ function createRelayServer(opts) {
         registeredAt: (/* @__PURE__ */ new Date()).toISOString(),
         containerName: typeof body.containerName === "string" && body.containerName.length > 0 ? body.containerName : void 0,
         createdAt: typeof body.createdAt === "string" && body.createdAt.length > 0 ? body.createdAt : void 0,
+        projectIndex,
         worktrees
       };
       registry.register(reg);
@@ -10681,11 +10872,66 @@ function createRelayServer(opts) {
         registeredAt: r.registeredAt,
         containerName: r.containerName,
         createdAt: r.createdAt,
+        projectIndex: r.projectIndex,
         worktrees: r.worktrees ?? []
       }));
       send(res, 200, { boxes: redacted });
       return;
     }
+    if (route === "GET /admin/prompts/stream") {
+      const boxId = url.searchParams.get("boxId") ?? "";
+      if (boxId.length === 0) {
+        send(res, 400, { error: "missing boxId query param" });
+        return;
+      }
+      res.statusCode = 200;
+      res.setHeader("Content-Type", "text/event-stream");
+      res.setHeader("Cache-Control", "no-cache");
+      res.setHeader("Connection", "keep-alive");
+      res.setHeader("X-Accel-Buffering", "no");
+      if (typeof res.flushHeaders === "function") res.flushHeaders();
+      res.write(": connected\n\n");
+      subscribers.add(boxId, res);
+      for (const ev of prompts.forBox(boxId)) {
+        res.write(`event: prompt-ask
+data: ${JSON.stringify(ev)}
+
+`);
+      }
+      const heartbeat = setInterval(() => {
+        try {
+          res.write(`event: ping
+data: {"ts":"${(/* @__PURE__ */ new Date()).toISOString()}"}
+
+`);
+        } catch {
+        }
+      }, SSE_HEARTBEAT_MS);
+      if (typeof heartbeat.unref === "function") heartbeat.unref();
+      res.on("close", () => {
+        clearInterval(heartbeat);
+        subscribers.remove(boxId, res);
+      });
+      return;
+    }
+    if (route === "POST /admin/prompts/answer") {
+      const body = await readJsonBody(req);
+      if (!isPromptAnswerBody(body)) {
+        send(res, 400, { error: 'expected {id, answer:"y"|"n", cancelled?}' });
+        return;
+      }
+      const targetBox = prompts.boxFor(body.id);
+      const hit = prompts.resolve(body.id, body.answer, body.cancelled);
+      if (!hit) {
+        send(res, 404, { error: "no pending prompt with that id" });
+        return;
+      }
+      if (targetBox) {
+        subscribers.broadcast(targetBox, "prompt-resolved", { id: body.id });
+      }
+      send(res, 204, null);
+      return;
+    }
     send(res, 404, { error: "not found", route });
   }
   function authBox(req, res, reg) {
@@ -10706,6 +10952,8 @@ function createRelayServer(opts) {
     registry,
     events,
     statusStore,
+    prompts,
+    subscribers,
     url: `http://${host}:${String(opts.port)}`,
     close: () => new Promise((resolve2, reject) => {
       server.close((err) => {
@@ -10719,10 +10967,10 @@ function sanitizeWorktrees(input) {
   if (!Array.isArray(input)) return void 0;
   const out = [];
   for (const w of input) {
-    if (w && typeof w.containerPath === "string" && typeof w.hostWorktreeDir === "string" && typeof w.branch === "string") {
+    if (w && typeof w.containerPath === "string" && typeof w.hostMainRepo === "string" && typeof w.branch === "string") {
       out.push({
         containerPath: w.containerPath,
-        hostWorktreeDir: w.hostWorktreeDir,
+        hostMainRepo: w.hostMainRepo,
         branch: w.branch
       });
     }
@@ -10747,9 +10995,9 @@ async function handleGitRpc(reg, method, params) {
       stderr: `no worktree registered for box ${reg.boxId} matching ${containerPath}`
     };
   }
-  const op = method === "git.pull" ? "pull" : "push";
+  const op = method === "git.push" ? "push" : "fetch";
   const remote = params?.remote ?? "origin";
-  const argv = ["git", "-C", worktree.hostWorktreeDir, op, remote];
+  const argv = ["git", "-C", worktree.hostMainRepo, op, remote, worktree.branch];
   if (Array.isArray(params?.args)) {
     for (const a of params.args) {
       if (typeof a === "string") argv.push(a);
@@ -10757,6 +11005,33 @@ async function handleGitRpc(reg, method, params) {
   }
   return runHostCommand(argv);
 }
+async function handleCpRpc(reg, method, params) {
+  const entry = process.env.AGENTBOX_CLI_ENTRY;
+  if (!entry) {
+    return {
+      exitCode: 64,
+      stdout: "",
+      stderr: "relay: AGENTBOX_CLI_ENTRY not set; cannot run cp host-side"
+    };
+  }
+  const boxRef = `${reg.name}:${params.boxPath}`;
+  const argv = method === "cp.toHost" ? [process.execPath, entry, "cp", boxRef, params.hostPath] : [process.execPath, entry, "cp", params.hostPath, boxRef];
+  return runHostCommand(argv, CP_RPC_TIMEOUT_MS);
+}
+async function handleDownloadRpc(reg, kind) {
+  const entry = process.env.AGENTBOX_CLI_ENTRY;
+  if (!entry) {
+    return {
+      exitCode: 64,
+      stdout: "",
+      stderr: "relay: AGENTBOX_CLI_ENTRY not set; cannot run download host-side"
+    };
+  }
+  const argv = [process.execPath, entry, "download"];
+  if (kind !== "workspace") argv.push(kind);
+  argv.push(reg.name, "-y");
+  return runHostCommand(argv, DOWNLOAD_RPC_TIMEOUT_MS);
+}
 async function handleCheckpointRpc(reg, params) {
   const entry = process.env.AGENTBOX_CLI_ENTRY;
   if (!entry) {
@@ -10770,6 +11045,7 @@ async function handleCheckpointRpc(reg, params) {
   if (params?.name) argv.push("--name", params.name);
   if (params?.merged === true) argv.push("--merged");
   if (params?.setDefault === true) argv.push("--set-default");
+  if (params?.replace === true) argv.push("--replace");
   return runHostCommand(argv, CHECKPOINT_RPC_TIMEOUT_MS);
 }
 function runHostCommand(argv, timeoutMs = GIT_RPC_TIMEOUT_MS) {

package/share/agentbox-setup/SKILL.md

@@ -5,7 +5,21 @@ description: Generate an agentbox.yaml for the current AgentBox workspace. Invok
 
 # /agentbox-setup
 
-Goal: produce a `/workspace/agentbox.yaml` that captures this project's services, tasks, and box defaults so the in-box supervisor (`agentbox-ctl`) can boot the workspace deterministically.
+## Box layout (what you're configuring against)
+
+Your user i `vscode` and you can use passwordless sudo to run commands as root.
+
+`/workspace` is the box's plain writable filesystem — a per-box git worktree on a fresh `agentbox/<box-name>` branch (or a tar-piped copy of the host workspace for non-git projects). Anything you install or build into `/workspace` (incl. `node_modules`, `.next`, `target`, `.venv`) lives in the **container's writable layer** and is captured wholesale by `agentbox checkpoint` (`docker commit`) — so a setup task that runs the install once becomes a warm-start asset for every future box in the project. Everything is wiped on `agentbox destroy`.
+
+Three bind mounts wire the box back to the host:
+
+- **Host main repo's `.git/`** — bind-mounted RW at its identical absolute host path. In-box commits land on the host's branch refs (visible to `git log` on the host immediately); the box itself carries no SSH/git creds, so `git push` goes through the host relay (`agentbox-ctl git push`). The host's **working tree is never written to** — only refs/objects under `.git/`.
+- **`~/.claude`** — a Docker named volume (`agentbox-claude-config`, shared across boxes by default) seeded from the host's `~/.claude` on each create so auth, skills, and plugins persist without leaking the host's home dir.
+- **`agentbox.yaml`** — read by `agentbox-ctl` from `/workspace`. Tasks and services declared here are what the supervisor will run.
+
+## Goal
+
+Produce a `/workspace/agentbox.yaml` that captures this project's services, tasks, and box defaults so the in-box supervisor (`agentbox-ctl`) can boot the workspace deterministically.
 
 `agentbox.yaml` is **declarative**. The supervisor reads it on box start, but you don't have to restart the box: after you write the file, `agentbox-ctl reload` (run from inside the box) makes the already-running supervisor re-read it and immediately run the declared tasks and autostart the services. See step 8.
 
@@ -23,10 +37,12 @@ Look at `/workspace`:
 ## 2. Pick services and tasks
 
 - **Services** = long-running. Web servers, watchers, queue workers, databases. `restart: on-failure` by default.
-- **Tasks** = one-shot. `pnpm install`, DB migrations, codegen, fixture loaders. Wire dependent services with `needs:` so they wait for the task to finish successfully.
+- **Tasks** = one-shot. `pnpm install`, DB migrations, codegen, fixture loaders, install apt packages. Wire dependent services with `needs:` so they wait for the task to finish successfully.
 - Names: must match `[A-Za-z0-9_-]+`. Task names and service names share a namespace — no collisions.
 - No cycles in `needs:`.
-- **Always generate a dependency-install task** and make it the root of the `needs:` graph (every service that needs deps gets `needs: [install, …]`). The box runs on Linux; the host's `node_modules` (and `.next`, `target`, `.venv`) are macOS-native and now live in the box's writable upper layer, so they must be rebuilt **inside** the box. The task must be **idempotent and self-healing**: `agentbox-ctl` re-runs pending tasks on every box stop/start (the daemon dies with the container and is relaunched), so a plain `rm -rf node_modules && install` would wipe + reinstall on every start. Guard the rebuild with a marker file *inside* `node_modules` (the `.agentbox-installed` convention AgentBox uses internally): rebuild only when the marker is absent (fresh box, or a stale host-leaked `node_modules`), and be a fast no-op once it exists. Detect the package manager from the lockfile — never hardcode `pnpm`. See the worked example below.
+- **Always generate a dependency-install task** and make it the root of the `needs:` graph (every service that needs deps gets `needs: [install, …]`). Future boxes start from a snapshot of the final filesystem so they won't need this, but updates or moving to a cloud provider might need to rebuild the container from scratch. The filesystem can be then later captured by `agentbox-ctl checkpoint --set-default`. The task must be **idempotent and self-healing**: `agentbox-ctl` re-runs pending tasks on every box stop/start (the daemon dies with the container and is relaunched), so a plain `rm -rf node_modules && install` would wipe + reinstall on every start. Guard the rebuild with a marker file *inside* `node_modules` (the `.agentbox-installed` convention AgentBox uses internally): rebuild only when the marker is absent (fresh box), and be a fast no-op once it exists. Detect the package manager from the lockfile — never hardcode `pnpm`. See the worked example below.
+- **Add a comment to the beginning** of the file to explain what you did and what issues you encountered, so that future run might use this information in case the project evolves and you need to update the agentbox.yaml file.
+-
 
 ## 3. Wire readiness probes (services only)
 
@@ -61,7 +77,7 @@ Per service:
 
 Sets per-project defaults for `agentbox create`/`claude`/`code`/`shell` — same shape as `~/.agentbox/config.yaml`. CLI flags still override. Common keys:
 
-- `box.hostSnapshot` (bool) — frozen APFS clone of the *host* workspace as overlay lower (renamed from `box.snapshot`).
+- `box.hostSnapshot` (bool) — APFS-clone the *host* workspace into a per-box scratch dir before seeding `/workspace` (stabilizes the tar-pipe source).
 - `box.defaultCheckpoint` (string) — checkpoint new boxes start from (normally you set this via `agentbox-ctl checkpoint --set-default` at the end of setup — see section 9, not by hand).
 - `box.withPlaywright` (bool) — install `@playwright/cli` globally inside the box.
 - `box.vnc` (bool) — run Xvnc + noVNC on container port 6080.
@@ -76,6 +92,11 @@ Full key list (run on the host): `agentbox config list --keys`.
 
 ```yaml
 # yaml-language-server: $schema=https://agentbox.dev/schema/agentbox.schema.json
+# This agentbox.yaml setup this Next.js project, and includes:
+# - a postgres database because it's used in the project
+# - an inngest server for queues
+# - a fix to move .turbo/cache folder to the workspace to avoid a permission error during setup
+# - ...
 defaults:
   box:
     withPlaywright: true
@@ -83,30 +104,23 @@ defaults:
     ide: cursor
 
 tasks:
-  # Idempotent install. node_modules lives in the box's writable upper layer
-  # (per-box, isolated, captured by `agentbox open --upper`). The host's
-  # node_modules is macOS-native, so force a clean Linux build the first time
-  # and self-heal a stale one — but skip on every subsequent box start
-  # (agentbox-ctl re-runs pending tasks after stop/start). Adjust the
-  # lockfile detection to the project's package manager.
+  # Idempotent install. /workspace is the container's writable filesystem, so
+  # node_modules persists across pause/stop/start and is captured by
+  # `agentbox checkpoint`. The host's node_modules is macOS-native and is
+  # never copied in, so force a clean Linux build the first time — but skip
+  # on every subsequent box start (agentbox-ctl re-runs pending tasks after
+  # stop/start). Adjust the lockfile detection to the project's package
+  # manager.
   install:
     command: |
       set -e
       MARKER=node_modules/.agentbox-installed
       [ -f "$MARKER" ] && { echo "deps installed (marker present) — skip"; exit 0; }
+      apt-get update && apt-get install -y postgresql-client
       rm -rf node_modules
       if [ -f pnpm-lock.yaml ]; then
         corepack enable >/dev/null 2>&1 || true
         pnpm install --frozen-lockfile || pnpm install
-      elif [ -f yarn.lock ]; then
-        corepack enable >/dev/null 2>&1 || true
-        yarn install --frozen-lockfile || yarn install
-      elif [ -f bun.lockb ] || [ -f bun.lock ]; then
-        bun install
-      elif [ -f package-lock.json ]; then
-        npm ci || npm install
-      else
-        npm install
       fi
       touch "$MARKER"
 
@@ -149,44 +163,19 @@ services:
 1. Write the file to `/workspace/agentbox.yaml`.
 2. **Apply it live**: from inside the box run `agentbox-ctl reload`. The already-running supervisor re-reads the config and immediately runs the declared tasks and autostarts the services — no box restart needed. It prints the `added` / `removed` / `changed` diff. If it errors because the daemon isn't running, the config is still valid: the next `agentbox start` (or `agentbox create` in this workspace) picks it up automatically.
 3. Confirm with `agentbox-ctl status`: tasks should be `running` or `done`, autostart services `starting` or `ready`. If something failed, tail it with `agentbox-ctl logs <service>` and fix the config, then `agentbox-ctl reload` again.
-
-4. **Then do section 9** — once the box is warmed up (deps installed, services ready), checkpoint it with `agentbox-ctl checkpoint --set-default` so future boxes start ready. This is the real final step; don't stop at hand-off.
+4. Checkpoint (snapshot) this box writable layer: once the box is warmed up (deps installed, services ready), checkpoint it with `agentbox-ctl checkpoint --set-default` so future boxes start ready.
 
 5. Tell the user:
 
    > I wrote `/workspace/agentbox.yaml` and ran `agentbox-ctl reload` so the supervisor is already running the declared tasks/services. To land the file on the host:
    > - I've created a checkpoint of the warm box state so future boxes start ready in seconds, no reinstall.
    > - commit it inside the box (`git add agentbox.yaml && git commit -m 'add agentbox config'`) — the box's `.git/` is bind-mounted, so the commit shows up on the host immediately; or
-   > - on the host, tell the user to run `agentbox pull config` to update their original host workspace.
-
-
-## 9. Checkpoint the warm state (do this at the very end)
-
-Once `agentbox-ctl status` shows the install task `done` and services `ready` — i.e. the box is fully warmed up — capture a **checkpoint** so future boxes in this project start from this exact state instead of cold.
+   > - on the host, tell the user to run `agentbox download config` to update their original host workspace.
 
-A checkpoint snapshots the box's writable layer, which includes everything you just did:
-
-- `node_modules` (and `.next`, `target`, `.venv`, build caches) — the expensive Linux-native install,
-- `.env` / `.env.*` / `secrets.toml` and any other gitignored config files present in `/workspace`,
-- any other files written during setup.
-
-A new box created from the checkpoint reuses all of it (the install task's marker is already present, so it no-ops), while git-tracked code still comes fresh from the host's current HEAD. Result: new boxes are ready in seconds with no reinstall and no missing env vars.
-
-**Run this from inside the box, as the final step:**
-
-```sh
-agentbox-ctl checkpoint --set-default
-```
-
-This routes through the host relay (no host shell needed), captures `<box-name>-<n>`, and writes `box.defaultCheckpoint` into the project's config so **every future `agentbox create` / `claude` in this project starts warm automatically**. Pass `--name <name>` for a stable name, or omit `--set-default` to capture without changing the default. Re-run it whenever the warm state meaningfully changes (e.g. after a dependency bump you want every new box to inherit).
-
-Then tell the user, e.g.:
-
-> I checkpointed the warm box state (node_modules, env files, build caches) and set it as this project's default — `agentbox create` will now spin up new boxes from it in seconds, no reinstall.
-
-## 10. Known issues
+## 9. Known issues
 
 - For Nextjs/Vite/Tasnstack projects, makes sure to forward also websocket for hot reload.
-- **Turbo/Nx/Jest and other git-worktree-aware tools may try to write their cache to a read-only host path.** The box runs `/workspace` as a git worktree with the host repo's `.git/` bind-mounted at its absolute host path; tools that derive paths from git (Turbo's cache root = the worktree's git *common dir*) resolve outside `/workspace` and hit `EROFS` on the Mac path. Pin the cache into the writable overlay via the task/service `env:`, e.g. `TURBO_CACHE_DIR: /workspace/.turbo/cache` (or pass `--cache-dir`).
+
 - The `install` task is intentionally a no-op once `node_modules/.agentbox-installed` exists. Do **not** remove the marker guard to "force a fresh install" — that reinstalls on every box start. To force a one-off rebuild, delete `node_modules` (or just the marker) then run `agentbox-ctl reload`.
-- `.pnpm-store` default location is read only, so you need to point it to a writable location in the box's writable workspace eg: `PNPM_STORE: /workspace/.pnpm-store` and add `.pnpm-store/` to the `.gitignore` if the workspace root is git-tracked.
+
+- Host-only CLI wrappers (portless, etc.) must be bypassed, eg some projects wrap the dev server with a host-side proxy (here: `portless projectname next dev --turbopack`). Override the service command: to call the underlying tool directly (`next dev --turbopack`)