v1.8.0: named instances, read-only status gate, bot guide

Devbox Anywhere v1.8.0: named instances, read-only status gate, bot guide

v1.8.0 lets a hosted bot (or any script) watch a devbox without getting a shell, and lets you run a second, separate devbox on the same server for it. Everything is opt-in. An existing install behaves as before, with one new helper that does nothing until you configure it.

What's new

• Named instances: install-devbox --instance NAME --web-port P --ssh-port P [--with-browser --browser-port P] creates a second devbox with its own data root (/data/devbox-NAME), container, Compose project (devbox-NAME) and loopback ports.
  • The name is validated strictly. Reserved names and the default ports are refused, and so is a port that is already in use (it fails closed when ss is missing).
  • It refuses to adopt a container it didn't create, and never takes a path (--data-root is still rejected).
  • devbox-anywhere plan|verify|diagnose|preflight accept --instance.
• devbox-status-gate: a read-only forced command for an SSH key (restrict,command="/home/coder/.local/bin/devbox-status-gate" ssh-ed25519 ...).
  • It allows exactly version, list and status <project> [--json]. Anything else is denied with exit 126.
  • It runs the status tool in a clean environment and keeps an owner-only audit log, rotated once at 256 KiB.
  • It is installed and checked by verify like the other helpers, and does nothing until you add a key line.
• Status board fix: status now proves an agent's tmux window exists before it reads activity. It matches the exact name, then addresses the window by id. An agent with no window reads unknown, not another window's activity. An ambiguous or forged window is never reapable.
• Status hardening:
  • Every pane of a split window counts toward activity.
  • Turn output is parsed fail-closed, and the turn lock's timestamp is validated.
  • JSON escapes control bytes and invalid UTF-8, and the table prints only printable ASCII.
  • status no longer takes git's index lock.
  • An unreadable worktree marks only that agent as error.
  • Registry rows are read byte-wise in every locale.
• New guide: docs/14: Let a bot manage your devbox. It covers a separate instance for the bot, the gate, a forwarding-only tunnel account and compromise recovery. It states the trust model plainly: the gate protects the instance from the bot's key, not the reverse.
• docs/03 gains "Running a second instance", and docs/13 corrects the reapable rules.

Upgrading from v1.7.x

1. Move your approved checkout to the v1.8.0 commit.
2. Re-run the installer with the same flags you first installed with (--expose-ssh, --with-browser). A bare re-run moves SSH back to loopback and leaves the browser out.
3. Until you re-run, verify reports the new helper.devbox-status-gate check as failing. That is expected.

status --json objects gain an additive error field. schema_version stays 1. If a consumer checks the exact set of keys, allow the new one.

Testing

• Test suites: the full suite passes on macOS (bash 3.2) and Linux (bash 5.2 with real tmux), with 156/156 named mutation reds.
• Container smoke on a disposable Ubuntu 24.04 Docker-in-Docker host: 65/65 checks pass.
  • The default install is unchanged.
  • Refusals happen before anything is built.
  • A second instance runs beside the default without recreating it, and each instance's re-run leaves the other alone.
  • Through real sshd, the gate allows its three commands and denies injection, shells, login and port forwarding.
  • Removing the instance leaves the default running.
• Review: the whole branch was reviewed independently across installer security, gate security, docs vs code, test quality and release hygiene, and the fixes were reviewed again. All 28 confirmed findings were fixed.

Base: v1.7.0.

v1.7.0: agent status board

Devbox Anywhere v1.7.0 — agent status board

devbox-session status <project> shows every agent on a project at a glance: what each one has done, who holds the turn, and which agents are safe to clean up. It's a native tmux + git implementation, with no external binary.

$ devbox-session status webapp
project=webapp session=webapp base=auto  (activity is a heuristic)
webapp-api       dirty        +3/-0  turn:alice      working
webapp-web       new          +0/-0  turn:free       idle
webapp-cli       merged       +2/-0  turn:free       idle      (reapable)

What's new

• Git facts you can trust: new | new+dirty | clean | dirty | merged | merged+dirty, +ahead/-behind against the base branch, and the devbox-turn holder. Uncommitted work is never hidden behind another state.
• new vs merged: a just-created agent with no commits is new, never merged. devbox-worktree add now records the fork point as an optional 4th registry column.
• (reapable) = merged, clean, turn free, and not currently working. Only then is devbox-worktree remove <project> <agent> safe. A new or still-working agent is never reapable.
• Activity is a labeled HEURISTIC: working | idle | blocked | unknown, read from the tmux pane.
  • working = any non-shell foreground process. An agent CLI idle at its own prompt reads working, so treat it as "a CLI is open here", not "busy".
  • blocked = a waiting-for-input prompt (y/n, password, question) stalled past DEVBOX_STATUS_STALE (default 60s).
  • An unreadable pane is unknown, never guessed.
