Fitting out a home dockyard

This is the whole thing, laid out in order. If you have watched an build you something impressive on your laptop and then wondered where it is supposed to live, this is the answer I arrived at. None of it is bought as a product. It is an old laptop, some free software, and a habit of only adding a piece when the lack of it has actually hurt.

Words you might not know have a dotted underline. Hover, tap or tab to them for a plain explanation — no need to already speak the language.

1 · The laptop is the workbench, not the yard

You type on your laptop. The agent works on your laptop. That part is fine.

The distro barely matters. I run on mine; plenty of people use so they never leave Windows; plain is the safe default and nothing here depends on the choice. What you need is a , , , and — I keep both installed and use whichever suits the job.

The trouble starts a few projects in. An agent building a web app will stand up a database, a cache and a dev server, each in its own . Do that across three projects and you have a dozen containers on your laptop fighting over , your fan is loud, and the moment you shut the lid on the train everything you had running stops. The laptop is a great place to work. It is a bad place for things to run.

The laptop is where the drawing happens. It is not where a hull should sit — close it and everything on the slipway goes down with it.

2 · A slip that stays in the water

The fix is one machine that is always on. It does not have to be a “server” — a laptop from about 2015 with a dead battery, lid shut on a shelf, does the job. Let’s call it Marina.

Two settings turn a laptop into a server. Tell to do nothing when the lid closes, and set it to power back on after a blackout. Then install , , and drop your laptop’s public onto it so you can log in without a password.

Now the split is clean. You still work on your laptop — that is where the agent runs, where you read the diffs, where you think. But the run on Marina. You in, bring a project up with one command, and close your laptop. It keeps running. The fan noise, the port clashes and the “oh no I rebooted” all move off the machine you carry around.

You work on the laptop. The hulls sit on the machine that never leaves the water.

3 · The strongroom

Something on Marina will eventually break, or fill up, or get deleted by a command that looked safe. The question that matters is: is there a recent copy of everything, somewhere that is not Marina?

Two halves. The code is easy: every project gets a , so a lost disk means a morning of cloning, not a funeral. The state is the hard half — the with real records in it, the folder of files people uploaded, the of secrets that only ever existed on the running machine. Git does not touch any of that.

So you need a second copy of the state. A if you have one; a spare USB drive that Marina s a nightly dump onto if you do not. It does not need to be clever. It needs to be off the box and recent. I ended up building this into the control layer so every project is held to it — that is a lifeboat for every hull — but a cron job and a cheap drive is a completely respectable start.

Git already carries the code. Everything else lives on one disk until something deliberately copies it off.

4 · The harbourmaster

Two projects fit in your head. Six do not — especially when each was built over weeks of sessions, spread across your laptop and Marina, and half of them have not been touched in a month. Which session finished the auth work? Is this spec still true? What is even running right now?

This is what bosun-x is for. It is a folder of and — one directory per project — holding the spec, the task list, and a note so the next session starts clean instead of re-deriving three months of context. The agent reads and writes those files directly (there is an server so it can do it through tools). Over the top sits a dashboard that reads your state live, shows every project at once, and flags the ones that have drifted below your bar — no , no spec, a stale handoff.

The discipline is the point; the dashboard is just the window onto it. The whole of the chart room is about this piece.

Before: a dozen projects in unknown states across two machines. After: one folder of plain files, one page, and an agent that can read both.

5 · When a hull is seaworthy

Sooner or later one project stops being an experiment. Real people use it. “It goes down when I reboot Marina” turns from a shrug into a problem. It wants its own address, its own , and it should not be sharing a disk with the thing you are still hacking on.

So it graduates. It moves to a — a few dollars a month for a small rented machine with a public IP. The shape does not change: , a in front, the same file. It is just running somewhere that is not your house, on a machine whose whole job is to stay up.

Now you have machines in more than one place. And “just ssh to it” gets complicated: the VPS has a public address, but Marina is behind your home router’s , your laptop moves between networks, and none of them can reliably start a connection to the others.

A project that has earned it lifts off the workshop bench and onto a machine whose only job is to stay up.

6 · Channel markers

The answer is an : a private network laid over the top of the real internet. You enrol each machine once — laptop, Marina, every VPS — and each gets a fixed address on the overlay. After that any machine can reach any other directly and encrypted, wherever they physically sit. ssh prod-1 works from a café.

Two ways to get one. is the no-config option: it runs the introduction service for you, so setup is a login and a client on each machine. is the run-it-yourself option — one tiny “lighthouse” server for introductions, a certificate per machine, direct traffic after that. Both are underneath. I use Nebula because I wanted to own the whole path; Tailscale is what I would tell a friend to start with.

bosun-x rides this network too. It reaches every host over the overlay with a single locked-down that can only list containers and nothing else — a key with one job — so one page shows the whole fleet no matter which city each machine is in.

One private network. Every machine hangs off it with a fixed address; bosun-x reads across it with a key that can only look, never touch.

7 · The whole harbour

Put it together and it is not complicated, just layered. You and the agent work on the laptop. Marina runs the projects and pushes their state to a drive. An joins your laptop, Marina and any rented boxes into one addressable fleet. bosun-x sits across the top as the chart room — every deck visible from one page — and every project has a so no single machine is a single point of failure.

You do not build it in this order on day one. You start with a laptop and an agent. You add the always-on box when the fan noise and the lost work get annoying. You add backups the first time you feel the cold at the thought of a dead drive. You add bosun-x when you lose track. You add the overlay when a project graduates. Every piece earns its place by the pain it removes.

The finished yard, top to bottom: bosun-x sees everything, the overlay carries everything, the machines do the work, and a copy of every project lives somewhere else.

That is the dockyard. Start with the workbench and a sharp agent; add a slip when the lost work starts to sting, a strongroom the first time you feel the cold, a harbourmaster when you lose count. Do that and you are not bailing water any more — you are running a tight ship, and you can put out to sea knowing the harbour will still be standing when you sail back in.

Fair winds.