A safe little home for your coding agents

The files: nickypro/.vps-dotfiles › agent-box. Its README has every detail; this page is the tour.

Your devices only talk to the server. It passes traffic to the container over its loopback address (127.0.0.1), so the container adds no new doors to the internet. Backups leave from the server, never the container.

Your home folder, data and logins live on the host, so make rebuild can replace the container without losing anything.

Assume that sooner or later an agent follows an instruction it shouldn’t. The setup tries to make that boring.

The network guard

A small nftables firewall on the host, in its own table so Docker and ufw leave it alone. The internet works; an attacker’s usual next steps don’t.

T3’s web UI is a terminal with sudo, so who can reach it matters. Pick with ACCESS in config.mk; to switch, change it and rerun sudo make host-config.

About an hour. The commands are in the dropdowns; this guide uses sudo make … throughout.

1. 1

   Prepare the server on the server

   Ubuntu or Debian with 4 GB of RAM or more, and Docker Engine with its compose plugin. Then a few tools, a firewall, key-only SSH and some swap.

   Commands

   sudo apt install -y git make fail2ban nftables jq
   sudo ufw allow OpenSSH
   sudo ufw allow 80,443/tcp        # only for the mtls or public modes
   sudo ufw enable
   
   # keys only (check your key logs you in first)
   printf 'PasswordAuthentication no\nKbdInteractiveAuthentication no\n' \
     | sudo tee /etc/ssh/sshd_config.d/10-keys-only.conf
   sudo systemctl reload ssh
   
   # swap, so a busy agent has room
   sudo fallocate -l 8G /swapfile && sudo chmod 600 /swapfile
   sudo mkswap /swapfile && sudo swapon /swapfile
   echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

2. 2

   Get the files on the server

   Clone the repo, make the storage and list your SSH keys. For a mode other than tailscale, set ACCESS in config.mk now (and DOMAIN, for mtls or public).

   Commands

   git clone https://github.com/nickypro/.vps-dotfiles
   cd .vps-dotfiles/agent-box
   sudo mkdir -p /srv/agent-box/{home,data,cells}
   sudo chown 1000:1000 /srv/agent-box/{home,data}   # uid 1000 = the dev user inside
   cp authorized_keys.example authorized_keys
   nano authorized_keys                        # your SSH public keys, one per line

   Memory and CPU caps are in docker-compose.yml; the defaults suit a 4-core, 8 GB server.

3. 3

   Build it and fence it in on the server

   About 10 minutes. Then net-test should show the cloud metadata service and the host’s SSH blocked, and the internet and DNS open.

   Commands

   sudo make rebuild       # build the image and start the container
   sudo make guard-link    # the firewall that keeps the container off the host
   sudo make net-test      # what the container can and can't reach
   sudo make doctor        # checks everything that has broken before

4. 4

   Turn on the web UI (or don’t) on the server

   Open the one for your mode.

   tailscale recommended

   curl -fsSL https://tailscale.com/install.sh | sh
   sudo tailscale up
   sudo make host-config   # runs tailscale serve: T3 on https, your tailnet only

   • In Tailscale’s admin console, turn on MagicDNS and HTTPS Certificates (DNS page), and disable key expiry for this machine.
   • Machine names show up in public certificate logs, so pick a dull one.
   • Never tailscale funnel: it publishes to the whole internet.
   • If other people share your tailnet, add an Access controls rule so only you reach this machine.

   ssh no web UI, experimental

   Set ACCESS = ssh. Nothing to install; this only removes what another mode left serving T3. Skip make pair: the app pairs itself in step 7.

   sudo make host-config   # no nginx site, no tailscale serve

   mtls client certificates

   Set ACCESS = mtls and DOMAIN in config.mk, put the domain in nginx/agent-box-mtls.conf, and point its DNS at the server.

   sudo apt install -y nginx certbot python3-certbot-nginx
   sudo certbot certonly --nginx -d code.example.com
   sudo make ca                         # your own certificate authority, once
   sudo make cert NAME_ARG=laptop       # makes laptop.p12 and prints its password
   sudo make web-passwd USER_ARG=me     # optional: a password for devices without a cert
   sudo make host-config

   Import the .p12 on each device, then delete the server’s copies. Keep the CA key (/etc/nginx/agent-box/ca.key) in exactly one place.

   public password only

   Set ACCESS = public and DOMAIN, put the domain in nginx/agent-box-public.conf, and point DNS at the server.

   sudo apt install -y nginx certbot python3-certbot-nginx
   sudo certbot certonly --nginx -d code.example.com
   sudo make web-passwd USER_ARG=me     # prints a generated password
   sudo make host-config

