@madarco/agentbox 0.5.0 → 0.7.0

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-codex-hooks.json

@@ -0,0 +1,37 @@
+{
+  "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 }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "hooks": [
+        { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+      ]
+    }
+  ]
+}

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 `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/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.

package/runtime/hetzner/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/hetzner/agentbox-codex-hooks.json

@@ -0,0 +1,37 @@
+{
+  "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 }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "hooks": [
+        { "type": "command", "command": "agentbox-ctl codex-state idle >/dev/null 2>&1 &", "timeout": 3 }
+      ]
+    }
+  ]
+}

package/runtime/hetzner/agentbox-dockerd-start

@@ -0,0 +1,132 @@
+#!/usr/bin/env bash
+# Start the in-box dockerd. Launched by the host via
+# `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
+
+if pgrep -x dockerd >/dev/null; then
+  exit 0
+fi
+
+mkdir -p /var/lib/docker /var/run /var/log/agentbox
+
+# /var/run lives in the container's writable layer (not a volume), so files
+# written by the previous dockerd run survive `docker stop`/`start`. dockerd
+# refuses to start if `/var/run/docker.pid` exists with a PID in /proc — and
+# after restart, that PID number has been reassigned to (probably) the new
+# `sleep infinity`. Wipe both the pidfile and the stale socket here; pgrep
+# above already confirmed no real dockerd is running.
+rm -f /var/run/docker.pid /var/run/docker.sock
+
+# Cgroup v2 + unprivileged DinD on OrbStack/Docker Desktop: the outer
+# container has /sys/fs/cgroup and /proc/sys bind-mounted RO from the host
+# (Docker's standard hardening). We need both writable for dockerd to:
+#   * mkdir /sys/fs/cgroup/docker (its own cgroup slice for child containers)
+#   * write /proc/sys/net/ipv6/conf/<veth>/disable_ipv6 (default bridge setup)
+# Without these, `docker run` fails with EROFS or "failed to disable IPv6".
+# SYS_ADMIN + the private cgroup namespace let us remount these RW; the
+# writes only affect the box's own namespaces (not the host). Failure is
+# tolerable — some hosts already mount these RW.
+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 &
+
+# Wait for the socket to become accept()-able. Bound by ~30s — first start has
+# 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
+    break
+  fi
+  sleep 0.1
+done
+
+disown -a

package/runtime/hetzner/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