• --json: a schema-versioned document, one object per agent, "activity_confidence":"heuristic".
• Fails closed: an unknown project errors. A registered worktree that no longer exists shows MISSING, and the command doesn't crash.

Upgrading from v1.6.x

No migration needed. Existing 3-column registry rows keep working. For agents created before the upgrade, status falls back to the branch reflog to tell new from merged. If that reflog is unreadable, the agent is never marked reapable (fail-safe). New agents get the 4th column automatically.

Scope

Runtime changes are limited to scripts/devbox-session (the new status subcommand) and scripts/devbox-worktree (records the fork point). Every registry reader accepts both 3- and 4-column rows. The installer, harness and other helpers are unchanged.

Testing

• Full canonical suite green, 62/62 named mutation reds, on BOTH a macOS host without tmux and a Linux host with tmux. The activity probe is guarded by a fake-tmux test that runs everywhere, plus a real-tmux test where tmux exists.
• Live test on a real devbox in an isolated tmux server, registry and worktree root, with legacy agents created by the shipped v1.6.1 devbox-worktree and new agents added after the upgrade into the same registry. All of these read correctly:
  • y/n prompt → blocked
  • fresh agents, idle and busy → new, not reapable
  • really merged → merged (reapable)
  • legacy agent without a reflog → not reapable
  • fresh with uncommitted work → new+dirty
  • remove/list on mixed rows work

Base: v1.6.1 (d58d3da).

v1.6.1: verify no longer flaps under repeated runs

Devbox Anywhere v1.6.1 — verify no longer flaps under repeated runs

Fixes the known issue listed in v1.6.0.

Fixed

