Teaching AI Agents to Run My Homelab

How I use a Git repository to give AI agents the context, procedures, and operational history they need to manage my homelab, while keeping secrets outside Git.

AI agents now do almost all the work of running my homelab. I built a Git repository for them so each new session has context about the infrastructure and a record of previous interventions.

I want all infrastructure management to pass through that repository. I decide what I want to achieve and which interventions I am willing to authorize; the agents carry out the operational steps on my behalf.

The repository is called infrastructure-management. It contains inventories, configuration files, scripts, runbooks, incident records, and plans. There is no Terraform setup behind my homelab. This is my attempt to bring as much of its management as possible into versioned files, starting with the infrastructure I already have.

Teaching them, in this case, means improving the instructions, procedures, and context they work from. An increasing part of my work is making that material more useful for the next task.

An owner supplies versioned instructions, runbooks, configuration, and history to AI agents, which operate a virtualized homelab and record outcomes. Workloads are grouped as applications, data services, media and files, experiments, and home automation; monitoring observes the infrastructure and secrets remain outside Git.

I grouped workloads by role after a read-only look at Beszel. Names, addresses, exact counts, capacities, and measurements are omitted. The connections and monitoring traces are illustrative; the workflow above the infrastructure describes how I use the repository.

Giving agents somewhere to start

An agent needs more than access to a server. It needs to know which server matters for the task, what runs there, which procedures apply, and whether an earlier intervention left something it should preserve.

I could provide that information in every conversation. But then the quality of an intervention would depend on how much context I remembered to include that day. The next conversation would need the same explanation again.

I wanted a persistent place for that knowledge.

In my repository, AGENTS.md is the entry point. It gives the agent working rules and directs it to the relevant documents. The infrastructure inventory lives separately, as do procedures and incident records. Keeping those apart lets the entry point stay short while the operational knowledge grows.

The structure is fairly ordinary:

AGENTS.md
docs/
  overview/
  inventory/
  operations/
  runbooks/
  plans/
  evidence/
scripts/
configs/
deployment/

The distinctions matter when an agent reads them. An inventory records observed state. A runbook explains how to perform an operation. A plan describes work that may still be pending. Evidence records what was checked. A proposed backup design must not be mistaken for a backup that is already running.

History changes the next intervention

The historical record is one of the reasons I built this.

Knowing the current configuration helps an agent understand what it is looking at. Knowing why that configuration exists helps it avoid undoing a deliberate decision. An incident record can also preserve checks that ruled out an explanation, a workaround that remains in place, or a recovery step that has not yet been completed.

There is a small example in the scripts README. It records where each managed script is installed, how it is scheduled, and what happens if it fails. Some jobs leave errors in a local journal or log without sending a notification. That gap is documented too.

An agent reviewing one of those jobs can see what is supposed to run and where to check its outcome. It also knows that silence from a notification channel does not establish success. The record identifies which failures need to be checked locally.

Those details give the next agent something specific to act on without relying on me to remember them. They also leave the limits of the setup visible, so a future intervention can address them.

This is the kind of knowledge I want to accumulate: details that change how the next operation should be performed.

Bringing the management into code

I think of this as moving toward infrastructure as code, with a practical limit to that description.

Terraform provides a way to define and manage infrastructure resources as code. My repository does not describe the whole homelab in a form that an infrastructure tool can apply. I cannot claim that a fresh checkout is enough to recreate everything.

What I am bringing into Git is the material agents use to manage the environment: configuration sources, executable scripts, procedures, decisions, and operational history. Almost none of the management now happens through me manually carrying out the steps. An agent can still use SSH or run a command on a host; the repository gives that work its context and procedure.

I have written before about Make as executable documentation. The same idea appears here in commands such as make check-docs, make test, and make drift.

The first checks local documentation links and naming rules. The second runs local tests and shell syntax checks. The third compares managed script copies in the repository with their installed counterparts over SSH.

That last distinction is important. A versioned script and the script actually running on a host can differ. The scripts README lists where each managed copy is installed and explicitly says that repository changes are not deployed automatically. The agent still has to install the change deliberately and verify the result.

These checks make parts of the workflow repeatable and give the agent evidence to work with. The documentation still needs to be checked against the systems it describes.

Secrets stay outside Git

Secrets are excluded from the repository.

I keep credentials outside Git while recording the context needed to manage the infrastructure. The runbooks tell an agent which checks to run and what to record. Runtime files containing secrets stay outside that versioned material.

Access and context are separate requirements. An agent needs the appropriate access to perform a task, and it needs instructions that explain what it should do with that access. Keeping secrets outside Git preserves that boundary.

Improving how I help the agents

My aim is to make all infrastructure management pass through this repository. We are already close enough that doing the work manually has become the exception.

That changes what I need to improve. If I have to explain an undocumented dependency during a task, that dependency belongs in the relevant document. If an agent cannot tell whether a procedure applies to a particular host, the scope needs to be clearer. If verification only establishes that a service responds, the record should say so rather than imply that every user interaction was tested.

The repository is where I can make the operational steps easier to understand, check, and repeat across conversations.

A successful intervention should leave an updated record of what changed, what was verified, and what remains open. The next agent should be able to start from that record without needing me to reconstruct the previous conversation.

References

Share

Pass it along

LinkedInFacebookTelegramWhatsAppEmail