roost

A home for your remote coding agents.
Built for herdr.

install · connect · set up · docs

roost is one Docker container for your NAS, homelab or VM. Claude Code, Codex, opencode and friends live in it, and you drive them from herdr. Close the laptop, and the agents keep working. Open herdr on another machine or your phone, and you are back in the same sessions.

• A normal container: one compose file, one port, your public key. No scripts to run on the docker host.
• Plain SSH in: pubkey-only, one user (agent). Works with ssh, herdr, VS Code Remote, SFTP, Termius, Heeler.
• Agents ready on first start: harnesses, herdr, gh/glab, headless Chromium + Playwright MCP, all via mise.
• Contained: no sudo, no Docker socket. Agents cannot add logins.
• Persistent: logins, repos and tools live in one volume and survive updates.

Install

On the docker host, in an empty folder:

curl -fsSLO https://raw.githubusercontent.com/aronjanosch/roost/main/compose.yml
cat > .env <<'EOF'
PUBLIC_KEYS="ssh-ed25519 AAAA... laptop,ssh-ed25519 AAAA... phone"
GIT_USER_NAME="Ada Lovelace"
GIT_USER_EMAIL="ada@example.com"
EOF
docker compose up -d
docker logs -f roost      # first start installs tools; wait for "roost bootstrap done"

Only PUBLIC_KEYS is required. Everything else (port, paths, uid, harnesses, extra packages) is in .env.example. Change a value, then docker compose up -d again. On Unraid, use uid/gid 99:100 and paths under /mnt/user/appdata.

Connect

# ~/.ssh/config: pick any alias
Host roost
  HostName <docker-host>
  Port 2222
  User agent

ssh roost                              # shell in the box
herdr machine add roost --label roost  # sessions show up next to your local ones

From your phone: any SSH app works (Termius, Heeler, …). Same host, port 2222, user agent, the app's key in PUBLIC_KEYS. Run herdr to attach. Your phone needs to reach the host: same LAN, or a VPN such as Tailscale.

Set up inside

Start an agent in the box and ask it to set up roost. The built-in roost-setup skill walks you through what is still missing: git identity, gh login, agent logins, cloning your repos into ~/projects, tools your projects need, and how to connect more devices.

Already logged in on your laptop? Copy those logins across instead (never private keys):

git clone https://github.com/aronjanosch/roost
roost/bin/roost-migrate roost        # your ssh alias for the box; asks per group

Update

docker compose pull && docker compose up -d   # logins, repos and tools stay

Running agent sessions stop during the recreate.

Docs

• reference: migrate, ~/projects and trust, herdr versions, host notes, security model
• tools · harnesses
• maintainers: image build, file layout
• roost-setup skill: the guided setup agents run in the box

Security

The box runs agents in bypass mode, so treat it as one trust zone. Don't expose port 2222 to the internet. See SECURITY.md.

License

MIT