@madarco/agentbox 0.1.0

package/dist/lifecycle-P4FSKGR2-3466P54Y.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import {
+  AmbiguousBoxError,
+  BoxNotFoundError,
+  destroyBox,
+  getBoxHostPaths,
+  inspectBox,
+  listBoxes,
+  openBoxInFinder,
+  pauseBox,
+  pruneBoxes,
+  snapshotPresent,
+  startBox,
+  stopBox,
+  unpauseBox
+} from "./chunk-RWJE6AER.js";
+import {
+  SNAPSHOTS_ROOT
+} from "./chunk-O5HS3QHW.js";
+import "./chunk-IDR4HVIC.js";
+import "./chunk-SOMIKEN2.js";
+export {
+  AmbiguousBoxError,
+  BoxNotFoundError,
+  SNAPSHOTS_ROOT,
+  destroyBox,
+  getBoxHostPaths,
+  inspectBox,
+  listBoxes,
+  openBoxInFinder,
+  pauseBox,
+  pruneBoxes,
+  snapshotPresent,
+  startBox,
+  stopBox,
+  unpauseBox
+};
+//# sourceMappingURL=lifecycle-P4FSKGR2-3466P54Y.js.map

package/dist/lifecycle-P4FSKGR2-3466P54Y.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/state-ZSP3ORXW-WI6KOIG3.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import {
+  STATE_DIR,
+  STATE_FILE,
+  allocateProjectIndex,
+  autoPickProjectBox,
+  findBox,
+  readState,
+  recordBox,
+  removeBoxRecord,
+  resolveBoxRef,
+  writeState
+} from "./chunk-IDR4HVIC.js";
+export {
+  STATE_DIR,
+  STATE_FILE,
+  allocateProjectIndex,
+  autoPickProjectBox,
+  findBox,
+  readState,
+  recordBox,
+  removeBoxRecord,
+  resolveBoxRef,
+  writeState
+};
+//# sourceMappingURL=state-ZSP3ORXW-WI6KOIG3.js.map

package/dist/state-ZSP3ORXW-WI6KOIG3.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/stats-GZFLPYTU-DBJ2DVBJ.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import {
+  agentboxHomeBytes,
+  allCheckpointVolumesBytes,
+  boxResourceStats,
+  parseDockerSize,
+  projectCheckpointVolumeBytes,
+  volumeSizeBytes
+} from "./chunk-J35IH7W5.js";
+import "./chunk-SOMIKEN2.js";
+export {
+  agentboxHomeBytes,
+  allCheckpointVolumesBytes,
+  boxResourceStats,
+  parseDockerSize,
+  projectCheckpointVolumeBytes,
+  volumeSizeBytes
+};
+//# sourceMappingURL=stats-GZFLPYTU-DBJ2DVBJ.js.map

package/dist/stats-GZFLPYTU-DBJ2DVBJ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@madarco/agentbox",
+  "version": "0.1.0",
+  "description": "Launch Claude Code, Codex, and other coding agents in isolated sandboxes",
+  "license": "MIT",
+  "author": "Marco D'Alia",
+  "type": "module",
+  "engines": {
+    "node": ">=20.10"
+  },
+  "bin": {
+    "agentbox": "./dist/index.js"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "codex",
+    "coding-agent",
+    "sandbox",
+    "docker",
+    "cli",
+    "isolation",
+    "agentbox"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/madarco/agentbox.git",
+    "directory": "apps/cli"
+  },
+  "homepage": "https://github.com/madarco/agentbox#readme",
+  "bugs": {
+    "url": "https://github.com/madarco/agentbox/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "dist",
+    "share",
+    "runtime"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.9.0",
+    "@xterm/headless": "^5.5.0",
+    "commander": "^12.1.0",
+    "execa": "^9.5.2",
+    "supports-hyperlinks": "^3.1.0",
+    "yaml": "^2.6.1"
+  },
+  "optionalDependencies": {
+    "@homebridge/node-pty-prebuilt-multiarch": "^0.13.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8",
+    "@agentbox/config": "0.0.0",
+    "@agentbox/core": "0.0.0",
+    "@agentbox/ctl": "0.0.0",
+    "@agentbox/sandbox-docker": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src test",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist runtime .turbo",
+    "publish:patch": "npm version patch && git push --follow-tags",
+    "publish:minor": "npm version minor && git push --follow-tags"
+  }
+}

