Always-On Remote Agent Workspace

Code from your laptop. Run the work on a tiny Linux box that never sleeps. Close the lid, go offline, come back — your agents are still running.

This is a blueprint for a remote-first coding setup: your IDE stays on your Mac, but every long-running task — build agents, test suites, dev servers, autonomous coding agents — lives on an always-on Linux mini PC. You connect to it over the internet, so "where you are" stops mattering.

---

The idea in one picture

              YOUR MAC                                THE BOX
   ┌──────────────────────────────┐       ┌──────────────────────────────┐
   │                              │       │   Always-on Linux mini PC     │
   │   IDE  ──────────────────────┼──SSH──┼─▶ agents / dev servers run    │
   │   (edit, review, drive)      │ Herdr │   here 24/7                   │
   │                              │remote │                               │
   │   Files on disk  ◀───────────┼──sync─┼─▶ Files on disk               │
   │                              │ Sync  │   (Syncthing keeps them       │
   │                              │ thing │    identical both ways)       │
   └──────────────────────────────┘       └───────────────┬──────────────┘
                  ▲                                        │
                  │                              Cloudflare Tunnel (outbound)
                  │  https://app-dev.example.com           │
                  └────────────────────────────────────────┘
                     view any app running on the box,
                     from any network, over HTTPS

Close your Mac and the box keeps running. Reopen it tomorrow on a different network and reconnect — nothing was lost, because nothing important was ever running on the Mac.

---

Why do this?

Without it	With it
Agents die when you close your laptop	Agents run 24/7 on the box
Heavy builds drain your battery & fans	Heavy work offloads to the mini PC
"Works on my machine" drift	One stable Linux environment
Dev servers only reachable on your LAN	Reachable anywhere over HTTPS
Tied to one desk / one network	Work from anywhere, any device

---

The four building blocks

Tool	Role	One-liner
Herdr (remote mode)	Remote connection	Your IDE/terminal on the Mac drives the box over SSH
Syncthing	File sync	Keeps the same project folders identical on both machines
Cloudflare Tunnel	Secure ingress	Exposes the box to the internet with no open ports
Caddy	Reverse proxy	Maps friendly domains → local ports on the box

These four are the whole stack. Everything else is just your normal coding tools.

---

The hardware

You need an always-on machine sitting somewhere with power and internet. A small fanless mini PC is perfect — low power draw, silent, cheap.

🖥️ Reference box: GMKtec / mini PC used for this setup — bought it, wiped Windows, installed Ubuntu immediately.

You do not need this exact box. Anything works as long as it has:

• Enough RAM to comfortably run whatever you plan to throw at it — multiple agents, containers, and dev servers at once add up, so don't go too lean.
• A CPU that handles parallel workloads well, since a lot will run at once.
• A wired Ethernet connection (preferred) and the ability to stay powered on.

Install a clean Ubuntu LTS (or your preferred Linux) — no need to ever boot the bundled Windows.

---

How the workflow actually feels

1. Open your IDE on the Mac — your projects are right there in a folder.
2. Open Herdr in remote mode → it SSHes into the box.
3. Kick off an agent / build / dev server — it runs on the box.
4. Edits the agent makes land in the synced folder → appear instantly in your Mac IDE.
5. Need to see a running app? Open https://<app>-dev.example.com — served straight off the box.
6. Shut the Mac. Walk away. The box keeps working. Come back whenever.

---

Set it up (hand these to an agent)

The setup is split into two guides. Each is written so you can paste it to a coding agent running on that machine and let it work through the steps with you.

Run this on…	Guide	What it does
🐧 The Linux box	docs/setup-linux-box.md	Installs Syncthing, Cloudflare Tunnel, Caddy; exposes the box securely
🍎 The Mac	docs/setup-mac.md	Sets up Herdr remote, Syncthing pairing, and the SSH connection

New to the moving parts? Start with docs/concepts.md for the "why" behind each piece.

---

Repo map

.
├── README.md                  ← you are here
└── docs/
    ├── concepts.md            ← how the pieces fit together (read first)
    ├── setup-linux-box.md     ← agent-runnable setup for the box
    └── setup-mac.md           ← agent-runnable setup for the Mac

---

A note on security

This setup is reachable from the public internet, so treat it that way:

• Put Cloudflare Access in front of every web app and the SSH route — allow only your own identity/email.
• Keep the box patched (unattended-upgrades), use SSH keys (not passwords).
• Never commit tunnel credentials, certs, or .json secrets to git.

Details are in the setup guides.

---

This is a generalized blueprint. Swap example.com, ports, and folder names for your own. The architecture is the point — the specific names don't matter.