I have a mini PC that runs my AI coding agents. It’s a headless Debian 13 box with 4 CPUs and 15 GB of RAM, I reach it over Tailscale, and agents like Claude Code and Codex work on it all day without asking me for permission.
Getting it there took a lot of small fixes, and I didn’t want to redo them by hand the next time. So I wrote agbox: one command that turns a fresh Debian or Ubuntu machine into that same setup.
curl -fsSL https://raw.githubusercontent.com/antomanc/agbox/main/install.sh | bashWhy I built it
I wanted a clean, repeatable way to get a working agent machine out of my mini PC. Once it worked, I realized nothing in it was specific to my hardware: the same steps work on an old laptop, a $5 VPS, or a machine I set up for a client or a friend.
The problems I kept running into were boring, and that’s what made them annoying:
- Ubuntu’s AppArmor blocks the bubblewrap sandboxes that Claude Code and Codex use on Linux
nodeworks in my shell but not in the agent’s shell- a password prompt in the middle of a task stops the agent until I come back
- services die on reboot
- the same database ends up installed three different ways
None of these is hard to fix on its own. Fixing all of them, on every machine, in the same way, is the part I wanted a tool for.
What it sets up
agbox installs the agents (Claude Code, Codex and opencode) and gives them one shared AGENTS.md that tells them what the machine is and how to work on it. On my box that file says things like “databases run with docker compose, bind ports to 127.0.0.1” and “dev servers bind to 0.0.0.0 so I can open them over Tailscale”. Claude Code reads it through a one-line import in CLAUDE.md, so I only edit one file.
Toolchains come from mise, set up so Node, Python, uv and pnpm work in interactive shells, agent shells and systemd services alike. Docker Engine and Compose handle Postgres, Mongo and Redis. Playwright gets headless Chromium with all its system libraries, so agents can actually test the web apps they build.
For access there’s Tailscale with Tailscale SSH, so no ports are open to the internet. Small machines get zram compressed swap and Docker log rotation. Optionally it also runs t3code and Hermes Agent as always-on services.
The machine is the sandbox
This is the opinionated part. By default agents run as a normal, non-root user with passwordless sudo and no approval prompts.
Claude Code and Codex sandbox their commands with bubblewrap, and on Ubuntu 24.04+ that fails often enough that agents either keep asking for approvals or fall back to running unsandboxed anyway. On a dedicated machine I’d rather put the safety around the box:
- btrfs snapshots every hour, so I can roll back anything an agent breaks
- git for the code, and
AGENTS.mdtells agents to commit often - Tailscale instead of open ports, plus a firewall and key-only SSH on a VPS
- no valuable secrets on the machine in the first place
If the box gets messed up badly enough, I reinstall it. That’s fine for a disposable machine and a terrible idea for your daily laptop, so don’t run it there. If you want prompts and sandboxes back, it’s one setting:
agbox setup --set AGENT_MODE=sandboxed --set PASSWORDLESS_SUDO=falseThe security doc has the full reasoning.
How it works
agbox is plain Bash with no dependencies, because it has to run on a machine that has nothing installed yet. It’s also short enough to read before you pipe it into a shell, which you should do with any curl | bash.
Before changing anything it shows a plan and asks Apply? [Y]es / [n]o / [c]ustomize. Customize asks a few questions (profile, agents, services, user, hostname, timezone, git identity) and saves the answers to /etc/agbox/agbox.conf, so the next run starts from them.
Every step checks before it acts, so re-running agbox setup is how you update and repair the machine. --dry-run prints every command and file write without doing anything. When agbox edits your files, like ~/.bashrc or CLAUDE.md, it only touches its own marked block.
agbox doctor checks everything and prints the fix for each problem. That’s what the recording above shows.
For a brand new mini PC there’s also a fully unattended path: agbox preseed generates a Debian preseed file, you boot it from a Ventoy stick and walk away, and the first boot runs agbox setup.
agbox preseed --hostname home-server --ssh-key ~/.ssh/id_ed25519.pub -o preseed.cfgTry it
On an existing Debian 12/13 or Ubuntu 24.04/26.04 machine, run the curl command at the top as your normal user. For a fresh VPS, run it as root with --profile vps. That creates a dev user with your SSH key and locks the box down. The README has the details.
When it’s done, it prints the few things only you can do, like logging the agents in and running gh auth login.
agbox prepares the machine. For the project side (instructions, skills and test tooling for each repo) I wrote a companion tool, aginit.