@madarco/agentbox 0.13.0 → 0.15.0

package/runtime/e2b/scripts/build-template.sh

@@ -0,0 +1,295 @@
+#!/usr/bin/env bash
+# AgentBox E2B base-template installer.
+#
+# Run once by `Template.build`'s `.runCmd` step during `agentbox prepare
+# --provider e2b`. After it completes, E2B finalises the template — that
+# template id is what every per-box create boots from.
+#
+# Differences from the vercel installer (packages/sandbox-vercel/scripts/
+# provision.sh), which this mirrors:
+#   - apt-get / dpkg, not dnf (E2B base = Debian 12 bookworm).
+#   - NO docker / dockerd / iptables — E2B microVMs can't run nested
+#     containers (same shape as vercel).
+#   - The `vscode` user is created with a free uid (E2B's `code` group holds
+#     1000 on the base template, so useradd picks the next free uid; there are
+#     no bind mounts so the exact uid is irrelevant — only ownership of
+#     /workspace + /home/vscode matters).
+#
+# Required inputs (uploaded via Template.copy before this runs):
+#   /tmp/agentbox-ctl                  -- prebuilt @agentbox/ctl bundle (cjs)
+#   /tmp/agentbox-vnc-start            -- VNC startup helper
+#   /tmp/agentbox-checkpoint-cleanup   -- pre-snapshot cleanup helper
+#   /tmp/agentbox-open                 -- in-box xdg-open shim
+#   /tmp/agentbox-gh-shim              -- in-box `gh` shim (routes to host gh)
+#   /tmp/agentbox-git-shim             -- in-box `git` shim (routes via relay)
+#   /tmp/agentbox-custom-CLAUDE.md     -- /etc/claude-code/CLAUDE.md content
+#   /tmp/agentbox-managed-settings.json -- /etc/claude-code/managed-settings.json
+#   /tmp/agentbox-codex-hooks.json     -- /usr/local/share/agentbox/codex-hooks.json
+#   /tmp/agentbox-setup-skill.md       -- /usr/local/share/agentbox/setup-guide.md
+#
+# Output: noisy progress to stdout (streamed into ~/.agentbox/logs/prepare.log).
+# Each major step prints `>>> BEGIN <step>` / `<<< END <step>`.
+
+set -euo pipefail
+
+step() { printf '\n>>> BEGIN %s\n' "$1"; }
+done_() { printf '<<< END %s\n' "$1"; }
+
+if [ "$(id -u)" -ne 0 ]; then
+  echo "build-template.sh: must run as root (got uid $(id -u))" >&2
+  exit 64
+fi
+
+export DEBIAN_FRONTEND=noninteractive
+
+step "apt base packages"
+# E2B base ships Debian 12 with node + git + sudo already installed; we still
+# need tmux, build deps, the X11 stack, etc.
+apt-get update -y -q
+apt-get install -y -q --no-install-recommends \
+  ca-certificates \
+  git \
+  tar \
+  gzip \
+  curl \
+  wget \
+  sudo \
+  python3 \
+  python3-pip \
+  python3-venv \
+  tmux \
+  vim \
+  libcap2-bin \
+  rsync \
+  xclip \
+  autocutsel
+done_ "apt base packages"
+
+step "node sanity"
+# E2B base ships node 20; just confirm it's on PATH.
+if ! command -v node >/dev/null 2>&1; then
+  echo "build-template.sh: node not found on the E2B base template — unexpected" >&2
+  exit 65
+fi
+node --version
+done_ "node sanity"
+
+step "vscode user + sudoers"
+# Don't force a uid: the E2B base template's `code` group/user holds 1000,
+# and there are no bind mounts so uid-parity with the docker provider
+# doesn't matter. Ownership + passwordless sudo is what counts.
+if ! id vscode >/dev/null 2>&1; then
+  useradd -m -s /bin/bash vscode
+fi
+install -d -m 0755 -o vscode -g vscode /home/vscode
+echo 'vscode ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/90-agentbox-vscode
+chmod 0440 /etc/sudoers.d/90-agentbox-vscode
+visudo -cf /etc/sudoers >/dev/null
+done_ "vscode user + sudoers"
+
+step "agentbox base dirs + /workspace ownership"
+mkdir -p /workspace /run/agentbox /var/log/agentbox /etc/agentbox /etc/claude-code \
+         /usr/local/share/agentbox
+chmod 755 /workspace
+chown vscode:vscode /workspace /run/agentbox /var/log/agentbox
+done_ "agentbox base dirs + /workspace ownership"
+
+step "node setcap (bind <1024 without root)"
+# Grant node the capability so the WebProxy can bind port 80 without sudo.
+# Best-effort — if setcap is unavailable the WebProxy can still be launched
+# via sudo. (E2B's `getHost` accepts any port; agentbox uses 8080 across
+# cloud providers, so this is belt-and-braces.)
+NODE_BIN="$(readlink -f "$(command -v node)")"
+setcap cap_net_bind_service=+ep "$NODE_BIN" || echo "build-template.sh: setcap failed (continuing)"
+done_ "node setcap (bind <1024 without root)"
+
+step "corepack (pnpm + yarn shims)"
+npm install -g corepack@latest 2>&1 | tail -2 || true
+corepack enable pnpm yarn 2>/dev/null || true
+sudo -u vscode -H mkdir -p /home/vscode/.cache/node/corepack
+done_ "corepack (pnpm + yarn shims)"
+
+step "git system-wide safe.directory"
+git config --system --add safe.directory '*' 2>/dev/null || true
+sudo -u vscode -H git config --global --add safe.directory '*' 2>/dev/null || true
+done_ "git system-wide safe.directory"
+
+step "agentbox-ctl install"
+install -m 0755 /tmp/agentbox-ctl /usr/local/bin/agentbox-ctl
+done_ "agentbox-ctl install"
+
+step "baked helper scripts (vnc / cleanup / xdg-open)"
+install -m 0755 /tmp/agentbox-vnc-start          /usr/local/bin/agentbox-vnc-start
+install -m 0755 /tmp/agentbox-checkpoint-cleanup /usr/local/bin/agentbox-checkpoint-cleanup
+install -m 0755 /tmp/agentbox-open               /usr/local/bin/agentbox-open
+ln -sf /usr/local/bin/agentbox-open /usr/local/bin/xdg-open
+# NOTE: the gh + git shims are installed LAST (see "relay shims" near the end).
+# Installing them here would put the relay-routing `git` on PATH ahead of
+# /usr/bin/git and route this script's own remaining git/clone commands through
+# a relay that doesn't exist during the bake.
+done_ "baked helper scripts (vnc / cleanup / xdg-open)"
+
+step "baked config files (claude / codex / setup guide / tmux.conf)"
+install -m 0644 /tmp/agentbox-custom-CLAUDE.md      /etc/claude-code/CLAUDE.md
+install -m 0644 /tmp/agentbox-managed-settings.json /etc/claude-code/managed-settings.json
+install -m 0644 /tmp/agentbox-codex-hooks.json      /usr/local/share/agentbox/codex-hooks.json
+install -m 0644 /tmp/agentbox-setup-skill.md        /usr/local/share/agentbox/setup-guide.md
+
+cat > /etc/tmux.conf <<'TMUX'
+set -g default-terminal "tmux-256color"
+set -as terminal-overrides ",*:Tc"
+set -as terminal-overrides ",*:RGB"
+set -as terminal-features ",*:hyperlinks"
+set -as terminal-features ",*:RGB"
+set -g allow-passthrough on
+set -g set-clipboard on
+set -g extended-keys on
+set -as terminal-features ",*:extkeys"
+set -g mouse on
+bind -T copy-mode    WheelUpPane   send -N2 -X scroll-up
+bind -T copy-mode    WheelDownPane send -N2 -X scroll-down
+bind -T copy-mode-vi WheelUpPane   send -N2 -X scroll-up
+bind -T copy-mode-vi WheelDownPane send -N2 -X scroll-down
+set -g history-limit 50000
+set -g escape-time 0
+TMUX
+done_ "baked config files (claude / codex / setup guide / tmux.conf)"
+
+step "credential pivot symlinks (vscode home)"
+sudo -u vscode -H mkdir -p \
+  /home/vscode/.claude \
+  /home/vscode/.claude/skills/agentbox-setup \
+  /home/vscode/.codex \
+  /home/vscode/.local/share/opencode \
+  /home/vscode/.agentbox-creds/claude \
+  /home/vscode/.agentbox-creds/codex \
+  /home/vscode/.agentbox-creds/opencode
+sudo -u vscode -H ln -sf /home/vscode/.agentbox-creds/claude/.credentials.json \
+  /home/vscode/.claude/.credentials.json
+sudo -u vscode -H ln -sf /home/vscode/.agentbox-creds/codex/auth.json \
+  /home/vscode/.codex/auth.json
+sudo -u vscode -H ln -sf /home/vscode/.agentbox-creds/opencode/auth.json \
+  /home/vscode/.local/share/opencode/auth.json
+sudo -u vscode -H ln -sf /home/vscode/.claude/_claude.json /home/vscode/.claude.json
+sudo -u vscode -H cp /usr/local/share/agentbox/setup-guide.md \
+  /home/vscode/.claude/skills/agentbox-setup/SKILL.md
+done_ "credential pivot symlinks (vscode home)"
+
+step "login-shell shim (/etc/profile.d/agentbox.sh)"
+cat > /etc/profile.d/agentbox.sh <<'PROFILE'
+# Auto-loaded by login shells; box.env is written at create time.
+if [ -r /etc/agentbox/box.env ]; then
+  set -a
+  . /etc/agentbox/box.env
+  set +a
+fi
+case ":$PATH:" in
+  *:/home/vscode/.local/bin:*) : ;;
+  *) PATH=/home/vscode/.local/bin:$PATH ;;
+esac
+# Force /usr/local/bin to win PATH so the relay-routing shims at
+# /usr/local/bin/{git,gh} aren't shadowed by /usr/bin/{git,gh}. Strip any
+# existing occurrence and re-prepend.
+PATH=/usr/local/bin:$(printf '%s' "$PATH" | sed -e 's#:/usr/local/bin:#:#g' -e 's#^/usr/local/bin:##' -e 's#:/usr/local/bin$##' -e 's#^/usr/local/bin$##')
+export PATH
+export COLORTERM=${COLORTERM:-truecolor}
+export DISABLE_AUTOUPDATER=${DISABLE_AUTOUPDATER:-1}
+export DISPLAY=${DISPLAY:-:1}
+export AGENT_BROWSER_EXECUTABLE_PATH=${AGENT_BROWSER_EXECUTABLE_PATH:-/usr/local/bin/chromium}
+export BROWSER=${BROWSER:-/usr/local/bin/agentbox-open}
+PROFILE
+chmod 0644 /etc/profile.d/agentbox.sh
+done_ "login-shell shim (/etc/profile.d/agentbox.sh)"
+
+step "VNC stack (TigerVNC + websockify + noVNC)"
+# Best-effort: VNC is a convenience (agentbox screen). A package that isn't in
+# the Debian repos shouldn't fail the whole bake.
+apt-get install -y -q --no-install-recommends \
+  tigervnc-standalone-server xterm 2>&1 | tail -3 || \
+  echo "build-template.sh: tigervnc install failed (VNC may be unavailable)"
+# Install websockify into a per-user venv (PEP 668 forbids system pip on
+# Debian 12). The venv goes under /usr/local/share so agentbox-vnc-start can
+# find it regardless of the launching user.
+python3 -m venv /usr/local/share/agentbox/venv 2>/dev/null || true
+/usr/local/share/agentbox/venv/bin/pip install --quiet websockify 2>&1 | tail -2 || \
+  echo "build-template.sh: websockify install failed (VNC may be unavailable)"
+ln -sf /usr/local/share/agentbox/venv/bin/websockify /usr/local/bin/websockify
+# noVNC static assets — clone shallow into a stable path the vnc-start script
+# can serve.
+if [ ! -d /usr/local/share/novnc ]; then
+  git clone --depth 1 https://github.com/novnc/noVNC /usr/local/share/novnc 2>&1 | tail -2 || \
+    echo "build-template.sh: noVNC clone failed (VNC may be unavailable)"
+fi
+sudo -u vscode -H mkdir -p /home/vscode/.vnc
+done_ "VNC stack (TigerVNC + websockify + noVNC)"
+
+step "agent CLIs (codex + opencode + agent-browser, global npm)"
+npm install -g @openai/codex opencode-ai agent-browser 2>&1 | tail -3 || \
+  echo "build-template.sh: one or more agent npm installs failed (continuing)"
+done_ "agent CLIs (codex + opencode + agent-browser, global npm)"
+
+step "Claude Code (native installer, run as vscode)"
+# Anthropic's canonical installer drops `claude` at /home/vscode/.local/bin/.
+sudo -u vscode -H bash -lc 'curl -fsSL https://claude.ai/install.sh | bash -s stable'
+done_ "Claude Code (native installer, run as vscode)"
+
+step "Chrome runtime libs (apt)"
+# agent-browser launches Chromium at AGENT_BROWSER_EXECUTABLE_PATH
+# (/usr/local/bin/chromium, set in the login-shell shim above). Bake the libs
+# Playwright's Chromium needs. Match the docker provider's Debian apt list.
+apt-get install -y -q --no-install-recommends \
+  libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
+  libgbm1 libpango-1.0-0 libcairo2 libasound2 \
+  fonts-liberation
+done_ "Chrome runtime libs (apt)"
+
+step "playwright + Chromium download (as vscode)"
+# Run the download as vscode so the cache lands under
+# /home/vscode/.cache/ms-playwright. Resolve a stable symlink at
+# /usr/local/bin/chromium so AGENT_BROWSER_EXECUTABLE_PATH stays predictable
+# across Chromium revision bumps.
+npm install -g playwright 2>&1 | tail -3
+sudo -u vscode -H bash -lc 'playwright install chromium'
+CHROME_BIN="$(sudo -u vscode -H bash -lc 'ls /home/vscode/.cache/ms-playwright/chromium-*/chrome-linux*/chrome 2>/dev/null | sort | tail -1')"
+if [ -z "$CHROME_BIN" ] || [ ! -x "$CHROME_BIN" ]; then
+  echo "build-template.sh: could not resolve Playwright Chromium binary" >&2
+  exit 70
+fi
+# Fail loud if a shared lib is missing — surfaces an incomplete apt set at bake
+# time, not at first agent-browser launch.
+LDD_OUT="$(ldd "$CHROME_BIN" 2>&1 || true)"
+if printf '%s\n' "$LDD_OUT" | grep -q 'not found'; then
+  echo "build-template.sh: Chromium has unresolved shared libs:" >&2
+  printf '%s\n' "$LDD_OUT" | grep 'not found' >&2
+  exit 71
+fi
+ln -sf "$CHROME_BIN" /usr/local/bin/chromium
+done_ "playwright + Chromium download (as vscode)"
+
+step "apt cleanup"
+apt-get clean -y -q 2>/dev/null || true
+rm -rf /var/lib/apt/lists/* 2>/dev/null || true
+done_ "apt cleanup"
+
+# Relay-routing shims, installed LAST — after every git/gh use in this script
+# (the noVNC `git clone` and any npm/installer step). At RUNTIME agent calls to
+# `gh ...` / `git push|pull|fetch|clone` must route through the host relay; the
+# login-shell shim above forces /usr/local/bin ahead of /usr/bin so these win.
+# During the bake there is no relay, so they must not shadow the real binaries
+# until provisioning is done. Installed from /tmp just before the trim step.
+step "relay shims (gh + git)"
+install -m 0755 /tmp/agentbox-gh-shim  /usr/local/bin/gh
+install -m 0755 /tmp/agentbox-git-shim /usr/local/bin/git
+done_ "relay shims (gh + git)"
+
+step "trim /tmp/agentbox-*"
+rm -f /tmp/agentbox-ctl /tmp/agentbox-vnc-start \
+      /tmp/agentbox-checkpoint-cleanup /tmp/agentbox-open \
+      /tmp/agentbox-gh-shim /tmp/agentbox-git-shim \
+      /tmp/agentbox-custom-CLAUDE.md /tmp/agentbox-managed-settings.json \
+      /tmp/agentbox-codex-hooks.json /tmp/agentbox-setup-skill.md
+mv /tmp/agentbox-build-template.sh /var/log/agentbox/build-template.sh 2>/dev/null || true
+done_ "trim /tmp/agentbox-*"
+
+printf '\n*** build-template.sh: complete — template ready for finalisation.\n'

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

@@ -48,7 +48,42 @@ Look at `/workspace`:
 - 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)
 
@@ -157,6 +192,36 @@ services:
       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.
@@ -184,6 +249,7 @@ Tell the user (verbatim):
 ## 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.

package/runtime/hetzner/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/hetzner/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": [
       {