@madarco/agentbox 0.13.0 → 0.15.0

package/runtime/docker/packages/sandbox-docker/scripts/agentbox-vnc-start

@@ -23,10 +23,22 @@ mkdir -p "$HOME/.vnc"
 # VncAuth truncates >8 chars at compare time, which is fine — the host writes
 # an 8-char password. Write to a temp file + rename so a failure (e.g.,
 # vncpasswd missing) doesn't leave an empty file that Xvnc would then reject.
-TMP_PASSWD="$(mktemp "$HOME/.vnc/passwd.XXXXXX")"
-printf '%s\n' "$PASS" | vncpasswd -f > "$TMP_PASSWD"
-chmod 600 "$TMP_PASSWD"
-mv "$TMP_PASSWD" "$HOME/.vnc/passwd"
+#
+# Debian 12 (E2B base) doesn't package vncpasswd at all — tigervnc-tools is
+# Ubuntu-only. When vncpasswd is missing, fall back to `-SecurityTypes None`
+# and rely on the cloud provider's signed preview URL as the access boundary
+# (same effective model: holding the URL = holding the credential). Other
+# providers (docker, hetzner, daytona, vercel) keep VncAuth.
+VNC_SECURITY_ARGS=(-SecurityTypes VncAuth -PasswordFile "$HOME/.vnc/passwd")
+if command -v vncpasswd >/dev/null 2>&1; then
+  TMP_PASSWD="$(mktemp "$HOME/.vnc/passwd.XXXXXX")"
+  printf '%s\n' "$PASS" | vncpasswd -f > "$TMP_PASSWD"
+  chmod 600 "$TMP_PASSWD"
+  mv "$TMP_PASSWD" "$HOME/.vnc/passwd"
+else
+  echo "agentbox-vnc-start: vncpasswd not installed; starting Xvnc with -SecurityTypes None (preview URL is the access boundary)" >&2
+  VNC_SECURITY_ARGS=(-SecurityTypes None)
+fi
 
 mkdir -p /var/log/agentbox 2>/dev/null || true
 
@@ -37,8 +49,7 @@ mkdir -p /var/log/agentbox 2>/dev/null || true
 # accept cut-text from noVNC, set both the X CLIPBOARD and PRIMARY selections.
 Xvnc :1 \
   -localhost \
-  -SecurityTypes VncAuth \
-  -PasswordFile "$HOME/.vnc/passwd" \
+  "${VNC_SECURITY_ARGS[@]}" \
   -geometry 1280x800 \
   -depth 24 \
   -AlwaysShared \

package/runtime/docker/packages/sandbox-docker/scripts/chromium-resolver