package/runtime/docker/Dockerfile.box

@@ -0,0 +1,316 @@
+# AgentBox base box image.
+#
+# Layered on Microsoft's devcontainers base:ubuntu (arm64-native — the
+# `universal:2-linux` image is amd64-only, which is a non-starter on Apple
+# Silicon hosts). We add the bits the box needs to mount a FUSE overlay over
+# /host-src + /upper, plus a "universal-ish" set of language runtimes
+# (Node.js 22 from NodeSource, Python 3 from apt). Anything heavier (Go, Java,
+# Ruby, .NET, browser tooling, vscode-server) goes in a later iteration.
+#
+# Required runtime flags:
+#     --cap-add=SYS_ADMIN --device=/dev/fuse --security-opt=apparmor:unconfined
+FROM mcr.microsoft.com/devcontainers/base:ubuntu
+
+USER root
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# COLORTERM is the de-facto signal TUI apps (including Claude Code) use to
+# decide whether to emit 24-bit RGB. Without it, claude sees TERM=tmux-256color
+# in panes and falls back to a 256-color palette, which renders the logo and
+# gradients as dim monochrome blocks. tmux is configured to forward RGB to the
+# outer terminal regardless; this just unlocks the in-pane side.
+#
+# DISABLE_AUTOUPDATER follows Anthropic's own devcontainer guidance: there's no
+# point updating Claude Code inside a sandbox that's torn down regularly, and
+# leaving it enabled triggers a "installMethod is native, but .local/bin
+# missing" warning when the host's .claude.json (synced in) reports a native
+# install method while the box uses npm-global.
+#
+# LANG/LC_ALL must be set via ENV (not /etc/environment, which is what the
+# devcontainers base seeds): `docker exec` doesn't source login files, so
+# without this every host-launched tmux/claude inherits an empty LANG, the
+# active locale falls back to POSIX, and tmux 3.x treats the terminal as
+# non-UTF-8 — Claude's rounded prompt box (`╭ ─ ╮ │ ╰ ╯`) renders as ASCII.
+# en_US.UTF-8 is pre-generated by the base image, so no locale-gen needed.
+ENV COLORTERM=truecolor \
+    DISABLE_AUTOUPDATER=1 \
+    LANG=en_US.UTF-8 \
+    LC_ALL=en_US.UTF-8 \
+    PATH=/home/vscode/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
+
+# The PATH prepend above is load-bearing: Anthropic's native installer drops
+# `claude` at /home/vscode/.local/bin/, which isn't in `docker exec`'s default
+# PATH. Without this, the tmux session started by `startClaudeSession` can't
+# resolve `claude` via /bin/sh -c and the session exits immediately.
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        curl ca-certificates gnupg \
+    && curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
+    && apt-get install -y --no-install-recommends \
+        fuse3 \
+        fuse-overlayfs \
+        rsync \
+        nodejs \
+        python3 \
+        python3-pip \
+        python3-venv \
+        build-essential \
+        git \
+        tmux \
+        libcap2-bin \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p /workspace /host-src /upper /snapshot /run/agentbox /var/log/agentbox \
+    && chmod 755 /workspace /host-src /upper /snapshot \
+    && chown vscode:vscode /run/agentbox /var/log/agentbox
+
+# The in-box supervisor (runs as non-root `vscode`) owns a TCP forwarder that
+# binds container :80 -> the `expose:`-flagged service (see WebProxy /
+# agentbox.yaml `expose:`). Binding a port <1024 needs CAP_NET_BIND_SERVICE;
+# grant it to the node binary so the supervisor can listen on :80 without root.
+# Broad (any in-box node can bind low ports) but acceptable for a single-tenant
+# sandbox — strictly narrower than the existing NET_ADMIN/seccomp=unconfined.
+RUN setcap cap_net_bind_service=+ep "$(readlink -f "$(command -v node)")"
+
+# Host repos are bind-mounted in at their identical absolute path (worktree
+# pointer files contain absolute paths to <main>/.git/worktrees/<name>, so both
+# sides have to resolve the same path), and the host owns those `.git/` dirs.
+# git's recent "dubious ownership" guard would refuse to operate without an
+# explicit allowlist. /etc/gitconfig is system-wide and unaffected by the RO
+# bind-mount of ~/.gitconfig from the host.
+RUN git config --system --add safe.directory '*'
+
+# Docker-in-Docker. dockerd inside the box (storage-driver=fuse-overlayfs, set
+# in /etc/docker/daemon.json) lets the agent run `docker build`/`docker run`
+# in its own namespace without exposing the host daemon. fuse-overlayfs is
+# required because the kernel `overlay` driver isn't usable from an
+# unprivileged container — but fuse3 + fuse-overlayfs are already installed
+# above for the /workspace overlay, so docker reuses them. iptables is needed
+# for inner-container bridge networking. Adding `vscode` to the `docker` group
+# 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`
+# (see launchDockerdDaemon), mirroring the VNC/ctl daemon pattern.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        docker.io \
+        iptables \
+    && rm -rf /var/lib/apt/lists/* \
+    && mkdir -p /etc/docker \
+    && printf '%s\n' '{ "storage-driver": "fuse-overlayfs", "iptables": true }' > /etc/docker/daemon.json \
+    && usermod -aG docker vscode
+
+# agentbox-ctl: the in-container supervisor + CLI. Build context is the
+# monorepo root, so packages/ctl/dist is the prebuilt bundle from
+# `pnpm --filter @agentbox/ctl build`. The CLI is bundled with all deps
+# inlined (see tsup config), so a single COPY is enough.
+COPY packages/ctl/dist/bin.cjs /usr/local/bin/agentbox-ctl
+RUN chmod +x /usr/local/bin/agentbox-ctl
+
+# Setup guide for the first-run wizard. The CLI also installs the same file as
+# a host-side claude skill (~/.claude/skills/agentbox-setup/SKILL.md) the
+# first time the wizard fires; the existing ~/.claude rsync flow propagates
+# it into every box automatically. Keeping a copy baked into the image at a
+# stable path guarantees the wizard's initial prompt can reference the guide
+# even on hosts where the user wiped their ~/.claude/skills.
+COPY apps/cli/share/agentbox-setup/SKILL.md /usr/local/share/agentbox/setup-guide.md
+RUN chmod 0644 /usr/local/share/agentbox/setup-guide.md
+
+# Prepare /home/vscode/.claude (the volume mount target) and the .claude.json
+# symlink. The mkdir+chown is load-bearing: when we mount the named
+# `agentbox-claude-config` volume at runtime, Docker seeds the empty volume's
+# perms from this directory on first mount. Without the chown the volume comes
+# up root-owned and Claude Code can't write.
+#
+# The symlink ~/.claude.json -> ~/.claude/_claude.json routes Claude's
+# top-level state file (onboarding, anonymous id, plugin caches, oauth account
+# stub) into the volume, so it persists across box rebuilds and gets refreshed
+# from the host on every `agentbox claude` create. The target is initially
+# dangling — it materializes when `ensureClaudeVolume` copies the host's
+# ~/.claude.json into the volume.
+RUN mkdir -p /home/vscode/.claude \
+    && chown vscode:vscode /home/vscode/.claude \
+    && ln -s /home/vscode/.claude/_claude.json /home/vscode/.claude.json \
+    && chown -h vscode:vscode /home/vscode/.claude.json
+
+# Prepare /home/vscode/.vscode-server and /home/vscode/.cursor-server (+ their
+# extensions subdirs) so the named volumes mounted at runtime — per-box
+# `agentbox-{vscode,cursor}-server-<id>` over the server dirs, then shared
+# `agentbox-{vscode,cursor}-extensions` over the extensions subdirs — come up
+# owned by vscode. Same load-bearing reason as the .claude block above: empty
+# named volumes inherit the mount point's perms on first mount; without these
+# chowns, the Dev Containers extension (in either VS Code or Cursor) fails to
+# mkdir <server>/bin/<commit>/ during server install ("Permission denied").
+RUN mkdir -p /home/vscode/.vscode-server/extensions /home/vscode/.cursor-server/extensions \
+    && chown -R vscode:vscode /home/vscode/.vscode-server /home/vscode/.cursor-server
+
+# Claude Code via Anthropic's native installer — the recommended path per
+# code.claude.com/docs/en/setup (npm-global is under "Advanced installation"
+# now, with a warning against `sudo npm install -g`). Pinned to the `stable`
+# release channel so rebuilds get a predictable ~week-old release.
+# DISABLE_AUTOUPDATER=1 (set above) prevents in-box self-updates. We run as
+# `vscode` so the binary lands at /home/vscode/.local/bin/claude — the path
+# the host's `.claude.json` (with installMethod=native) expects, so the in-box
+# integrity check doesn't fire.
+USER vscode
+RUN curl -fsSL https://claude.ai/install.sh | bash -s stable
+USER root
+
+# Browser support for in-box agents: Vercel's agent-browser drives Chrome via
+# CDP. Two things have to happen here:
+#
+#  1. Install Chrome's runtime libs (the well-known set Playwright's
+#     `install-deps` installs). Package names are pinned to Ubuntu 24.04
+#     (Noble) — the t64 suffix marks libs that flipped to 64-bit time_t in
+#     the noble transition. If the base image moves back to jammy these will
+#     need the un-suffixed names.
+#
+#  2. Get an actual Chromium binary. `agent-browser install` would normally
+#     download Chrome for Testing, but Chrome for Testing has no Linux ARM64
+#     build (Apple Silicon hosts run linux/arm64 containers) and Noble's
+#     `chromium-browser` apt package is a snap stub that won't run inside a
+#     container. The reliable cross-arch source is Playwright's bundled
+#     Chromium, so we install playwright globally just for its
+#     `playwright install chromium` downloader, then point agent-browser at
+#     the resulting binary via AGENT_BROWSER_EXECUTABLE_PATH. agent-browser
+#     honours that env var (priority: CLI flag > env > config file >
+#     built-in default; see agent-browser's README).
+#
+# Runtime state (sessions, auth cookies under ~/.agent-browser/) lives in the
+# container's writable layer, preserved across pause/unpause/stop/start and
+# wiped on `agentbox destroy`.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        libnss3 libnspr4 libatk1.0-0t64 libatk-bridge2.0-0t64 libcups2t64 \
+        libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 \
+        libgbm1 libdrm2 libpango-1.0-0 libcairo2 libasound2t64 \
+        fonts-liberation xdg-utils \
+    && rm -rf /var/lib/apt/lists/*
+
+RUN npm install -g agent-browser playwright
+
+# Download Chromium as `vscode` so the ms-playwright cache lands in vscode's
+# home (the user agent-browser runs as). The downloaded binary lives at
+# `chromium-XXXX/chrome-linux/chrome`, where XXXX is a Playwright-internal
+# revision number that changes between releases — we resolve it once here and
+# write the result to a stable symlink so AGENT_BROWSER_EXECUTABLE_PATH can
+# point at something predictable.
+USER vscode
+RUN playwright install chromium \
+    && ln -sf "$(ls /home/vscode/.cache/ms-playwright/chromium-*/chrome-linux/chrome | sort | tail -1)" /tmp/chromium-link \
+    && test -x "$(readlink /tmp/chromium-link)"
+USER root
+RUN mv /tmp/chromium-link /usr/local/bin/chromium
+
+ENV AGENT_BROWSER_EXECUTABLE_PATH=/usr/local/bin/chromium
+
+# VNC: Xvnc (TigerVNC, X server + RFB in one binary), noVNC (HTML5 client),
+# websockify (the WS<->RFB proxy noVNC needs). No window manager: a Chromium
+# launched with DISPLAY=:1 fills the screen, and agents drive tabs through the
+# browser itself. Adding a WM would cost another ~10MB and complicate the
+# lifecycle for no win.
+#
+# autocutsel: with no WM, nothing owns the X11 CLIPBOARD/PRIMARY selections, so
+# the text noVNC delivers via RFB cut-text isn't reliably served back to
+# Chromium on Ctrl+V. autocutsel (one daemon per selection, started by
+# agentbox-vnc-start) keeps both selections populated and in sync. xclip is
+# kept alongside it purely for debugging the clipboard round-trip.
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends \
+        tigervnc-standalone-server tigervnc-common tigervnc-tools \
+        novnc websockify \
+        autocutsel xclip \
+    && rm -rf /var/lib/apt/lists/*
+
+# DISPLAY is image-baked so every `docker exec` (the claude tmux session,
+# `agentbox shell`, any agent subprocess) inherits it. Anything launched
+# without an explicit DISPLAY override renders to the VNC session.
+ENV DISPLAY=:1
+
+# EXPOSE 6080 is load-bearing for OrbStack. OrbStack maps
+# `<container-name>.orb.local` to the container's single EXPOSE'd port; without
+# this, the auto-DNS responds but nothing is routed. (Docker Desktop doesn't
+# use EXPOSE for routing — it just needs the `-p` flag passed at `docker run`.)
+EXPOSE 6080
+# Web service port. The canonical host-reachable URL is the published loopback
+# port (`-p 127.0.0.1:0:80`, resolved per box); EXPOSE 80 is only an OrbStack
+# bare-domain bonus and is not load-bearing (OrbStack honors a single EXPOSE).
+EXPOSE 80
+
+# Pre-create the per-user .vnc dir so it's writable from the runtime user. The
+# password file itself is written at container start by agentbox-vnc-start
+# (derived from AGENTBOX_VNC_PASSWORD).
+RUN mkdir -p /home/vscode/.vnc \
+    && chown -R vscode:vscode /home/vscode/.vnc
+COPY packages/sandbox-docker/scripts/agentbox-vnc-start /usr/local/bin/agentbox-vnc-start
+RUN chmod +x /usr/local/bin/agentbox-vnc-start
+
+# DinD launcher script. Same exec-d-as-root pattern as agentbox-vnc-start.
+COPY packages/sandbox-docker/scripts/agentbox-dockerd-start /usr/local/bin/agentbox-dockerd-start
+RUN chmod +x /usr/local/bin/agentbox-dockerd-start
+
+# 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
+# get broken across visual wrap boundaries. The WheelUp/Down rebinds drop the
+# copy-mode scroll step from the built-in 5 lines to 2 — a macOS trackpad
+# swipe emits a burst of wheel events, so the default flies past dozens of
+# lines on a single flick.
+RUN printf '%s\n' \
+        '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 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' \
+        > /etc/tmux.conf
+
+# System-wide Claude Code hint. NOTE: /etc/claude-code/CLAUDE.md is not a
+# documented Claude Code load path today (only /etc/claude-code/managed-settings.json
+# is, and that's settings-only) — kept here so it's discoverable via
+# `cat /etc/claude-code/CLAUDE.md` and forward-compatible if Claude Code
+# adds it to its memory chain. Until then, in-box agents learn the same
+# facts via /etc/agentbox/box.env + AGENTBOX_* env vars. Content lives in
+# scripts/custom-system-CLAUDE.md (edit there, not inline) for maintainability.
+RUN mkdir -p /etc/claude-code
+COPY packages/sandbox-docker/scripts/custom-system-CLAUDE.md /etc/claude-code/CLAUDE.md
+RUN chmod 0644 /etc/claude-code/CLAUDE.md
+
+# Enterprise-managed Claude Code settings: activity-reporting hooks. Highest
+# precedence and NOT synced from the host ~/.claude, so the host-hook filter
+# never touches it; hook arrays merge across settings sources, so the user's
+# own hooks still run. Drives `agentbox status/list/inspect` claude activity.
+# (Build context is the monorepo root — see BUILD_CONTEXT_DIR in image.ts.)
+COPY packages/sandbox-docker/scripts/claude-managed-settings.json /etc/claude-code/managed-settings.json
+RUN chmod 0644 /etc/claude-code/managed-settings.json
+
+# /etc/agentbox/ holds runtime-injected box.env (written by `agentbox create`
+# via docker exec). Pre-created here so the writable layer starts with the
+# right perms; the file itself appears at create time.
+RUN mkdir -p /etc/agentbox && chmod 0755 /etc/agentbox
+
+# Login-shell shim: source /etc/agentbox/box.env so `agentbox shell <box>` and
+# any `bash -l` see AGENTBOX_* even when launched outside `docker run`'s env
+# (e.g. interactive shells). `set -a` exports every sourced var.
+RUN printf '%s\n' \
+        '# Auto-loaded by login shells; box.env is written by `agentbox create`.' \
+        'if [ -r /etc/agentbox/box.env ]; then' \
+        '  set -a' \
+        '  . /etc/agentbox/box.env' \
+        '  set +a' \
+        'fi' \
+        > /etc/profile.d/agentbox.sh \
+    && chmod 0644 /etc/profile.d/agentbox.sh
+
+# Default to the vscode user (UID 1000) provided by base:ubuntu. The overlay
+# mount itself happens via `docker exec --user root`, so this is just the
+# default identity for interactive shells.
+USER vscode
+WORKDIR /workspace