Letting an agent touch the machine

01In summary

Four machines, run by an AI agent under a written method, over 347 days and 160 commits. The part that surprises people: three of the four exist so that AI development agents have somewhere to work. The agent looks after its own habitat.

The fourth is the ordinary case — an application's production, staging and test environments. So the set covers both halves of the job: the estate the agents live on, and a real system that has users.

Now the number that tells you what this work actually is. 234 of the 326 documents are issue records. Three quarters of everything written down is an account of something going wrong. That is not a failure rate. That is what operations looks like when you write it down honestly, and any method that produces tidier paperwork is describing a different job.

Underneath: 119,790 lines of documentation, 94 scripts, 391 deployment files. Written by one person, who last worked as a system administrator twenty years ago — and who had never touched one of these four platforms at all.

02What is claimed, and what is not

Recall belongs to the agent. Judgement belongs to the operator. Discipline belongs to the method.

Three clauses, and the middle one is the one everybody drops. So let us be blunt about the version of this that is simply false:

What is actually true is narrower, and more useful. The kind of expertise you need changes shape. It moves out of memory and into judgement. You no longer have to carry the syntax, the flag names and where the config files live — an agent has all of that, all the time, and never gets tired. What you do have to carry is the bit that decides whether to run the thing at all: what does this touch, what breaks if it is wrong, can I undo it, and is the claim in front of me something someone measured or something that merely sounds right?

Anyone who has administered a system will believe that version, because it matches what they already know. The dangerous part was never the typing.

There is one target here that pushes the claim further than the twenty-years story does. One of the four runs a platform the operator had never worked on. No recall to fade, none to restore. It still worked — because "back up first", "check you can get there" and "say whether you measured it" are not platform knowledge. They are the same rules everywhere. Section 13 has the catch that comes with that.

03Why operations is not development

Everything else follows from one difference, so it goes first.

In a repository, somebody already built you a safety net. Version control keeps the previous state whether you thought about it or not. On a machine there is no such gift: the state before your change exists only because someone arranged for it, beforehand, deliberately.

Which is why the first principle in the guide the agent must read — and it is the one principle written into all four of them — has nothing to do with capability. It says: back up before changing; verify prerequisites; validate results; never skip a safety step because it is slow. That last clause does the real work. Nobody skips a safety step because they think it is wrong. They skip it because it is slow.

04Four machines, and what they are for

One application of a method is an anecdote. Four, at four different levels of the stack, starts to look like a pattern.

Look at the labels on the right and the shape of the thing changes. This is not four unrelated boxes. Three of them are the estate the AI development work runs on, and one is a real application with real users. The agent is not only operating machines. It is maintaining the place where its colleagues work.

The bare-metal one deserves a sentence of its own, because it is the one with teeth. A development machine and a storage container sit on the same hardware. The development side is there to be experimented on. The storage side holds data that has to survive. Same box. That is not an abstract "existing data must be preserved" — it is a machine you want to be reckless with and careful about at the same time.

The fourth is described by what it is made of, not what it is: Node and React services with an identity platform, a headless CMS, a database, a cache and monitoring, in containers, across production, staging and test. That is deliberate — and honestly it is the better description anyway, because if you run something similar you can see yourself in it. A product name would have told you nothing.

The build host has no scripts at all. That is informative rather than embarrassing: almost everything there was a one-off configuration decision, not something worth automating. A pattern that insisted the scripts folder be full would have produced ceremony, not value.

05The same shape every time

Seven fixed documents and seven fixed directories, in all four repositories. Checked by measurement, not by memory.

Two things stop this being mere filing. First, the execution guide is written to the agent, not to a person, and it opens with what the agent has to check about itself before doing anything. Second, the structure is identical across machines that share almost no technology — so a session that has worked on one of them already knows where to look in the others.

That is the real payoff with an agent: orientation drops to almost nothing. And orientation is where a session spends most of its first effort.

06A machine's state as data

An agent remembers nothing about a machine between sessions. So the machine's state has to live somewhere as data — otherwise every session starts by guessing, and guessing is exactly what you do not want happening before something irreversible.

Two properties make it worth trusting rather than merely present.

Every value has a date on it. Machines drift. A value established six months ago is a claim about the past wearing present tense. Undated state is worse than none, because people believe it.

Values say whether they were measured. The file distinguishes, in its own text, between what somebody observed on the machine and what was assumed from documentation. Which is the next section, and the single most portable idea here.

07Measured, or reasoned?

Straight from the guide the agent has to read first. Worth saying exactly where this one comes from: it is written into the most recent of the four guides, not all of them. The method sharpened as it went, and this is the sharpest thing it arrived at.

State plainly which of your claims are measured and which are reasoned. They are not interchangeable, and the difference matters most when the next step is irreversible.

Agents are fluent. Fluency is the problem: a reasonable guess and a direct observation come out sounding exactly alike. Same confidence, same phrasing, no hedge in either. When you are writing code that costs you a failing test. Before a partitioning command it costs rather more.

So the distinction is not left to good intentions. It is pushed into the artefacts. The state file marks measured values as measured. The guide makes the agent say which is which. The effect is that you can read a proposal and see, without asking, which parts rest on something someone actually looked at.

08Step zero: check you can actually get there

Before any task, the agent checks that it can really reach the machine it thinks it is administering. A documented address is not evidence.

Like the previous principle, this one is written into the newest guide rather than all four — it was added after the failure below, which is how most good rules arrive.

It sounds like bureaucracy right up to the moment you see what it catches. An agent's runtime is not fixed. It might be in a container, in a virtualised subsystem, on a different host than last week. The network it sees is not necessarily the network the documentation describes — and from the inside it has no way to notice.

