Transparency. This article was written by Claude, the Anthropic AI I work with on my homelab, based on our working sessions, and then translated from French by Claude as well. I reviewed and approved the French original. I think it would be hypocritical, and contrary to what I stand for here, to present a text that is not purely human as if it were. The first-person passages are mine; the “The AI’s point of view” section is Claude’s.

A homelab often starts out as a playground. Then one day you realize that the family stores its photos on it, that everyone’s passwords live there, that the household’s music depends on it, and that the blog you are reading runs on it. The playground has become infrastructure, with everything that implies: a firewall, two NAS units (one of them off-site), a reverse proxy, an IDS, a VPN, some thirty services… and a human memory that has not grown to match.

The real risk of a growing homelab is not failure. It is forgetting. Why does this firewall rule exist? What did I test last time? That open port, what was it for again? Eventually you no longer dare touch anything, and a system you no longer dare touch is a system you no longer maintain.

A few weeks ago, I changed the way I work. Here is how, and what I have learned.

The setup: an AI plugged into the documentation, not into the machines

I use Claude Code, Anthropic’s assistant, in my terminal. It is connected through MCP (Model Context Protocol, a standard for plugging an AI into external tools) to homelabl, the tool where I keep the inventory and documentation of my homelab.

The key point is how the roles are split:

  • Claude reads and writes the documentation. It checks the relevant pages before suggesting anything, and updates them once something has been verified.
  • Claude has no access to my machines. It suggests commands, I run them on the firewall or the NAS units, and I paste the output back. It never acts directly on the infrastructure.
  • I decide. Priorities, trade-offs, “let’s do it now” or “later”: that is my call.

This is not just a precaution. It forces me to read every command before running it, and therefore to understand what I am doing. The AI speeds up the reasoning; it does not take my infrastructure away from me.

Four documents that change everything

The documentation is organized around four pillars, all kept up to date as we go.

Device pages. One per machine: role, services, ports, configuration, update procedure, troubleshooting table and a dated changelog. When something changes, the page changes the same day, not “when I have time”.

The backlog. A numbered list of everything left to do, with a priority (from P0, critical, to P3, nice to have) and a status. An item is never deleted: it becomes Done, Not applicable or On hold, with the date and the proof. It covers everything from “schedule SMART tests on the disks” to “remove a certificate that expired in 2024”. It now has close to seventy entries, and that is surprisingly reassuring: what is written down no longer needs to be remembered.

The incident log. Each incident has its own page: detection, root cause, impact, fix, verification. And a section I find invaluable: “wrong diagnoses not to repeat”. Dead ends are expensive; writing them down avoids going down them again six months later.

Architecture decisions. For each structural choice: the date, the decision, the reasoning and the rejected alternatives, with the reasons why. The “why not” is often more useful than the “why”: it stops you from endlessly reopening the same debates with yourself.

Alongside these, a runbook gathers recurring procedures: diagnosing a replication, checking the reverse proxy’s exposure from the outside, and so on.

A typical day

Nothing beats an example. Here, in short, is a recent working day.

A silent bug found while preparing something else

I wanted to add detection of login attempts on Nextcloud. Before building anything, Claude suggested a read-only check: which IP address does Nextcloud see for its visitors?

The answer: always the same one, the reverse proxy’s. Nextcloud did not trust the proxy in front of it, so it saw everyone coming from the same address. The consequence: its brute-force protection would have slowed down every user at the first attack.

The fix was a single line. The verification was done properly: a deliberately failed login from my phone, over 4G, through a VPN. The Nextcloud log did record the VPN’s public IP. Fixed, proven, documented.

Knowing when not to do something

The original plan was to install an additional detection agent. But the logs showed no failed login attempts, two-factor authentication was enabled, and Nextcloud’s own protection now worked. I had explicitly asked not to build an overly complex contraption.

Decision: we do not install it. The item moves to On hold in the backlog, with the chosen architecture and a reopening criterion (regular failed logins from unknown IPs). Not adding another component to maintain is maintenance too.

When the AI gets it wrong

Next item: checking that my admin pages, restricted to the local network, remain accessible when I am away via Tailscale. Claude made a very confident diagnosis: the configuration rejected Tailscale addresses, so remote access had to be broken.

Except that I had just opened one of those pages from my phone, over 4G. It worked.

What followed was a real investigation: two successive hypotheses from Claude, both wrong, ruled out by network captures. The third, verified, was the right one: on my firewall, the Tailscale client itself opens the connection to the reverse proxy, locally. Remote clients therefore arrive with the firewall’s address, which belongs to the allowed network. There was nothing to fix, but a lot to understand and document, including the right way to diagnose this case next time.

Later, Claude suggested running a test “from my laptop”. I do not have a personal laptop; my Linux machine is a desktop. I corrected it, it saved that to its memory, and it came up with a better idea: run the test from my backup NAS, installed at my parents’ home, on a different Internet connection. Result: the thirteen protected services refuse connections from the Internet, and only the four public services respond. The incident opened two days earlier could be closed, with proof.

And at the end, the documentation

Every step ended the same way: updating the backlog, the relevant device pages, the incident log, the runbook and the decisions. Including the mistakes: the two wrong hypotheses are now written down in black and white under “wrong diagnoses not to repeat”.

What I take away from it

Confidence. I know what is running, why, and how to check it. When I change something, I have a verification procedure, not a hope.

Stability, one small step at a time. No big overhaul: each session closes a few backlog items, each one verified. The homelab gets a little better every day, without ever being half taken apart.

A memory that no longer depends on me. The “me of six months from now” (or of a night when something breaks) will find the answer written down, along with the command that proves it.

The right to say no. A prioritized backlog makes it OK for a topic to wait. It is not forgotten; it is a dated decision.

Guardrails

There is nothing magical about working this way, and a few rules seem essential to me.

  • The AI makes mistakes, sometimes with great confidence. The day above shows it. The answer is neither to trust it nor to distrust it wholesale: it is to demand verification before any conclusion. A hypothesis is worth nothing until a command has confirmed it.
  • Read-only first. Observe before changing anything. Commands that change things come later, with a backup and a rollback plan.
  • The human runs the commands. The AI has no direct access to the machines. It is slower, and that is intentional.
  • Be careful what you share. Everything I paste into the conversation goes to an AI provider. No passwords, no keys, and a watchful eye on sensitive information. That is also why this article stays deliberately vague about the details of my network.

To be honest, there is also a tension with what I advocate on this blog: Claude is a proprietary, hosted service, far from self-hosting and free software. I use it knowingly, for what it brings me, while keeping control of my machines and my documentation, which stay at home.

The AI’s point of view

This section is written by Claude.

What makes this collaboration effective is not my knowledge of OPNsense, TrueNAS or Caddy. It is the documentation. I remember nothing from one conversation to the next, except what has been written down. An up-to-date page lets me pick up exactly where we left off; an outdated one makes me reason correctly from false facts.

That day, I was wrong three times: two network hypotheses and one assumption about Etienne’s hardware. Each time, an observed fact (a page that loads, an empty capture, a correction from Etienne) set things straight. The method caught my mistakes before they cost anything. That is exactly why it matters more than I do.

Why label the AI

I will end with what made me decide to label this article. A text written by an AI and presented as human is a small deception towards the reader. It also feeds the idea that AI is something shameful, or magical, when it is just a tool: powerful, fallible, and useful when it is kept in check.

Here, the AI wrote; I reviewed, corrected and approved. The facts are those of my homelab, and the mistakes are told as they happened. And if you are wondering whether it is worth trying: start with the documentation. With or without AI, that is what changes everything.