One Docker container with its own unprivileged sshd, published only on the node's Tailscale address. A
herdr client on a laptop attaches to it as a saved machine and runs OMP, Claude Code and
Codex agents inside — the container is the agent sandbox.
📚 Documentation · Installation · Connecting · Git identities · CLI
| Feature | What it gives you |
|---|---|
| Agent sandbox | Agents with bypassed permissions reach the project tree, the internet and LAN, and a rootless project Docker daemon only |
| Tailnet-only access | One sshd port, published on the Tailscale address (BIND_ADDR) and loopback — never 0.0.0.0 |
| No private keys | Public keys only; manual git borrows the laptop's 1Password agent, agent git gets HTTPS and per-operation tokens |
| Multiple identities | One identities.conf routes git author, signing key and GitHub token by directory and GitHub owner |
| Project Docker | docker compose against a rootless sibling daemon, with path identity and project ports kept off the Tailnet |
| Persistent workspace | herdr panes survive client exit; /home/dev is a host bind mount that survives every rebuild |
| One CLI, both sides | ./bin/devbox for workstation and laptop, with a doctor acceptance test on each |
Important
The container is the sandbox: agents never reach the host filesystem, the host's root Docker daemon or a private key — the box holds public keys only. It contains authority, not data: outbound internet is unrestricted and the LAN is reachable — only the host's own services and the Tailnet overlay are blocked — so assume anything inside can leave. See Security model.
Setup spans the laptop, the workstation and 1Password, so let an agent drive it. You need a workstation running Ubuntu 26.04 LTS with Docker and Tailscale ≥ 1.98, and a laptop with 1Password and OMP, Claude Code or Codex.
Clone this repo on the laptop, start the agent in the checkout (each loads the repo's devbox-setup and
devbox-laptop skills) and paste:
Set up the devbox from this checkout. My workstation is <workstation>, reachable over Tailscale.
Follow the devbox-setup skill phase by phase and run each phase's check before moving on, then set up
the laptop side with the devbox-laptop skill. Stop and hand me every step that needs me: 1Password
items and approvals, sudo passwords, interactive logins, tokens and identities.conf values.
Done means `./bin/devbox doctor` passes on the workstation and `./bin/devbox doctor laptop` here.
Then run herdr and open panes on the Devbox machine, or ssh devbox for a plain shell. Prefer doing it by hand?
Every step is in Installation.
Warning
start, stop and rebuild recreate or stop the container and drop every live SSH session and herdr pane; they ask
first unless --force is given. update upgrades the agent tools in place and never does.
Everything else — architecture, installation, connecting, git identities, secrets, toolchain, networking, project Docker, operations, security, CLI and development — lives in docs/.
| Item | Details |
|---|---|
| Maintainer | @rozsival (see CODEOWNERS) |
| Issues | GitHub Issues |
| License | MIT |