What turns that from a war story into a rule is the generalisation: an agent should establish where it is before acting on a description of the world. The documentation was not wrong. The agent just was not where the documentation assumed — and nothing in the documentation could have told it so.

09Two executors, one handover

Two executors, with the border written down: a human at the physical machine, an agent over SSH.

Some things do not delegate, and no amount of capability changes that. Putting an installer on a USB stick. Watching a boot screen. Confirming a monitor really shows a login prompt. Being there to pull the power. The method says so out loud instead of pretending otherwise — which matters, because an unstated border is where a plan quietly assumes somebody will be available.

The interesting bit is not the split, it is the handover: verified, not assumed. The human's part ends with something the agent can check for itself, and the agent's part begins by checking it. A handover where one side simply reports success to the other is not a handover. It is a hope with a timestamp.

It also answers the question people actually want to ask — what happens when it breaks at three in the morning? Someone still has to be able to stand in front of the machine. Better to know that in advance than to discover it during the incident.

10What the work actually produced

Three quarters of the documentation is issues. Not procedures, not a polished reference library — the record of things going sideways, and of decisions that had to be frozen in writing before anything irreversible happened.

That proportion is worth sitting with, because it contradicts how this work is usually presented. Running machines with an agent does not produce a neat shelf of procedures. It produces a large pile of incidents, questions and decisions-with-reasons. The procedures are the sediment left behind after all that settles.

It also explains why the documents read the way they do. They are for an agent that was not there when any of it happened. An issue recording only what was done is useless to it. An issue recording what was expected, what actually happened, and what was concluded is what lets the next session avoid repeating it.

11The estate that feeds itself

Three of the four machines exist so agents can work on them. Which means a fair share of the operational problems are caused by the agents themselves.

This is less ominous than it sounds, and more interesting. Development work consumes disk. It starts containers. It takes ports. It leaves state lying around. Do that continuously, on machines that also have to stay up, and you have a system that generates its own incidents.

The routing failure in section 8 is exactly this species. A development tool's container bridge grabbed a subnet that overlapped the physical network and swallowed the traffic. Nobody attacked anything. The estate tripped over its own feet.

Today the loop is closed by hand. An agent causes the problem, a human notices, a human tells the operating agent, the operating agent fixes it. The human is a message bus — and a message bus that has to sleep.

The obvious next step is to take the human out of that middle position. Let the development agent raise the problem directly with the operating agent, which already has a written role, procedures, a state file and a record of what has gone wrong before. Most of what that needs already exists. What is missing is a channel and an authority boundary.

Which gives the boundary, and it is not a new one. It is the same line the method already draws between its two executors — only now it is the development agent, rather than a person, at the front of the chain.

Put plainly: the escalation can be automated. The decision to do something unrecoverable should not be. That is not caution for its own sake — it is the same sentence from section 7, applied one link further up the chain.

12The time axis

347 days from the first commit to the most recent, with commits on 62 distinct days — 160 commits across the four repositories.

There is no velocity figure anywhere in this document, on purpose. These are four applications of a pattern, started whenever a machine actually needed something. Dividing commits by days would produce something that looks like a rate and means nothing — and in a document whose whole argument is about telling measured from inferred, that would cost more than it gave.

The shape is honestly lumpy, too. Operations is not a project with a burn-down chart. A machine sits untouched for four months and then demands a week, and the record shows exactly that.

13What this does not give you

The useful half of this and the dangerous half sit right next to each other, so they need pulling apart.

It does not remove the need for someone who knows when to be suspicious. The method encodes discipline — back up first, check your access, mark what you measured. It cannot supply the instinct that notices a confident proposal is wrong. Here that instinct came from having administered systems twenty years ago. The recall was gone; the judgement was not. If you have neither, you are not in the same position, and should not read this as though you were.

And on an unfamiliar platform, that gap gets wider. One of these four runs a platform the operator had never touched. The method still worked, because the safety rules are not platform knowledge. But there is a catch worth naming: on a platform you do not know, you can still judge the risk — what this touches, whether it can be undone — and you cannot sanity-check the specifics at all. The backup, the step-zero check and the measured mark are not extra ceremony there. They are the only thing standing in for the knowledge you do not have.

It does not make irreversible actions safe. It makes them prepared. Different word, and the difference is the backup you took before you needed it.

It is not a productivity claim. Nothing here says this beats a practised administrator doing it by hand. It says it is possible, repeatable and written down — which are different properties, and more useful ones when nobody has done the job for two decades.

And it is dated. This runs from late 2025 into 2026. What the tooling of that period allowed is not what will be possible later, and an account like this ages in months. The measurement date is on every page for that reason.

14What transfers, what it costs, where it stops

What to copy

Three things, in order of value. The state file — one document per machine saying what it actually is, with a date on every value and a mark on the ones somebody measured. The fixed structure — the same documents and directories for every machine, so a session stops wasting its first effort on orientation. Step zero — the agent works out where it is before acting on anyone's description of the world.

The two sentences worth stealing outright

Never skip a safety step because it is slow. And: state plainly which of your claims are measured and which are reasoned. Both are cheap to adopt, and neither depends on a single thing described here.

What it costs

Writing. 119,790 lines of it, most of which is things going wrong. If that sounds like too much, the honest reply is that the alternative is all of it living in one person's head — which is exactly what makes a system unmaintainable, and a situation an agent cannot work in at all.

Where it stops

At the point where somebody has to be standing next to the machine. And at the judgement about whether to run the command — which is still yours, and is the part worth keeping sharp.