• verify could return a false ok: false when run repeatedly (present since v1.2.0). service.ssh (and the installer's readiness probe) checks sshd with an unauthenticated ssh-keyscan 127.0.0.1 from inside the container. OpenSSH 10's default PerSourcePenalties gives each such connection a noauth penalty, so roughly 15 quick runs, such as an agent retrying verify until green, made sshd refuse loopback. service.ssh then failed until the penalty expired. The shipped sshd config now sets PerSourcePenaltyExemptList 127.0.0.1,::1. Only in-container processes connect from loopback, and remote clients arrive via the bridge, so brute-force protection for real remote sources is unchanged.

Scope

One line in stack/config/devbox-sshd.conf, which takes effect on the image rebuild your upgrade already does. No helper, installer or harness changes.

Testing

• Full canonical suite green, 52/52 named mutation reds. The new invariant test derives the loopback addresses the probes actually use from the real devbox-anywhere and install-devbox, so the exemption can't drift from the probe.
• Real-upgrade container smoke 41/41 PASS on Ubuntu 24.04 / Docker 29.1.3 / Compose v2.40.3 (v1.5.0 → this release, full v1.6.0 gate plus a new hammer step):
  • the running sshd reports the exemption
  • 25 back-to-back verify runs all returned ok: true (21 of 25 failed before the fix)
  • service.ssh still passed after 30 additional raw keyscans

Base: v1.6.0 (b01d835).

v1.6.0: rebuild safety — upgrade-safe drop-ins, verify invariants, supervised daemons

Devbox Anywhere v1.6.0 — rebuild safety: upgrade-safe customization, honest verify, supervised daemons

Your customizations now survive an upgrade, verify checks the things that actually break after a rebuild, and long-running agent gateways come back on their own.

What's new

• Upgrade-safe relink drop-ins. Add your own persistent links as ~/.local/share/devbox-relink.d/*.conf files: one literal <target> <link> pair per line, absolute paths, no $HOME. They load after the shipped links in LC_ALL=C order, and a later file wins. A missing source, malformed line or unreadable directory is reported and skipped, never linked wrong.
• Upgrades preserve your edits. If an upgrade would overwrite a helper you changed, the installer first copies it to <helper>.pre-upgrade.<utc>.bak and prints a machine-readable PRESERVED notice. For devbox-relink it also lists any custom relink lines (CUSTOM_RELINK_LINE …) so you can re-add them as drop-ins. They aren't migrated automatically. Unchanged helpers are left alone.
• verify checks the hands-off invariants (warn-only, schema v2).
  • relink.targets warns when a managed link is broken: a shipped default that's missing or replaced by a real file/dir, or a drop-in whose source is gone.
  • daemon.<name> warns when a declared daemon isn't running.
  • Both are warn-only, so they never flip ok and never block an install that was fine before.
• devbox-daemon — declare a long-running process in ~/.local/share/devbox-daemons.d/<name>.conf (name, command, optional tmux_session). It starts last at every boot, idempotently, and comes back after a container rebuild with no human action. verify delegates liveness to it. docs/10 describes the rebuild-safe path for messaging gateways (hermes gateway install isn't usable in this image because systemd isn't PID 1).

Fixed

• gh auth login couldn't persist on a fresh install (present since v1.0). ~/.config/gh was a dangling link until the store existed, and gh's directory-create fails against a dangling link (mkdir …/.config/gh: file exists). devbox-relink now pre-creates the directory sources (gh-config, terminfo). File sources (gitconfig) still write through as before. docs/09 explains which is which.

Upgrading from v1.5.x

Run the installer from the new release as usual. If you hand-edited ~/.local/bin/devbox-relink, read the PRESERVED / CUSTOM_RELINK_LINE output and move those lines into a drop-in. Your backup stays next to the helper.

Known issue (pre-existing, fix planned for v1.6.1)

verify's service.ssh check probes sshd with an unauthenticated ssh-keyscan from inside the container. OpenSSH 10's default PerSourcePenalties blocks 127.0.0.1 after about 15 rapid probes, so running verify many times in a row can return a false ok: false that heals by itself a few minutes later. This has been present since v1.2.0. If you script retries, space them out.

Testing

• Full canonical suite green, 51/51 named mutation reds. New tests run the real verify probe against the real shipped devbox-relink in a clean HOME, not canned output.
• Real-upgrade container smoke PASS on Ubuntu 24.04 / Docker 29.1.3 / Compose v2.40.3: a v1.5.0 install with an in-file custom relink, upgraded to this release. It covered preservation notices and backup, drop-in re-add, an idempotent re-run, verify pass/warn behavior on healthy, dangling and absent links, gh and git write-through on a fresh box, and a daemon plus drop-in link restored after compose down/up. The only failure was the known service.ssh issue above, root-caused and reproduced on its own.

Base: v1.5.0 (9190eba).

v1.5.0: worktree post-add hook + dependency policy

Devbox Anywhere v1.5.0 — worktree post-add hook + dependency policy

Addresses the first practical snag from real use: a freshly created agent worktree has no installed dependencies, so an agent dropped into it hits missing-dependency errors.

What's new

• DEVBOX_WORKTREE_POSTADD hook — an optional command run inside the new worktree right after the agent is created, so dependencies install automatically:

  DEVBOX_WORKTREE_POSTADD='npm ci' devbox-worktree add webapp webapp-api

  If the hook fails, add exits non-zero but keeps the worktree, branch, and registration, so you can fix the environment and re-run the install without recreating the agent.
• docs/13 "Dependency policy" — install dependencies per worktree; explicitly warns against sharing node_modules/venv across worktrees (native-module corruption, install races, invisible lockfile drift), and suggests a content-addressed store (pnpm, uv cache) if disk or install time is a concern.

Scope

Only scripts/devbox-worktree changes at runtime (the new post-add path); the installer, harness, and other helpers are unchanged from v1.4.1.

Testing

• Full canonical suite green; 39/39 named mutation reds (incl. a new red proving a failing hook is surfaced, not swallowed).
• Live helper-slice smoke PASS on Ubuntu 24.04 x86_64 / Docker 29.1.3 / Compose v2.40.3, against a real v1.4.1 base install: the hook runs with cwd = the new worktree, a failing hook exits non-zero while keeping the worktree + registration, and the no-hook path is unchanged.

No known blockers within the reviewed and tested scope. Base: v1.4.1 (1e50295).

v1.4.1: sanitization — neutral test fixtures

Devbox Anywhere v1.4.1 — sanitization: neutral test fixtures

Patch release over v1.4.0. No installer, harness, or helper-script changes — the installable and runtime bytes are identical to v1.4.0. This release only sanitizes documentation and test fixtures, so v1.4.1 is the clean, honest artifact to install.

Changes

• Neutral test/doc fixtures — the v1.4.0 tests and docs/13 used a private project name as the example fixture. Renamed to the neutral webapp across all fixtures and examples (pure rename, no logic change).
• Removed a local planning document that had been committed to the branch, and added .hermes/ to .gitignore so local planning/scratch can no longer travel with a branch.

Unchanged from v1.4.0

Multi-channel sessions with multiple agents — devbox-session, devbox-turn, devbox-worktree, installer + harness integration, and the always-on/opt-in browser layers from v1.3.0. See the v1.4.0 notes for the full feature description.

Testing

• Full canonical suite green; 38/38 named mutation reds.
• The v1.4.0 feature was validated by a 10/10 live smoke on Ubuntu 24.04 x86_64 / Docker 29.1.3 / Compose v2.40.3. Because v1.4.1 changes only docs and test fixtures (no runtime/installer bytes), that validation carries over unchanged.

No known blockers within the reviewed and tested scope. Base: b92a704.

v1.4.0: multi-channel sessions with multiple agents

Devbox Anywhere v1.4.0 — Multi-channel sessions with multiple agents

Any channel Hermes is connected to (a terminal over SSH, a Telegram topic, a Slack channel) can drive the same project work, and multiple agents can work one project in parallel without colliding. The box, not any single chat, is the source of truth.

Model

project   -> one tmux session            shared "room"; every channel resolves to it
agent     -> one window + one worktree    own checkout + branch = real parallel isolation
channel   -> project:window | session     a control surface (channels live in Hermes config)
turn-lock -> per worktree                 one writer per checkout (advisory coordination)

What's new

• devbox-session — resolve project → tmux session and project:agent → session/window/worktree/branch. Fails closed on unknown/off-convention/duplicate/malformed/traversal input.
• devbox-turn — per-worktree one-writer lock. Atomic acquire, explicit take/release, holder-only release, stale-lock reclaim past DEVBOX_TURN_TTL, and refuses a nonexistent worktree. Advisory coordination, not a security boundary.
• devbox-worktree — add/list/remove an agent's git worktree + agent/<agent> branch + tmux window. add rolls back atomically on failure; remove refuses a dirty worktree without --force.
• Installer + harness integration — install-devbox copies the three helpers into the container ~/.local/bin (persistent mount); the harness verify reports helper.devbox-{session,turn,worktree}.
• Docs + skill — docs/13-multi-channel-multi-agent.md, an 8th skill reference, README v1.4.0 section.

Design boundaries

• Channels are Hermes configuration, not part of this repo — no channel adapters or per-channel auth code here.
• Agent ids must be <project>-<suffix>; worktrees live under ~/project/.worktrees/<agent> (persistent).
• Chat surfaces show snapshots/streams, not a live TUI mirror.
• Every wired channel carries the devbox account's full terminal authority — not a sandbox.

Also fixed

• Default install on Docker Compose v2.40+ — DEVBOX_BROWSER_PASSWORD is now generated unconditionally, so compose build no longer fails interpolating the profile-gated browser service on a default (no-browser) install. (Latent since v1.3.0.)

Testing

• Full canonical suite; 38/38 named mutation reds.
• 10/10 live smoke PASS on Ubuntu 24.04 x86_64 / Docker 29.1.3 / Compose v2.40.3: default install, harness verify with the three new helper checks, two agents with independent worktrees/branches, resolver, turn-lock refusing a second writer, dirty-remove refused + forced teardown, loopback-only bindings.

No known blockers within the reviewed and tested scope. Base: v1.3.0 (028b3cb).

Devbox Anywhere v1.3.0

Devbox Anywhere v1.3.0 — Browsers & authenticating to services

Gives the devbox a browser when it needs one, in three layers (safest first), without weakening the loopback-by-default, human-only-secrets, explicit-exposure model. scripts/install-devbox remains the sole privileged installer.

Headless browser (always on)

• A pinned Playwright + Chromium with OS dependencies is baked into the image (offline-ready) for tests, screenshots, scraping, and link checks.
• devbox-browser-check smoke helper launches headless Chromium and fails loud on any error.

Auth playbook (documentation, no new services)

• docs/12-browser-and-auth.md: token-first authentication — including Cloudflare API tokens, Access service tokens, and tunnel tokens — SSH-forwarded OAuth callbacks, and guidance on when a real browser is actually required.
• A seventh Hermes umbrella-skill reference, references/browser-and-auth.md.

Opt-in interactive browser (--with-browser)

• A loopback-only KasmVNC Chromium service (linuxserver/chromium, pinned by digest) behind a Compose browser profile — off by default.
• install-devbox --with-browser binds 127.0.0.1:8081 only, generates an owner-only noVNC password (never printed), and persists the browser profile under /data/devbox/browser so completed logins survive rebuilds.
• The agent harness plan --json --with-browser reports the listener and the additional approval and appends the flag to the install command; default plans are unchanged.
• Reach it over the existing SSH tunnel or an authenticated proxy / Cloudflare Access. Never expose port 8081 publicly. The interactive browser is a convenience, not a sandbox.

Also in this release

• The install test fixture is now POSIX-sh (previously bash-only printf %q), so the canonical suite passes under dash.

Verification

• Canonical suite passes (all gates) with 29 named mutation reds.
• A full real-build smoke on an x86_64 Debian/Ubuntu Docker host passed end-to-end: image build, headless Chromium, install-devbox --with-browser, harness verify returning ok: true (all 8 checks), and the noVNC endpoint answering on loopback 8081.

Supported install target is Debian/Ubuntu (GNU coreutils and /usr/bin/python3). Within the reviewed and tested scope, there are no known blockers.

Devbox Anywhere v1.2.0

Devbox Anywhere v1.2.0

This release adds a secure, agent-oriented operating layer for Devbox Anywhere while keeping scripts/install-devbox as the sole authoritative privileged installer.

New: deterministic agent harness

scripts/devbox-anywhere provides schema-versioned JSON and stable check IDs for terminal-capable assistants:

• preflight checks Linux, required tools, Compose v2, and local Docker availability.
• plan validates an exact installer-bearing commit and reports paths, listeners, approvals, and the installer command without changing the server.
• verify validates trusted installer state, expected ports and writable mounts, helper installation, and HTTP/SSH readiness.
• diagnose reports failed checks and safe recovery information without mutating the installation.

New: Hermes umbrella skill

skills/devbox-anywhere/ packages the operating workflow for Hermes Agent, with six references covering:

• installation and upgrades;
• verification and diagnosis;
• Telegram project topics;
• coding-agent handoffs;
• backups, restoration, and rebuilds;
• security and approval boundaries.

Install the skill by copying its complete directory from this exact verified stable checkout. Start a new Hermes session afterward so the skill index refreshes.

Security and reliability hardening

• Privileged installer and harness Docker operations use an isolated Docker configuration and the local built-in default context.
• Stable-release and exact-commit source validation remain mandatory.
• The privileged checkout remains fixed at /opt/devbox-anywhere; persistent state remains fixed under /data/devbox.
• code-server and container SSH remain loopback-only by default.
• Public container SSH still requires explicit --expose-ssh selection and separate firewall preparation.
• Human approval remains required before sudo, container build/start, firewall, or public-network effects.
• Machine-readable parser errors do not reflect arbitrary or secret-shaped arguments.

Documentation and proof

• README now explains the Hermes skill and harness, their four commands, installation, and security boundaries.
• Canonical tests cover installer acceptance, exact Compose semantics, lifecycle and source trust, the agent harness, Hermes packaging, runner inventory, and 24 named mutation reds.

Within the independently reviewed and tested scope, there are no known release blockers. A complete real image build/runtime installation was not performed on the review hosts because Docker was unavailable there.

Devbox Anywhere v1.1.0

Devbox Anywhere v1.1.0

This release adds the secure, agent-guided installation workflow for Claude Code, Codex, Hermes Agent, and other terminal-capable assistants.

Highlights

• Adds AGENTS.md and a reusable guided-install prompt.
• Adds scripts/install-devbox with a dry-run-first approval flow and explicit --yes for noninteractive installation.
• Requires an exact installer-bearing stable release commit and a clean, root-owned checkout at /opt/devbox-anywhere before privileged Docker operations.
• Sanitizes Git, Docker, and Compose environments and compares checkout bytes with the approved commit.
• Keeps code-server and container SSH loopback-only by default; public SSH requires explicit --expose-ssh and firewall preparation.
• Uses fixed, root-controlled persistent storage under /data/devbox and owner-only atomic secret state.
• Adds canonical acceptance, Compose-model, lifecycle, source-trust, failure-boundary, and mutation tests.
• Clarifies private SSH tunnelling, public/Coolify mappings, and provider handoff guidance.

Verification

The exact release commit passed independent security, functional, usability, privacy, and immutable-artifact review with no known blockers in the reviewed scope. The canonical repository test suite passed before publication.

A complete real Docker image build/runtime installation was not available on the review hosts. Compose semantics and installer lifecycle were validated through exact model checks, mocked lifecycle tests, source-trust probes, and mutation tests; this is not a claim of absolute security.

Upgrade and installation

Follow Agent-guided installation. Existing installations should review the release instructions and preserve backups before changing their deployment.