@madarco/agentbox 0.4.1 → 0.6.0

package/dist/{lifecycle-LURNDNYO-UWQYPNPX.js → lifecycle-EMXR46DI-DUVBXNTV.js}

@@ -13,12 +13,12 @@ import {
   startBox,
   stopBox,
   unpauseBox
-} from "./chunk-FQD6ZWYW.js";
+} from "./chunk-M7I247BK.js";
 import {
   SNAPSHOTS_ROOT
-} from "./chunk-NSIECUCS.js";
-import "./chunk-IDR4HVIC.js";
-import "./chunk-SOMIKEN2.js";
+} from "./chunk-HTTKML3C.js";
+import "./chunk-HPZMD5DE.js";
+import "./chunk-HHMWQNLF.js";
 export {
   AmbiguousBoxError,
   BoxNotFoundError,
@@ -35,4 +35,4 @@ export {
   stopBox,
   unpauseBox
 };
-//# sourceMappingURL=lifecycle-LURNDNYO-UWQYPNPX.js.map
+//# sourceMappingURL=lifecycle-EMXR46DI-DUVBXNTV.js.map

package/dist/{state-ZSP3ORXW-WI6KOIG3.js → state-KD7M46ZP-KHFTHFUS.js}

@@ -10,7 +10,7 @@ import {
   removeBoxRecord,
   resolveBoxRef,
   writeState
-} from "./chunk-IDR4HVIC.js";
+} from "./chunk-HPZMD5DE.js";
 export {
   STATE_DIR,
   STATE_FILE,
@@ -23,4 +23,4 @@ export {
   resolveBoxRef,
   writeState
 };
-//# sourceMappingURL=state-ZSP3ORXW-WI6KOIG3.js.map
+//# sourceMappingURL=state-KD7M46ZP-KHFTHFUS.js.map

package/dist/stats-SZXOJE3D-N7OODCHW.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import {
+  agentboxHomeBytes,
+  allCheckpointImagesBytes,
+  boxResourceStats,
+  parseDockerSize,
+  projectCheckpointImageBytes,
+  volumeSizeBytes
+} from "./chunk-BBZMA2K6.js";
+import "./chunk-HHMWQNLF.js";
+export {
+  agentboxHomeBytes,
+  allCheckpointImagesBytes,
+  boxResourceStats,
+  parseDockerSize,
+  projectCheckpointImageBytes,
+  volumeSizeBytes
+};
+//# sourceMappingURL=stats-SZXOJE3D-N7OODCHW.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@madarco/agentbox",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Launch Claude Code, Codex, and other coding agents in isolated sandboxes",
   "license": "MIT",
   "author": "Marco D'Alia",
@@ -57,8 +57,9 @@
     "vitest": "^2.1.8",
     "@agentbox/config": "0.0.0",
     "@agentbox/core": "0.0.0",
+    "@agentbox/ctl": "0.0.0",
     "@agentbox/sandbox-docker": "0.0.0",
-    "@agentbox/ctl": "0.0.0"
+    "@agentbox/relay": "0.0.0"
   },
   "scripts": {
     "build": "tsup",

package/runtime/docker/Dockerfile.box

@@ -2,12 +2,17 @@
 #
 # Layered on Microsoft's devcontainers base:ubuntu (arm64-native — the
 # `universal:2-linux` image is amd64-only, which is a non-starter on Apple
-# Silicon hosts). We add the bits the box needs to mount a FUSE overlay over
-# /host-src + /upper, plus a "universal-ish" set of language runtimes
-# (Node.js 22 from NodeSource, Python 3 from apt). Anything heavier (Go, Java,
-# Ruby, .NET, browser tooling, vscode-server) goes in a later iteration.
+# Silicon hosts). /workspace is a plain dir in the image's writable layer:
+# `agentbox create` populates it via in-container `git worktree add` (or a
+# tar pipe for the no-git case). The old FUSE overlay over /host-src+/upper
+# is gone — but fuse3 + fuse-overlayfs stay as the in-box dockerd's fallback
+# storage driver (it prefers the kernel-native overlay2). Plus the "universal-ish" set of
+# language runtimes (Node.js 22 from NodeSource, Python 3 from apt). Heavier
+# tooling (Go, Java, Ruby, .NET, more browser tooling, vscode-server) goes in
+# a later iteration.
 #
-# Required runtime flags:
+# Required runtime flags (SYS_ADMIN + /dev/fuse + apparmor:unconfined are now
+# load-bearing only for the *inner* dockerd — keep them):
 #     --cap-add=SYS_ADMIN --device=/dev/fuse --security-opt=apparmor:unconfined
 #
 # Pinned to ubuntu-24.04 (Noble), NOT the rolling `:ubuntu` tag: that tag now
@@ -67,9 +72,9 @@ RUN apt-get update \
         vim \
         libcap2-bin \
     && rm -rf /var/lib/apt/lists/* \
-    && mkdir -p /workspace /host-src /upper /snapshot /run/agentbox /var/log/agentbox \
-    && chmod 755 /workspace /host-src /upper /snapshot \
-    && chown vscode:vscode /run/agentbox /var/log/agentbox
+    && mkdir -p /workspace /run/agentbox /var/log/agentbox \
+    && chmod 755 /workspace \
+    && chown vscode:vscode /workspace /run/agentbox /var/log/agentbox
 
 # The in-box supervisor (runs as non-root `vscode`) owns a TCP forwarder that
 # binds container :80 -> the `expose:`-flagged service (see WebProxy /
@@ -79,6 +84,19 @@ RUN apt-get update \
 # sandbox — strictly narrower than the existing NET_ADMIN/seccomp=unconfined.
 RUN setcap cap_net_bind_service=+ep "$(readlink -f "$(command -v node)")"
 
+# Enable corepack (pnpm/yarn shims) at build time as root. Doing this here
+# rather than in the wizard's install task avoids two failures the runtime
+# `corepack enable` (run as non-root `vscode`) hits: it can't write shims into
+# the root-owned NodeSource bin dir (/usr/bin), and node 22's bundled corepack
+# resolves its dist path relative to the symlink dirname, so a
+# ~/.local/bin/pnpm symlink looks for ~/.local/dist/pnpm.js and breaks.
+# `corepack@latest` fixes the symlink resolution; baking the shims into
+# /usr/bin makes them root-owned-but-world-executable so `vscode` just uses
+# them (each project's `packageManager` version is lazily fetched into the
+# writable ~/.cache/node/corepack on first use, inside the install task).
+RUN npm install -g corepack@latest \
+    && corepack enable pnpm yarn
+
 # Host repos are bind-mounted in at their identical absolute path (worktree
 # pointer files contain absolute paths to <main>/.git/worktrees/<name>, so both
 # sides have to resolve the same path), and the host owns those `.git/` dirs.
@@ -87,13 +105,15 @@ RUN setcap cap_net_bind_service=+ep "$(readlink -f "$(command -v node)")"
 # bind-mount of ~/.gitconfig from the host.
 RUN git config --system --add safe.directory '*'
 
-# Docker-in-Docker. dockerd inside the box (storage-driver=fuse-overlayfs, set
-# in /etc/docker/daemon.json) lets the agent run `docker build`/`docker run`
-# in its own namespace without exposing the host daemon. fuse-overlayfs is
-# required because the kernel `overlay` driver isn't usable from an
-# unprivileged container — but fuse3 + fuse-overlayfs are already installed
-# above for the /workspace overlay, so docker reuses them. iptables is needed
-# for inner-container bridge networking. Adding `vscode` to the `docker` group
+# Docker-in-Docker. dockerd inside the box lets the agent run
+# `docker build`/`docker run` in its own namespace without exposing the host
+# daemon. The storage driver is NOT pinned here: agentbox-dockerd-start picks
+# it at runtime — the kernel-native overlay2 when a probe proves it works on
+# the data-root filesystem, else the fuse-overlayfs fallback (fuse3 +
+# fuse-overlayfs are installed above for that fallback). The baked daemon.json
+# only carries `iptables: true`; the script rewrites it with the resolved
+# `storage-driver` before launching dockerd. iptables is needed for
+# inner-container bridge networking. Adding `vscode` to the `docker` group
 # lets the agent invoke `docker` without sudo once dockerd creates the socket
 # at /var/run/docker.sock at runtime. The matching launch script is COPY'd in
 # below; the daemon is started by the host via `docker exec -d --user root`
@@ -104,7 +124,7 @@ RUN apt-get update \
         iptables \
     && rm -rf /var/lib/apt/lists/* \
     && mkdir -p /etc/docker \
-    && printf '%s\n' '{ "storage-driver": "fuse-overlayfs", "iptables": true }' > /etc/docker/daemon.json \
+    && printf '%s\n' '{ "iptables": true }' > /etc/docker/daemon.json \
     && usermod -aG docker vscode
 
 # agentbox-ctl: the in-container supervisor + CLI. Build context is the
@@ -114,12 +134,13 @@ RUN apt-get update \
 COPY packages/ctl/dist/bin.cjs /usr/local/bin/agentbox-ctl
 RUN chmod +x /usr/local/bin/agentbox-ctl
 
-# Setup guide for the first-run wizard. The CLI also installs the same file as
-# a host-side claude skill (~/.claude/skills/agentbox-setup/SKILL.md) the
-# first time the wizard fires; the existing ~/.claude rsync flow propagates
-# it into every box automatically. Keeping a copy baked into the image at a
-# stable path guarantees the wizard's initial prompt can reference the guide
-# even on hosts where the user wiped their ~/.claude/skills.
+# Setup guide for the first-run wizard. This baked copy is the single source
+# of the /agentbox-setup skill: seedSetupSkillIntoVolume()
+# (packages/sandbox-docker/src/claude.ts) copies it into the box's
+# claude-config volume at skills/agentbox-setup/SKILL.md on create /
+# `claude start`. It is intentionally box-only — the CLI never writes the
+# skill to the host's ~/.claude. The stable path also lets the wizard's
+# initial prompt reference the guide directly.
 COPY apps/cli/share/agentbox-setup/SKILL.md /usr/local/share/agentbox/setup-guide.md
 RUN chmod 0644 /usr/local/share/agentbox/setup-guide.md
 
@@ -256,6 +277,25 @@ RUN chmod +x /usr/local/bin/agentbox-vnc-start
 COPY packages/sandbox-docker/scripts/agentbox-dockerd-start /usr/local/bin/agentbox-dockerd-start
 RUN chmod +x /usr/local/bin/agentbox-dockerd-start
 
+# Pre-`docker commit` cleanup for checkpoints. Baked into the image so the host
+# can always reach it via `docker exec --user root <ctr>
+# /usr/local/bin/agentbox-checkpoint-cleanup` regardless of the in-box state
+# (e.g. an agent that swapped its login shell). Best-effort: every step is
+# allowed to fail.
+COPY packages/sandbox-docker/scripts/agentbox-checkpoint-cleanup /usr/local/bin/agentbox-checkpoint-cleanup
+RUN chmod +x /usr/local/bin/agentbox-checkpoint-cleanup
+
+# Host-routed link opener. The box has no real browser; this wrapper forwards
+# http(s) URLs to the host's default browser via the relay (`agentbox-ctl
+# open`). It shadows xdg-utils' /usr/bin/xdg-open (the symlink lands earlier
+# in PATH) and is set as $BROWSER so any tool that opens a link — Claude
+# Code's OAuth flow, `gh`, `git web--browse`, python's webbrowser — routes
+# to the host.
+COPY packages/sandbox-docker/scripts/agentbox-open /usr/local/bin/agentbox-open
+RUN chmod +x /usr/local/bin/agentbox-open \
+    && ln -sf /usr/local/bin/agentbox-open /usr/local/bin/xdg-open
+ENV BROWSER=/usr/local/bin/agentbox-open
+
 # tmux config so Claude's true-color output and OSC 8 hyperlinks survive the
 # in-container tmux. `terminal-features` is a no-op on tmux < 3.4. Without
 # this, claude renders without 24-bit color (logo invisible) and hyperlinks
@@ -315,8 +355,8 @@ RUN printf '%s\n' \
         > /etc/profile.d/agentbox.sh \
     && chmod 0644 /etc/profile.d/agentbox.sh
 
-# Default to the vscode user (UID 1000) provided by base:ubuntu. The overlay
-# mount itself happens via `docker exec --user root`, so this is just the
-# default identity for interactive shells.
+# Default to the vscode user (UID 1000) provided by base:ubuntu. /workspace is
+# pre-chowned to vscode above so `agentbox create`'s in-container
+# `git worktree add` (run as vscode via docker exec) can write to it.
 USER vscode
 WORKDIR /workspace

package/runtime/docker/apps/cli/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"
 
@@ -144,49 +158,32 @@ services:
 - A service with `restart: never` and an autostart dependency will block the dependent forever after one failed run — usually a mistake.
 - `command:` is either a shell string (run via `bash -c`) or an argv array. Use the argv form if you need to avoid shell quoting.
 
-## 8. Hand-off
-
-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.
-
-5. Tell the user:
+## 8. Checkpoint the warm state (do this at the very end)
 
-   > 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.
+Checkpoint (snapshot) this box writable layer: once the box is warmed up (deps installed, services ready), checkpoint it with `agentbox-ctl checkpoint --name setup --replace --set-default` so future boxes start ready.
+Run this command exactly once. The `--name setup --replace` makes it idempotent — if it ever needs to run again it overwrites the existing `setup` checkpoint instead of stacking duplicates.
+This doesn't need to be confirmed by the user.
+It will pause the container for several seconds so warn the user about it and write Done when it's done.
 
+## 9. Hand-off
 
-## 9. Checkpoint the warm state (do this at the very end)
+Tell the user (verbatim):
 
-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.
+   ```
+    █████╗  ██████╗ ███████╗███╗   ██╗████████╗██████╗  ██████╗ ██╗  ██╗
+   ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔══██╗██╔═══██╗╚██╗██╔╝
+   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝██║   ██║ ╚███╔╝
+   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗██║   ██║ ██╔██╗
+   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██████╔╝╚██████╔╝██╔╝ ██╗
+   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═════╝  ╚═════╝ ╚═╝  ╚═╝
+   ```
 
-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.
+   your box is ready, you can start more sessions with `agentbox claude`
 
 ## 10. 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`)