@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+# agentbox: resolve the Chromium that agent-browser drives.
+#
+# We deliberately do NOT bake a Chromium into the box image. Playwright pins an
+# exact Chromium build per playwright version, so a baked browser goes stale the
+# moment a project pins a different Playwright — the project's `playwright
+# install` then fetches a *different* build, and anything waiting on the baked
+# one (a hard-coded ms-playwright path) hangs forever. Instead we reuse the
+# *project's* Playwright Chromium — the exact build its own tests use — so
+# agent-browser and Playwright share a single binary that is always correct.
+#
+# `AGENT_BROWSER_EXECUTABLE_PATH=/usr/local/bin/chromium` points at this script,
+# so every agent-browser launch runs it. Resolution is effectively cached: once
+# a build exists the hot path is just an `ls` + `exec` (no download).
+#
+#   1. newest installed Playwright Chromium under ~/.cache/ms-playwright; else
+#   2. install one with the project's pinned Playwright (matching build), or the
+#      box's global Playwright as a fallback when the project has none; then
+#   3. exec the real binary with the args agent-browser passed.
+#
+# Chrome-for-Testing has no linux/arm64 build and Noble's chromium apt package
+# is a snap stub, so Playwright's downloader stays the only reliable cross-arch
+# source — we just invoke it lazily, with the project's version, instead of
+# baking a fixed one.
+
+newest_chrome() {
+  ls -d "$HOME"/.cache/ms-playwright/chromium-*/chrome-linux*/chrome 2>/dev/null | sort -V | tail -1
+}
+
+real="$(newest_chrome)"
+if [ -z "$real" ]; then
+  echo "agentbox: no Chromium yet; installing via Playwright (one-time)..." >&2
+  # Serialize concurrent first-launches: without a lock, two simultaneous
+  # agent-browser launches would both run `playwright install` into the same
+  # ~/.cache/ms-playwright, and one could exec a half-extracted binary. flock
+  # makes the second waiter re-check the cache and skip the redundant install.
+  mkdir -p "$HOME/.cache" 2>/dev/null
+  exec 9>"$HOME/.cache/agentbox-chromium-install.lock"
+  flock 9
+  real="$(newest_chrome)" # another launch may have installed it while we waited
+  if [ -z "$real" ]; then
+    if [ -x /workspace/node_modules/.bin/playwright ]; then
+      ( cd /workspace && ./node_modules/.bin/playwright install chromium ) >&2
+    else
+      playwright install chromium >&2
+    fi
+    real="$(newest_chrome)"
+  fi
+  flock -u 9
+fi
+
+if [ -z "$real" ] || [ ! -x "$real" ]; then
+  echo "agentbox: could not resolve a Chromium binary (Playwright install failed?)." >&2
+  exit 127
+fi
+
+exec "$real" "$@"

package/runtime/docker/packages/sandbox-docker/scripts/claude-managed-settings.json

