@madarco/agentbox 0.5.0 → 0.6.0

package/dist/{lifecycle-LFOL6YFM-TCHDX3J5.js → lifecycle-EMXR46DI-DUVBXNTV.js}

@@ -13,12 +13,12 @@ import {
   startBox,
   stopBox,
   unpauseBox
-} from "./chunk-FJNIFTWK.js";
+} from "./chunk-M7I247BK.js";
 import {
   SNAPSHOTS_ROOT
-} from "./chunk-PXUBE5KS.js";
+} from "./chunk-HTTKML3C.js";
 import "./chunk-HPZMD5DE.js";
-import "./chunk-RFC5F5HR.js";
+import "./chunk-HHMWQNLF.js";
 export {
   AmbiguousBoxError,
   BoxNotFoundError,
@@ -35,4 +35,4 @@ export {
   stopBox,
   unpauseBox
 };
-//# sourceMappingURL=lifecycle-LFOL6YFM-TCHDX3J5.js.map
+//# sourceMappingURL=lifecycle-EMXR46DI-DUVBXNTV.js.map

package/dist/{stats-Z4BVJODD-HEC4TMUZ.js → stats-SZXOJE3D-N7OODCHW.js}

@@ -6,8 +6,8 @@ import {
   parseDockerSize,
   projectCheckpointImageBytes,
   volumeSizeBytes
-} from "./chunk-7J5AJLWG.js";
-import "./chunk-RFC5F5HR.js";
+} from "./chunk-BBZMA2K6.js";
+import "./chunk-HHMWQNLF.js";
 export {
   agentboxHomeBytes,
   allCheckpointImagesBytes,
@@ -16,4 +16,4 @@ export {
   projectCheckpointImageBytes,
   volumeSizeBytes
 };
-//# sourceMappingURL=stats-Z4BVJODD-HEC4TMUZ.js.map
+//# sourceMappingURL=stats-SZXOJE3D-N7OODCHW.js.map

package/package.json

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

package/runtime/docker/Dockerfile.box

@@ -5,8 +5,8 @@
 # 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 because the in-box dockerd uses
-# fuse-overlayfs as its storage driver. Plus the "universal-ish" set of
+# 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.
@@ -105,14 +105,15 @@ RUN npm install -g corepack@latest \
 # 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 — fuse3 + fuse-overlayfs are installed above
-# specifically for this (the outer /workspace overlay is gone, but the inner
-# dockerd still needs 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`
@@ -123,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
@@ -284,6 +285,17 @@ RUN chmod +x /usr/local/bin/agentbox-dockerd-start
 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

package/runtime/docker/apps/cli/share/agentbox-setup/SKILL.md

@@ -158,21 +158,29 @@ 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
+## 8. Checkpoint the warm state (do this at the very end)
 
-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. 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.
+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.
 
-5. Tell the user:
+## 9. Hand-off
 
-   > 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 download config` to update their original host workspace.
+Tell the user (verbatim):
 
-## 9. Known issues
+   ```
+    █████╗  ██████╗ ███████╗███╗   ██╗████████╗██████╗  ██████╗ ██╗  ██╗
+   ██╔══██╗██╔════╝ ██╔════╝████╗  ██║╚══██╔══╝██╔══██╗██╔═══██╗╚██╗██╔╝
+   ███████║██║  ███╗█████╗  ██╔██╗ ██║   ██║   ██████╔╝██║   ██║ ╚███╔╝
+   ██╔══██║██║   ██║██╔══╝  ██║╚██╗██║   ██║   ██╔══██╗██║   ██║ ██╔██╗
+   ██║  ██║╚██████╔╝███████╗██║ ╚████║   ██║   ██████╔╝╚██████╔╝██╔╝ ██╗
+   ╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝   ╚═╝   ╚═════╝  ╚═════╝ ╚═╝  ╚═╝
+   ```
+
+   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.
 

package/runtime/docker/packages/ctl/dist/bin.cjs

@@ -10371,8 +10371,27 @@ var {
 } = import_index.default;
 
 // src/client.ts
+var import_node_child_process = require("child_process");
+var import_node_fs = require("fs");
 var import_node_net = require("net");
-async function connect(opts) {
+async function tryReviveDaemon(socketPath) {
+  if (process.env.AGENTBOX !== "1") return false;
+  try {
+    const child = (0, import_node_child_process.spawn)("agentbox-ctl", ["daemon"], {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.unref();
+  } catch {
+    return false;
+  }
+  for (let i = 0; i < 50; i++) {
+    await new Promise((r) => setTimeout(r, 100));
+    if ((0, import_node_fs.existsSync)(socketPath)) return true;
+  }
+  return false;
+}
+async function connectOnce(opts) {
   const sock = (0, import_node_net.createConnection)(opts.socketPath);
   await new Promise((resolve, reject) => {
     const timer = setTimeout(() => {
@@ -10390,6 +10409,17 @@ async function connect(opts) {
   });
   return sock;
 }
+async function connect(opts) {
+  try {
+    return await connectOnce(opts);
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ECONNREFUSED" && code !== "ENOENT") throw err;
+    const revived = await tryReviveDaemon(opts.socketPath);
+    if (!revived) throw err;
+    return await connectOnce(opts);
+  }
+}
 async function sendOneShot(opts, req) {
   const sock = await connect(opts);
   sock.write(`${JSON.stringify(req)}
@@ -11077,9 +11107,9 @@ function describeCommand(cmd) {
 }
 
 // src/supervisor.ts
-var import_node_child_process = require("child_process");
+var import_node_child_process2 = require("child_process");
 var import_node_events = require("events");
-var import_node_fs = require("fs");
+var import_node_fs2 = require("fs");
 var import_promises3 = require("fs/promises");
 var import_node_path = require("path");
 
@@ -11343,7 +11373,7 @@ var cachedLoginPath;
 function loginShellPath() {
   if (cachedLoginPath !== void 0) return cachedLoginPath;
   try {
-    const out = (0, import_node_child_process.execFileSync)("bash", ["-lc", 'printf %s "$PATH"'], {
+    const out = (0, import_node_child_process2.execFileSync)("bash", ["-lc", 'printf %s "$PATH"'], {
       encoding: "utf8",
       timeout: 5e3
     }).trim();
@@ -11358,7 +11388,7 @@ var ServiceRunner = class extends import_node_events.EventEmitter {
     super();
     this.spec = spec;
     this.opts = opts;
-    this.spawnFn = opts.spawn ?? import_node_child_process.spawn;
+    this.spawnFn = opts.spawn ?? import_node_child_process2.spawn;
     this.setTimer = opts.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
     this.clearTimer = opts.clearTimer ?? ((h) => {
       clearTimeout(h);
@@ -11455,7 +11485,7 @@ var ServiceRunner = class extends import_node_events.EventEmitter {
     const spec = this.spec;
     const cwd = resolveCwd(spec.cwd, this.opts.cwd);
     if (!this.logStream) {
-      this.logStream = (0, import_node_fs.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
+      this.logStream = (0, import_node_fs2.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
         flags: "a"
       });
       this.logStream.on("error", (err) => {
@@ -11589,7 +11619,7 @@ var TaskRunner = class extends import_node_events.EventEmitter {
     super();
     this.spec = spec;
     this.opts = opts;
-    this.spawnFn = opts.spawn ?? import_node_child_process.spawn;
+    this.spawnFn = opts.spawn ?? import_node_child_process2.spawn;
   }
   spec;
   opts;
@@ -11653,7 +11683,7 @@ var TaskRunner = class extends import_node_events.EventEmitter {
     const spec = this.spec;
     const cwd = resolveCwd(spec.cwd, this.opts.cwd);
     if (!this.logStream) {
-      this.logStream = (0, import_node_fs.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
+      this.logStream = (0, import_node_fs2.createWriteStream)((0, import_node_path.join)(this.opts.logDir, `${spec.name}.log`), {
         flags: "a"
       });
       this.logStream.on("error", (err) => {
@@ -12137,10 +12167,10 @@ var import_promises4 = require("fs/promises");
 var import_node_path2 = require("path");
 
 // src/status-reporter.ts
-var import_node_child_process3 = require("child_process");
+var import_node_child_process4 = require("child_process");
 
 // src/tmux.ts
-var import_node_child_process2 = require("child_process");
+var import_node_child_process3 = require("child_process");
 var import_node_os = require("os");
 var MAX_TITLE_LEN = 120;
 function sanitizePaneTitle(raw, ctx) {
@@ -12154,7 +12184,7 @@ function sanitizePaneTitle(raw, ctx) {
 }
 function runTool(cmd, args) {
   return new Promise((resolve) => {
-    const child = (0, import_node_child_process2.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
+    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "pipe"] });
     let stdout = "";
     let stderr = "";
     child.stdout.on("data", (b) => stdout += b.toString("utf8"));
@@ -12298,7 +12328,7 @@ async function collectPorts(supervisor) {
 }
 function run(cmd, args) {
   return new Promise((resolve) => {
-    const child = (0, import_node_child_process3.spawn)(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
+    const child = (0, import_node_child_process4.spawn)(cmd, args, { stdio: ["ignore", "pipe", "ignore"] });
     let stdout = "";
     child.stdout.on("data", (b) => stdout += b.toString("utf8"));
     child.on("error", () => resolve({ exitCode: 127, stdout }));
@@ -12345,7 +12375,8 @@ async function startServer(opts) {
       resolve();
     });
   });
-  await (0, import_promises4.chmod)(opts.socketPath, 432);
+  await (0, import_promises4.chmod)(opts.socketPath, 432).catch(() => {
+  });
   return server;
 }
 async function handleConnection(sock, opts) {
@@ -12592,7 +12623,7 @@ var checkpointCommand = new Command("checkpoint").description("Capture this box
 );
 
 // src/commands/git.ts
-var import_node_child_process4 = require("child_process");
+var import_node_child_process5 = require("child_process");
 function buildParams(opts, extra) {
   const params = { path: opts.cwd ?? process.cwd() };
   if (opts.remote) params.remote = opts.remote;
@@ -12601,7 +12632,7 @@ function buildParams(opts, extra) {
 }
 function runLocalGit(args, cwd) {
   return new Promise((resolve) => {
-    const child = (0, import_node_child_process4.spawn)("git", args, { cwd, stdio: "inherit" });
+    const child = (0, import_node_child_process5.spawn)("git", args, { cwd, stdio: "inherit" });
     child.on("close", (code) => resolve(code ?? 1));
     child.on("error", (err) => {
       process.stderr.write(`agentbox-ctl git: ${String(err.message ?? err)}
@@ -12663,6 +12694,15 @@ var notifyCommand = new Command("notify").description(
   })
 );
 
+// src/commands/open.ts
+var openCommand = new Command("open").description("Open a URL in the host's default browser (via the agentbox relay)").argument("<url>", "http(s) URL to open on the host").action(async (url) => {
+  const params = { url };
+  const code = await postRpcAndExit("browser.open", params, {
+    errorPrefix: "agentbox-ctl open"
+  });
+  process.exit(code);
+});
+
 // src/render.ts
 function renderStatusTable(rows) {
   if (rows.length === 0) return "(no services configured)";
@@ -12854,6 +12894,7 @@ program2.addCommand(checkpointCommand);
 program2.addCommand(cpCommand);
 program2.addCommand(downloadCommand);
 program2.addCommand(notifyCommand);
+program2.addCommand(openCommand);
 program2.parseAsync(process.argv).catch((err) => {
   const msg = err instanceof Error ? err.message : String(err);
   process.stderr.write(`agentbox-ctl: ${msg}

package/runtime/docker/packages/sandbox-docker/scripts/agentbox-checkpoint-cleanup

@@ -22,8 +22,14 @@ set +e
 apt-get clean 2>/dev/null
 rm -rf /var/lib/apt/lists/* 2>/dev/null
 
-# Throwaway scratch dirs.
-rm -rf /tmp/* /tmp/.[!.]* /var/tmp/* /var/tmp/.[!.]* 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.
@@ -31,9 +37,13 @@ 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).
+# 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.

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

@@ -1,9 +1,10 @@
 #!/usr/bin/env bash
 # Start the in-box dockerd. Launched by the host via
-# `docker exec -d --user root` after the FUSE overlay is up. Idempotent — safe
-# to call again on `agentbox start`. Storage driver is fuse-overlayfs (set in
-# /etc/docker/daemon.json baked into the image) so the inner daemon doesn't
-# need the kernel `overlay` driver, which an unprivileged container can't load.
+# `docker exec -d --user root`. Idempotent — safe to call again on
+# `agentbox start`. The storage driver is selected at runtime (see
+# select_storage_driver below): the kernel-native `overlay2` when a probe
+# proves it works on the data-root filesystem, otherwise `fuse-overlayfs`.
+# The chosen driver is written to /etc/docker/daemon.json before launch.
 
 set -euo pipefail
 
@@ -33,14 +34,93 @@ rm -f /var/run/docker.pid /var/run/docker.sock
 mount -o remount,rw /sys/fs/cgroup 2>/dev/null || true
 mount -o remount,rw /proc/sys 2>/dev/null || true
 
+# --- Storage-driver selection -------------------------------------------------
+# The inner dockerd's data root (/var/lib/docker, a Docker named volume) used
+# to be pinned to fuse-overlayfs. fuse-overlayfs is broken on recent kernels
+# (e.g. Docker Desktop's 6.x linuxkit kernel): inner `docker run` fails at
+# execve() with "exec ...: invalid argument". The kernel-native overlay2
+# driver works when the data-root filesystem can carry an overlay mount, which
+# the ext4 named volume can. We pick overlay2 when a probe proves it works,
+# else fall back to fuse-overlayfs.
+#
+# dockerd refuses to switch drivers once its data root is populated, so if the
+# data root is already initialized under one driver we reuse that driver and
+# skip the probe — a box created under one driver never switches.
+DOCKER_DATA_ROOT=/var/lib/docker
+DAEMON_JSON=/etc/docker/daemon.json
+
+probe_overlay2() {
+  # The kernel overlay filesystem has to exist at all.
+  grep -qw overlay /proc/filesystems 2>/dev/null || return 1
+
+  local probe lower upper work merged ok=1
+  # The probe dir MUST live inside the data root so the test overlay is mounted
+  # on the SAME filesystem the real graph will use. A probe under /tmp would
+  # test the container's overlayfs writable layer — the wrong filesystem.
+  probe="$(mktemp -d "$DOCKER_DATA_ROOT/.overlay2-probe.XXXXXX" 2>/dev/null)" || return 1
+  lower="$probe/lower"; upper="$probe/upper"; work="$probe/work"; merged="$probe/merged"
+  mkdir -p "$lower" "$upper" "$work" "$merged" || { rm -rf "$probe"; return 1; }
+
+  # Stage a known-good executable so the merged view exposes it.
+  cp /bin/true "$lower/probe-bin" 2>/dev/null || { rm -rf "$probe"; return 1; }
+  chmod 0755 "$lower/probe-bin" 2>/dev/null || true
+
+  if mount -t overlay overlay \
+       -o "lowerdir=$lower,upperdir=$upper,workdir=$work" "$merged" 2>/dev/null; then
+    # The actual fuse-overlayfs failure mode: execve from the merged dir. A
+    # successful mount is not enough — fuse-overlayfs mounts fine and only
+    # fails here.
+    "$merged/probe-bin" >/dev/null 2>&1 || ok=0
+    umount "$merged" 2>/dev/null || umount -l "$merged" 2>/dev/null || true
+  else
+    ok=0
+  fi
+  rm -rf "$probe"
+  [ "$ok" = 1 ]
+}
+
+select_storage_driver() {
+  # 1. Reuse an already-initialized data root's driver — dockerd cannot switch
+  #    a populated data root, and this script reruns on every `agentbox start`.
+  local has_overlay2=0 has_fuse=0
+  [ -d "$DOCKER_DATA_ROOT/overlay2" ] \
+    && [ -n "$(ls -A "$DOCKER_DATA_ROOT/overlay2" 2>/dev/null)" ] && has_overlay2=1
+  [ -d "$DOCKER_DATA_ROOT/fuse-overlayfs" ] \
+    && [ -n "$(ls -A "$DOCKER_DATA_ROOT/fuse-overlayfs" 2>/dev/null)" ] && has_fuse=1
+  if [ "$has_overlay2" = 1 ]; then echo "overlay2"; return 0; fi
+  if [ "$has_fuse" = 1 ]; then echo "fuse-overlayfs"; return 0; fi
+
+  # 2. Fresh data root: probe overlay2 against the data-root filesystem.
+  if probe_overlay2; then echo "overlay2"; return 0; fi
+  echo "fuse-overlayfs"
+}
+
+# Sweep any leaked probe dir from a hard-killed previous run (cosmetic; the
+# driver subdir checks above ignore it, and dockerd ignores non-driver dirs).
+rm -rf "$DOCKER_DATA_ROOT"/.overlay2-probe.* 2>/dev/null || true
+
+STORAGE_DRIVER="$(select_storage_driver)"
+
+# Write daemon.json with the resolved driver. `iptables: true` stays for inner
+# bridge networking. Rewritten every start, but the driver is stable (step 1
+# above), so this never causes a mid-life driver switch.
+mkdir -p /etc/docker
+printf '%s\n' \
+  "{ \"storage-driver\": \"$STORAGE_DRIVER\", \"iptables\": true }" \
+  > "$DAEMON_JSON"
+# Truncate dockerd.log fresh for this start, marker line first; dockerd appends.
+echo "agentbox-dockerd-start: storage-driver=$STORAGE_DRIVER" \
+  > /var/log/agentbox/dockerd.log
+# --- end storage-driver selection --------------------------------------------
+
 # nohup + & + disown lets us survive the `docker exec -d` returning. dockerd
 # reads /etc/docker/daemon.json on its own; no flags here keeps the start path
 # debuggable from inside the container (just edit the file and restart).
-nohup dockerd >/var/log/agentbox/dockerd.log 2>&1 &
+nohup dockerd >>/var/log/agentbox/dockerd.log 2>&1 &
 
 # Wait for the socket to become accept()-able. Bound by ~30s — first start has
-# to initialize iptables chains and the fuse-overlayfs graphdriver, which is
-# noticeably slower than overlay2.
+# to initialize iptables chains and the storage graphdriver (fuse-overlayfs is
+# noticeably slower to initialize than overlay2).
 for _ in $(seq 1 300); do
   if [ -S /var/run/docker.sock ] \
      && docker -H unix:///var/run/docker.sock info >/dev/null 2>&1; then

package/runtime/docker/packages/sandbox-docker/scripts/agentbox-open

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Routes in-box URL opens to the *host's* default browser via the agentbox
+# relay. The box has no real browser of its own. 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 forwarded to the host. Anything else (a file path,
+# another scheme) falls through to the real xdg-open, which resolves it
+# locally inside 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/docker/packages/sandbox-docker/scripts/custom-system-CLAUDE.md

@@ -2,13 +2,13 @@
 
 You are running inside an AgentBox sandbox: a Linux Docker container with
 docker-in-docker (run `docker` directly, no sudo). 
-Your user is `vscode` and you can use passwordless sudo to run commands as root.
+Your user is `vscode` and you can use passwordless **sudo** to run commands as root.
 `/workspace` is your own per-box git worktree on branch `agentbox/<box-name>`:
 writes there stay in the container's writable layer and don't touch the host's working
 tree.
 
 You can save the current filesystem state to be reused by future boxes by 
-running `agentbox-ctl checkpoint --set-default`.
+running `agentbox-ctl checkpoint --set-default`. This doesn't need to be confirmed by the user.
 
 The main `.git/` is bind-mounted at the same absolute path as on
 the host, so local commits show up in the host's `git log` immediately.
@@ -18,15 +18,10 @@ No SSH creds, no host gitconfig identity. For ops that need the user
 
 For ad-hoc file transfers between this box and the host, use
 `agentbox-ctl cp toHost <boxPath> <hostPath>` and
-`agentbox-ctl cp fromHost <hostPath> <boxPath>`. They RPC to the host and
+`agentbox-ctl cp fromHost <hostPath> <boxPath>` or `agentbox-ctl download claude` / `download env` /
+`download config`. They RPC to the host and
 ask the user for confirmation on the wrapper that runs `agentbox claude`;
 deny returns exit 10 (`denied by user`). 
 Don't put any timeout on the command, it will run forever and the user will be notified through multiple channels.
 
-If you install a skill/plugin, change `~/.claude`, or write
-`.env`/`.envrc`/secrets/`agentbox.yaml`, you can pull those onto the host
-yourself with `agentbox-ctl download claude` / `download env` /
-`download config` (also user-confirmed; additive; never overwrites host
-files, don't put any timeout on the command).
-
 Box identity: /etc/agentbox/box.env and the AGENTBOX_* env vars.