5. 5

   Connect from your laptop on your laptop

   Add two hosts to ~/.ssh/config, then ssh agent-box. The box only listens on the server’s loopback, so you jump through the server.

   The config

   Host myvps
     HostName your.server.address
     User you
   
   Host agent-box
     HostName 127.0.0.1
     Port 2222
     User dev
     HostKeyAlias agent-box
     ProxyJump myvps
     ForwardAgent no

   • HostKeyAlias files the box’s key under its own name, so it doesn’t clash with anything else on port 2222.
   • ForwardAgent no: every agent has sudo, so a forwarded agent would let any of them log in as you elsewhere. The box refuses it too.
6. 6

   Log the agents in in the box

   Log in to claude, codex and gh once; logins survive rebuilds. For GitHub, prefer a fine-grained token for just the agents’ repos. API keys go in with make secret.

   Commands, and more Claude accounts

   ssh agent-box
   claude          # log in to Claude Code
   codex login
   gh auth login   # or: gh auth login --with-token, with a fine-grained token
   
   sudo make claude-account ACCOUNT=work            # on the server: a second Claude login
   sudo make claude-account ACCOUNT=main LABEL=Me   # give your first one a name too

   Each extra account gets its own name and colour in T3, its own login and history, and a claude-work command. They share your notes and skills in ~/.claude, and every agent starts with box-notes.md, which explains the box to it.

7. 7

   Open T3 any device

   In a browser (tailscale, mtls or public): sudo make pair LABEL=phone prints a pairing link, good for 30 minutes, to open on that device.

   In the T3 desktop app (any mode): add agent-box as an SSH connection. It finds the running server and pairs itself, and every device sees the same threads.

   On Android (experimental): an unofficial T3 build with SSH, by the box’s author and proposed upstream. On an iPhone there’s no SSH app yet, so use a browser mode.

   Setting up the Android app

   It makes its own key (Settings › SSH). Add that to authorized_keys next to the Makefile, and to ~/.ssh/authorized_keys on the server, limited to the jump:

   restrict,port-forwarding,permitopen="127.0.0.1:2222",command="/bin/false" ssh-ed25519 AAAA… t3code-android

   Paste the two Host blocks from step 5 into the app, then Add environment › Or connect over SSH › agent-box. Check the host keys it shows with ssh-keygen -lf on the server: /etc/ssh/ssh_host_ed25519_key.pub, then ssh_host_keys/ssh_host_ed25519_key.pub next to the Makefile.