@@ -1,5 +1,6 @@
 {
-  "$comment": "AgentBox enterprise-managed Claude Code settings, baked into the box image at /etc/claude-code/managed-settings.json. Highest precedence and NOT synced from the host ~/.claude, so claude-hooks-filter.ts never touches it; per Claude Code, hook arrays MERGE across settings sources, so the user's own hooks still run. These hooks report Claude's activity to the box supervisor (agentbox-ctl claude-state -> ctl socket -> relay -> ~/.agentbox/boxes/<id>/status.json) so `agentbox status/list/inspect` can show it even when the box is paused. Each command is exit-0 fast and shell-backgrounded so a hook can never block or fail a Claude turn. The ExitPlanMode / AskUserQuestion entries run SYNCHRONOUSLY (no &) because they consume the hook's stdin payload; the catchall PreToolUse 'working' hook races with them, but the supervisor's sticky-state semantics swallow that race (a 'working' set while in end-plan/question is ignored unless --clear-pending is set, which only the matching PostToolUse hook passes).",
+  "$comment": "AgentBox enterprise-managed Claude Code settings, baked into the box image at /etc/claude-code/managed-settings.json. Highest precedence and NOT synced from the host ~/.claude, so claude-hooks-filter.ts never touches it; per Claude Code, hook arrays MERGE across settings sources, so the user's own hooks still run. These hooks report Claude's activity to the box supervisor (agentbox-ctl claude-state -> ctl socket -> relay -> ~/.agentbox/boxes/<id>/status.json) so `agentbox status/list/inspect` can show it even when the box is paused. Each command is exit-0 fast and shell-backgrounded so a hook can never block or fail a Claude turn. The ExitPlanMode / AskUserQuestion entries run SYNCHRONOUSLY (no &) because they consume the hook's stdin payload; the catchall PreToolUse 'working' hook races with them, but the supervisor's sticky-state semantics swallow that race (a 'working' set while in end-plan/question is ignored unless --clear-pending is set, which only the matching PostToolUse hook passes). skipDangerousModePermissionPrompt pre-accepts the bypass-permissions disclaimer at policy precedence — AgentBox boxes are isolated, and `agentbox claude` defaults to --dangerously-skip-permissions, so the one-time accept gate would just trap every fresh box.",
+  "skipDangerousModePermissionPrompt": true,
   "hooks": {
     "UserPromptSubmit": [
       {

package/runtime/e2b/agentbox-checkpoint-cleanup

@@ -0,0 +1,52 @@
+#!/usr/bin/env bash
+# Pre-`docker commit` cleanup: strip ephemeral / disposable state so the
+# captured checkpoint image is closer to "warm project state, nothing else".
+#
+# Invoked by the host via `docker exec --user root <container>
+# /usr/local/bin/agentbox-checkpoint-cleanup` right before
+# `docker commit`. Best-effort: every step is allowed to fail (a checkpoint
+# capture should never block on cleanup hiccups).
+#
+# What we DELIBERATELY keep:
+#   - /workspace                  the actual point of the checkpoint
+#   - /home/vscode/.npm           warm npm cache (next install is fast)
+#   - /home/vscode/.cache         pnpm/yarn/Cargo/etc. caches
+#   - /var/lib/docker             in-box dockerd's data root
+#   - /home/vscode/.claude        the named volume is bind-mounted; image
+#                                 layer never sees it anyway
+set +e
+
+# apt: drop downloaded .deb cache and the package index. The index is ~50MB
+# and gets refreshed on the next `apt-get update`; the .deb cache is reusable
+# only if we don't change versions, which we usually do.
+apt-get clean 2>/dev/null
+rm -rf /var/lib/apt/lists/* 2>/dev/null
+
+# Throwaway scratch dirs. Preserve /tmp/claude-* — that is the live in-box
+# Claude Code session's working tree (its per-task stdout/stderr files). The
+# agent that triggered this checkpoint *is* that session; deleting its task
+# output mid-run makes its harness see ENOENT, treat the command as failed,
+# and retry the checkpoint (observed: 5 duplicate auto-named checkpoints).
+# Stale claude-* dirs baked into the image are tiny and Claude Code prunes
+# them itself on the next session start.
+find /tmp /var/tmp -mindepth 1 -maxdepth 1 ! -name 'claude-*' -exec rm -rf {} + 2>/dev/null
+
+# Logs: truncate (don't delete) so the original file modes / ownerships stay
+# intact for the next run. Targets common rotated archives too.
+find /var/log -type f \( -name '*.log' -o -name '*.gz' -o -name '*.1' \) \
+  -exec truncate -s0 {} + 2>/dev/null
+find /var/log/agentbox -type f -exec truncate -s0 {} + 2>/dev/null
+
+# Bash history (root + vscode). Re-assert vscode ownership: `: >` run as root
+# (re)creates the file root-owned 0644 when it didn't exist, which the uid-1000
+# vscode user cannot append to, silently dropping all shell history.
+: > /root/.bash_history 2>/dev/null
+: > /home/vscode/.bash_history 2>/dev/null
+chown vscode:vscode /home/vscode/.bash_history 2>/dev/null
+chmod 600 /home/vscode/.bash_history 2>/dev/null
+
+# Anthropic's installer writes a transient marker; redundant once the binary
+# is in place. Safe to wipe.
+rm -rf /home/vscode/.claude-installer 2>/dev/null
+
+exit 0

package/runtime/e2b/agentbox-codex-hooks.json

@@ -0,0 +1,68 @@
+{
+  "$comment": "Codex 0.134.0 expects `~/.codex/hooks.json` to be `{ hooks: { Event: [...] } }` (matching the `HooksFile` Rust struct), NOT a top-level event map. The `hooks` feature flag must also be enabled (`codex --enable hooks`) and hook trust must be either persisted via the in-TUI dialog or bypassed at launch (`--dangerously-bypass-hook-trust`). startCodexSession() does both. In practice the hook firing on the JSON-config path is still unreliable in 0.134.0 (TUI mode skips them on at least some startup paths) — the real mechanism that lights up state in production is the tmux-pane scraper in packages/ctl/src/codex-scraper.ts. These hooks remain as a defense-in-depth seed so any future codex build that fixes the firing also lights up state without further work.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state waiting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state compacting >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state working >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+        ]
+      }
+    ]
+  }
+}

package/runtime/e2b/agentbox-open

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Routes in-box URL opens to `agentbox-ctl open`, which opens the link in the
+# box's own Chromium (agent-browser, visible via `agentbox screen`) and asks
+# the host user — in the footer/dashboard — whether to also open it on the
+# host. This script is installed at /usr/local/bin (earlier in PATH than
+# xdg-utils' /usr/bin/xdg-open, which it is also symlinked over) and is the
+# box's $BROWSER, so `xdg-open`, Claude Code's OAuth flow, `gh`,
+# `git web--browse`, python's webbrowser, etc. all land here.
+#
+# Only http(s) URLs are routed. Anything else (a file path, another scheme)
+# falls through to the real xdg-open, which resolves it locally in the box.
+
+set -uo pipefail
+
+target="${1:-}"
+
+case "$target" in
+  http://* | https://*)
+    exec agentbox-ctl open "$target"
+    ;;
+  *)
+    if [[ -x /usr/bin/xdg-open ]]; then
+      exec /usr/bin/xdg-open "$@"
+    fi
+    echo "agentbox-open: not an http(s) URL: $target" >&2
+    exit 1
+    ;;
+esac

package/runtime/e2b/agentbox-setup-skill.md

@@ -0,0 +1,263 @@
+---
+name: agentbox-setup
+description: Generate an agentbox.yaml for the current AgentBox workspace. Invoke when the user opens a sandbox without an agentbox.yaml or asks to (re)configure one.
+---
+
+# /agentbox-setup
+
+## Box layout (what you're configuring against)
+
+Your user i `vscode` and you can use `sudo` to run commands as root.
+
+`/workspace` is where the user code lives, 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).
+Run `agentbox checkpoint --set-default` (similar to `docker commit`) to save any changes make to the system and workspace so that new boxes will start from a warm state. Everything is wiped on `agentbox destroy`.
+
+Some special folders:
+
+- **Host main repo's `.git/`** — If the box 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/`. GitHub PR ops (`agentbox-ctl git pr create|view|list|comment|review|merge|close|reopen|checkout`) flow the same way through host `gh`; write ops require host confirmation (deny → exit 10), `merge` and `checkout` have additional opt-in guards.
+- **`~/.claude`** — and similar home folders for coding agents are 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.
+
+Exposed ports and services:
+- **portless** - every port with `expose:` setting in agentbox.yaml, will be exposed not only as a local port but also as a special domain name `https://<name>.localhost` (so on https) using `portless` cli and proxy. This will be also mapped to the host where also `portless` proxy is running so users can access the same service on the same looking url.
+- **vnc** - the webVNC server exposed on 6080 will be proxies to the host on a random port.
+- **vscode** - the vscode server is proxied to the host on a random port.
+
+## 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.
+
+## 1. Discover the project
+
+Look at `/workspace`:
+
+- Top-level manifests: `package.json`, `pyproject.toml` / `requirements.txt`, `Cargo.toml`, `go.mod`, `Gemfile`, `composer.json`, `mix.exs`, etc. — these tell you the runtime.
+- `docker-compose.yaml` / `docker-compose.yml` — often lists the real services the project expects.
+- `package.json` → `scripts`: look for `dev`, `start`, `build`, `test`, `migrate`, `seed`.
+- `Makefile` / `justfile` / `Taskfile.yaml` — alternative task runners.
+- Listening ports: grep for `listen(`, `PORT=`, framework defaults (3000 for Next.js / Nuxt, 5173 for Vite, 8000 for Django, 8080 for Spring, etc.).
+- Database / cache deps to spin up locally (Postgres, Redis, …) — declare them as services if the project doesn't expect them to be external.
+
+## 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, 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, …]`). 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.
+
+### Stateful services: data persistence & re-seeding (read this for databases)
+
+**A checkpoint does NOT capture docker-in-docker data.** `agentbox checkpoint` is a `docker commit` of the box's writable filesystem (the system + `/workspace`). The in-box `dockerd` keeps its storage in a *separate* per-box volume (`/var/lib/docker`), which is **not** part of that image — it's fresh on every new box and wiped on `agentbox destroy`. So a database or cache you run as a **docker container** (e.g. `docker run … postgres`) starts **empty on every new box** created from a checkpoint (every `agentbox claude` / `agentbox create`), even though `/workspace` and any marker files you wrote were restored. (A DB run as a **native process** with its data dir on the box filesystem — e.g. `postgres -D /var/lib/postgresql/data` — *is* captured by the checkpoint, since it lives in the writable layer.)
+
+**Consequence for migrate/seed tasks of a containerized DB: do not gate them on a filesystem marker.** A marker like `node_modules/.agentbox-installed` is correct for deps (they live in `/workspace`, which the checkpoint captures), but **wrong** for DB data living in a docker volume: the marker is restored from the checkpoint while the DB is empty, so a marker-guarded seed wrongly skips and the app boots against an empty database. Instead, **gate on the actual data** — connect to the DB and check whether a sentinel table/row exists, and seed only when it's missing:
+
+```yaml
+  seed:
+    # Re-seed when the DB is empty. The postgres data lives in the in-box
+    # docker volume, which is NOT captured by `agentbox checkpoint` — so a box
+    # started from a checkpoint has the workspace warm but an empty DB. We can't
+    # use a filesystem marker here (it would be restored while the DB is blank);
+    # instead probe the DB and seed only if the data is absent. Fast no-op once
+    # the data is present.
+    command: |
+      set -e
+      export PGPASSWORD=postgres
+      # Probe for existing data. If the table is missing the query errors,
+      # stderr is suppressed, stdout is empty, the grep fails — so we seed.
+      if psql -h 127.0.0.1 -p 5432 -U postgres -d app -tAc \
+          "SELECT EXISTS (SELECT 1 FROM users LIMIT 1)" 2>/dev/null | grep -q t; then
+        echo "data present — skip seed"
+        exit 0
+      fi
+      pnpm db:seed
+    needs: [install, migrate]
+```
+
+**Lifecycle nuance (this is why the data check, not a marker, is right):**
+
+- **Box stop → start** (`agentbox stop`/`start`): the supervisor daemon dies with the container and is relaunched, so it **re-runs all tasks** from `pending`. The per-box docker volume *does* survive stop/start, so the DB still has data — the data check makes the seed a fast no-op.
+- **New box from a checkpoint** (`agentbox claude`/`create`): tasks run and the DB volume is empty → the check fails → the seed runs. Correct.
+- **Resume after pause** (`agentbox pause`/`unpause`): the daemon is frozen and thawed, **not** restarted, so tasks do **not** re-run at all — nothing to seed, the running DB is untouched.
+
+(Migrations are usually safe to re-run as-is: migration tools track applied migrations in their own table, which on a fresh box is empty, so they simply re-apply. Only the *data* seed needs the existence check.) Install the DB client the seed/migrate tasks need (e.g. `postgresql-client`) in the `install` task — don't `docker exec` the DB container for these checks (nested `docker exec` fails inside a box with a `setns` error); reach it over TCP with the client tools instead.
+
+## 3. Wire readiness probes (services only)
+
+`ready_when:` lets the supervisor decide when a service is "ready" (vs. just "running"). Exactly one of these must be present:
+
+- `port: 3000` — TCP connect (default host `127.0.0.1`; override with `host:`).
+- `log_match: "Listening on"` — regex matched against stdout/stderr. First match flips the service to ready.
+- `http: "http://127.0.0.1:3000/health"` — GET probe. Optional `expect_status: 200` (default: any 2xx).
+
+Tunables: `interval_ms` (default 500), `initial_delay_ms` (default 0), `timeout_ms` (default 60000), `on_timeout: kill | mark_unhealthy` (default `kill` — re-enters the restart policy).
+
+### Mark the web service with `expose:`
+
+The box's primary web app (the dev server / Next.js / API the user opens in a browser) should declare:
+
+```yaml
+    expose:
+      port: 3000   # the port this service listens on inside the box
+      as: 80        # must be 80 — the container port AgentBox publishes
+```
+
+At most **one** service may set `expose:`. AgentBox forwards container `:80` to `127.0.0.1:<port>` and publishes it on the host with `portless` proxy to a <boxname>.localhost url, so `agentbox list`/`status` show it as the box's main URL on every engine (no OrbStack dependency). Set this on the same service whose `ready_when:` you just wrote (a DB or worker should **not** get `expose:`).
+
+## 4. Restart + backoff
+
+Per service:
+
+- `restart: always | on-failure | never` (default `on-failure`).
+- `backoff:` — `initial_ms` (default 500), `max_ms` (default 30000; must be `>= initial_ms`), `factor` (default 2).
+
+## 5. (Optional) `defaults:` block
+
+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) — 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.
+- `box.isolateClaudeConfig` (bool) — per-box `~/.claude` volume instead of the shared one.
+- `code.ide` — `vscode | cursor | auto`.
+- `code.autoTerminals` (bool) — auto-generate `.vscode/tasks.json` with per-service tails.
+- `browser.default` — `agent-browser | playwright | both`.
+
+Full key list (run on the host): `agentbox config list --keys`.
+
+## 6. Worked example
+
+```yaml
+# yaml-language-server: $schema=https://agent-box.sh/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
+  code:
+    ide: cursor
+
+tasks:
+  # 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
+      fi
+      touch "$MARKER"
+
+  migrate:
+    command: pnpm db:migrate
+    needs: [install]
+
+services:
+  postgres:
+    command: postgres -D /var/lib/postgresql/data
+    ready_when:
+      port: 5432
+    restart: always
+
+  dev:
+    command: pnpm dev
+    needs: [install, migrate, postgres]
+    ready_when:
+      port: 3000
+      timeout_ms: 120000
+    expose:
+      port: 3000
+      as: 80
+    restart: on-failure
+    backoff:
+      initial_ms: 500
+      max_ms: 5000
+      factor: 2
+```
+
+## 6b. Bringing extra host files/folders into the box
+
+Two ways to copy host files in (both COPY — never a live mount, so the box can't
+write back to the host):
+
+- **`carry:` block** (declarative, in `agentbox.yaml`) — for files/dirs every box
+  should get at create time. Each entry is `{ src, dest }` with optional `mode`,
+  `user`, `optional`, and `exclude:` (a list of tar globs / bare dir names to drop
+  when copying a directory). Heavy regenerable dirs (`.git`, `node_modules`, `bin`,
+  `obj`, `packages`, `dist`, `.next`, `target`) are dropped by default; `exclude:`
+  is additive. Each carry entry is capped at `box.cpMaxBytes` (default 100 MiB
+  after excludes) — the same limit `agentbox cp` enforces.
+- **`agentbox-ctl cp fromHost <hostPath> <boxPath>`** (ad-hoc, from inside the box)
+  — for a one-off copy. Prompts the user on the host to approve.
+
+**The per-copy size limit (important for large/legacy folders).** A single copy is
+blocked above `box.cpMaxBytes` (default **100 MB**) *after* default excludes, so it
+fails loud instead of silently hanging. When blocked you get a `du`-style tree of
+the biggest remaining folders/subfolders. To get under the limit, EITHER:
+
+- **drop what the box can regenerate** (the default excludes already remove
+  `node_modules`/`.git`/build output; add more with `--exclude=<glob-or-name>`), OR
+- **copy the heavy folders one at a time** so each copy is under the limit, OR
+- pass `--yes` to copy the whole thing anyway (only when you really need it all).
+
+Example: a 2.4 GB legacy folder is mostly `packages/` (NuGet) + `.git`; those are
+excluded by default, and what's left can be split:
+`agentbox-ctl cp fromHost ../legacy/src /workspace/legacy/src` then
+`... cp fromHost ../legacy/Database /workspace/legacy/Database`.
+
+## 7. Validate before handing off
+
+- check with `agentbox-ctl reload` and then `agentbox-ctl status` that everything is running as expected.
+- Every name in `needs:` must reference an existing task or service.
+- 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
+
+Tell the user (verbatim):
+
+   ```
+    █████╗  ██████╗ ███████╗███╗   ██╗████████╗██████╗  ██████╗ ██╗  ██╗
+   ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔══██╗██╔═══██╗╚██╗██╔╝
+   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝██║   ██║ ╚███╔╝
+   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗██║   ██║ ██╔██╗
+   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██████╔╝╚██████╔╝██╔╝ ██╗
+   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═════╝  ╚═════╝ ╚═╝  ╚═╝
+   ```
+
+   your box is ready, you can start more sessions with `agentbox claude`
+   you can access the web app at https://<boxname>.localhost
+
+
+## 9. Checkpoint the warm state - DON't SKIP THIS STEP
+
+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.
+Remember the checkpoint captures the writable layer (`/workspace` + system), **not** docker-in-docker volumes — so a containerized DB's data does not carry into new boxes. That's expected; the data-existence-gated seed task from section 2 re-seeds those automatically. (If you need the data itself to persist into new boxes, run the DB as a native process with its data dir on the box filesystem, or bind a `/workspace` path as the container's data volume so it lands in the checkpoint.)
+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.
+On all providers except Vercel, 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.
+On Vercel: this actually STOPS the sandbox, so warn the user about it. Also the system will ask confirmation.
+
+## 10. Known issues
+
+- For Nextjs/Vite/Tasnstack projects, makes sure to forward also websocket for hot reload.
+
+- Service like flask, nextjs, BETTER_AUTH_URL, NEXT_PUBLIC_APP_URL should use the <boxname>.localhost url for the local development so that on the host it will use the same url as the box.
+
+- 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`.

package/runtime/e2b/agentbox-vnc-start

@@ -0,0 +1,102 @@
+#!/usr/bin/env bash
+# Start the per-box VNC stack: Xvnc on :1 (loopback inside container) +
+# websockify on 0.0.0.0:6080 serving noVNC's HTML5 client and proxying RFB.
+# Launched by the host via `docker exec -d --user vscode` after the container
+# is up. Idempotent — re-running while the daemons are alive is a no-op, so
+# `agentbox start` can blindly call us again.
+
+set -euo pipefail
+
+PASS="${AGENTBOX_VNC_PASSWORD:-}"
+if [[ -z "$PASS" ]]; then
+  echo "agentbox-vnc-start: AGENTBOX_VNC_PASSWORD is not set" >&2
+  exit 64
+fi
+
+if pgrep -u "$(id -u)" -x Xvnc >/dev/null \
+   && pgrep -u "$(id -u)" -f "websockify.*6080" >/dev/null; then
+  exit 0
+fi
+
+mkdir -p "$HOME/.vnc"
+# vncpasswd's -f mode reads plaintext on stdin, writes the DES blob to stdout.
+# VncAuth truncates >8 chars at compare time, which is fine — the host writes
+# an 8-char password. Write to a temp file + rename so a failure (e.g.,
+# vncpasswd missing) doesn't leave an empty file that Xvnc would then reject.
+#
+# Debian 12 (E2B base) doesn't package vncpasswd at all — tigervnc-tools is
+# Ubuntu-only. When vncpasswd is missing, fall back to `-SecurityTypes None`
+# and rely on the cloud provider's signed preview URL as the access boundary
+# (same effective model: holding the URL = holding the credential). Other
+# providers (docker, hetzner, daytona, vercel) keep VncAuth.
+VNC_SECURITY_ARGS=(-SecurityTypes VncAuth -PasswordFile "$HOME/.vnc/passwd")
+if command -v vncpasswd >/dev/null 2>&1; then
+  TMP_PASSWD="$(mktemp "$HOME/.vnc/passwd.XXXXXX")"
+  printf '%s\n' "$PASS" | vncpasswd -f > "$TMP_PASSWD"
+  chmod 600 "$TMP_PASSWD"
+  mv "$TMP_PASSWD" "$HOME/.vnc/passwd"
+else
+  echo "agentbox-vnc-start: vncpasswd not installed; starting Xvnc with -SecurityTypes None (preview URL is the access boundary)" >&2
+  VNC_SECURITY_ARGS=(-SecurityTypes None)
+fi
+
+mkdir -p /var/log/agentbox 2>/dev/null || true
+
+# Xvnc on display :1, loopback-only (websockify is the only public ingress).
+# 1280x800x24 is a sensible laptop-browser viewport.
+# The clipboard params are on-by-default in TigerVNC 1.13 but pinned here so a
+# base-image bump can't silently break host->box paste, and to document intent:
+# accept cut-text from noVNC, set both the X CLIPBOARD and PRIMARY selections.
+Xvnc :1 \
+  -localhost \
+  "${VNC_SECURITY_ARGS[@]}" \
+  -geometry 1280x800 \
+  -depth 24 \
+  -AlwaysShared \
+  -AcceptCutText=1 \
+  -SendCutText=1 \
+  -SetPrimary=1 \
+  -SendPrimary=1 \
+  >/var/log/agentbox/xvnc.log 2>&1 &
+
+# Wait for Xvnc's RFB socket (5901). bash's /dev/tcp pseudo-device makes the
+# probe a one-liner without needing netcat in the image.
+for _ in $(seq 1 50); do
+  if (echo > /dev/tcp/127.0.0.1/5901) 2>/dev/null; then break; fi
+  sleep 0.1
+done
+
+# With no window manager, nothing owns the X selections, so Xvnc's RFB cut-text
+# isn't reliably handed to Chromium on Ctrl+V. autocutsel (one daemon per
+# selection) keeps CLIPBOARD and PRIMARY populated and synced. Best-effort: a
+# clipboard failure must never abort VNC, and the pgrep guard keeps a stray
+# re-entry from spawning duplicates (Xvnc is up now, so DISPLAY=:1 resolves).
+if ! pgrep -u "$(id -u)" -x autocutsel >/dev/null; then
+  DISPLAY=:1 autocutsel -selection CLIPBOARD -fork >/dev/null 2>&1 || true
+  DISPLAY=:1 autocutsel -selection PRIMARY -fork >/dev/null 2>&1 || true
+fi
+
+# noVNC's static assets live at different paths per base image: Debian/Ubuntu
+# (docker, hetzner) ship them at /usr/share/novnc via apt; the AL2023 bake
+# (vercel) git-clones them to /usr/local/share/novnc. websockify runs
+# os.chdir(--web) at startup, so a wrong path makes it FileNotFoundError and
+# never bind 6080 — pick the first dir that exists.
+NOVNC_WEB=""
+for _d in /usr/share/novnc /usr/local/share/novnc; do
+  if [[ -d "$_d" ]]; then NOVNC_WEB="$_d"; break; fi
+done
+if [[ -z "$NOVNC_WEB" ]]; then
+  echo "agentbox-vnc-start: noVNC assets not found (looked in /usr/share/novnc, /usr/local/share/novnc)" >&2
+  exit 65
+fi
+
+# websockify serves noVNC at /vnc.html (--web) and tunnels WS frames to Xvnc's
+# RFB. Bind 0.0.0.0:6080 so both Docker `-p` mappings and OrbStack's
+# <name>.orb.local routing reach it.
+websockify \
+  --web="$NOVNC_WEB" \
+  0.0.0.0:6080 \
+  127.0.0.1:5901 \
+  >/var/log/agentbox/websockify.log 2>&1 &
+
+disown -a