8. 8

   Turn on backups Backblaze + server

   Optional: about 20 minutes, mostly in Backblaze’s web UI. How it works.

   The bucket in Backblaze’s web UI

   1. Sign up for B2. The signup form is an iframe that ad blockers can hide; if the page looks empty, turn the blocker off for it.
   2. Create a bucket: Private, with Object Lock enabled. No default retention; Kopia sets it on each file.
   3. Lifecycle settings, custom rule: {"fileNamePrefix":"","daysFromHidingToDeleting":15}. Pruned files are only hidden; this deletes them 15 days later so they stop costing money.
   4. App keys: add one for this bucket only, with read and write access. Note the keyID and applicationKey (shown once) and the bucket’s endpoint, s3.<region>.backblazeb2.com.

   The repository as root on the server

   Install kopia, then in a root shell (sudo -i):

   mkdir -p /root/backup && chmod 700 /root/backup
   cat > /root/backup/b2.env <<'EOF'
   B2_KEY_ID=<keyID>
   B2_APP_KEY=<applicationKey>
   KOPIA_PASSWORD=<long and random: openssl rand -hex 32>
   # Optional alerts, see below:
   HC_URL=https://hc-ping.com/<uuid>
   EOF
   chmod 600 /root/backup/b2.env
   
   set -a; . /root/backup/b2.env; set +a
   export AWS_ACCESS_KEY_ID="$B2_KEY_ID" AWS_SECRET_ACCESS_KEY="$B2_APP_KEY"
   kopia repository create s3 --bucket=<bucket> --endpoint=s3.<region>.backblazeb2.com --region=<region> \
     --retention-mode=COMPLIANCE --retention-period=14d --description="agent-box backup"
   kopia maintenance set --extend-object-locks true
   kopia policy set --global --keep-latest 10 --keep-hourly 48 --keep-daily 30 --keep-weekly 8 --keep-monthly 12 --keep-annual 2 \
     --compression zstd-fastest --add-ignore ".cache/" --add-ignore "node_modules/" --add-ignore "__pycache__/" --add-ignore ".Trash*/"
   kopia policy set /root --add-ignore "/backup/" --add-ignore "/.config/kopia/"
   kopia policy set "root@$(hostname):/agent-box-container" \
     --add-ignore "/tmp/" --add-ignore "/var/tmp/" --add-ignore "/var/cache/" --add-ignore "/root/.npm/"
   kopia policy set /etc --add-ignore "/nginx/agent-box/"     # mtls: keep the CA key single-copy
   
   cd /path/to/.vps-dotfiles/agent-box
   make backup-link     # script + systemd units, hourly timer on
   make backup-now      # the first run can take hours

   Put the repository password in your password manager now. It’s the only way to decrypt the backups, and b2.env isn’t backed up.

   For HC_URL, a free healthchecks.io check (1-hour period, a few hours’ grace) emails you when backups fail or stop, or a disk passes 90%.

Every agent in the box is you: dev, with sudo, your logins and every project. For work you trust less (a stranger’s repo, a scraper, someone else’s project), make an isolated agent, a “cell”: its own Linux user and folder, as two more providers in the same T3.

Make one

sudo make cell-share CELL=web DIR=/data/papers        # read-only
sudo make cell-share CELL=web DIR=/data/out RW=1      # read-write
sudo make cell-unshare CELL=web DIR=papers
sudo make cells                                       # cells, their logins, what's shared
cell web import ~/projects/thing                      # inside the box: give it its own copy
cell web                                              # inside the box: a shell as the cell

Optional, baked into the image: set EXTRAS = desktop wine scraping (or some of them) in config.mk, then sudo make rebuild. All three add about 4 GB.

desktop start          # inside the box: prints a link to open
desktop browser        # Chromium on it, for agents (port 9222)
claude mcp add browser -s user -- npx -y @playwright/mcp@latest --cdp-endpoint http://127.0.0.1:9222
desktop stop           # gives the memory back

/opt/agent-box/extras/synthv/setup   # ~10 minutes, ~2.5 GB
synthv                               # starts it on the desktop

Scraping tools EXTRAS=scraping

In /opt/scrape (Python at /opt/scrape/bin/python), command-line tools on PATH: curl_cffi, trafilatura, yt-dlp, Camoufox, Playwright and markitdown.

echo "CAMOFOX_ACCESS_KEY=$(openssl rand -hex 16)" >> ~/.env   # the key, kept for restarts
tmux new -d -s camofox 'set -a; . ~/.env; CAMOFOX_BIND_HOST=127.0.0.1 CAMOFOX_CRASH_REPORT_ENABLED=false npx -y @askjo/camofox-browser'
. ~/.env && claude mcp add camofox -s user -e CAMOFOX_BASE_URL=http://127.0.0.1:9377 \
  -e CAMOFOX_ACCESS_KEY="$CAMOFOX_ACCESS_KEY" -- npx -y @askjo/camofox-browser-mcp

API keys

One command asks for a key without showing it, so it stays out of your shell history and process list:

Anything an agent can use, it can read, and a web page can talk it into leaking it. Use separate keys for the box and each cell, each with a spending limit.

To give or take away SSH access, edit authorized_keys next to the Makefile; no rebuild needed. make help lists everything.

sudo -i
kopia snapshot list --all                        # find a snapshot ID
kopia ls -l <snapshot-id>/home/.claude          # browse it
kopia restore <snapshot-id>/home/some/folder /tmp/restored
kopia mount <snapshot-id> /mnt/kopia &           # or browse it as a folder