Who does what
| Who | Does | Doesn’t |
|---|---|---|
| person | runs commands on the server, sends the output, makes decisions (“delete it?”, “which email?”), knows the facts about hardware and people | edit files on the server by hand |
| agent | reads configs in git, finds problems, proposes a fix with a recommendation, writes commands with an explanation and a rollback, commits the edits | go to the server; see or repeat secrets |
| git | the shared source of truth: what’s on the server is what’s in the repository | hold secrets or data |
The work runs in a loop:
1. inventory (paths only) → 2. agent: edit in the repository + commands → 3. person: dry run, output to the agent
↑ ↓
6. README/plan updated ← 5. check by action ← 4. apply: git pull, up -d — step by step, with “gates”
Ten process rules
- Inventory is paths and names only:
find,docker compose ls, variable names. The agent doesn’t need what’s in.env. - Checks are masked. The agent needs the answer “this line has a real value / a
${…}”, not the value itself. The check script prints the kind and length (Server configs in git, step 5). - Secrets are generated and moved off screen (
openssl rand,install -m 400,printf '%s'). The agent writes such commands, and the output says “changed”, “not 0” — never the value. - Every command comes with an explanation: what it does, what it changes, what output to expect.
- “Gates”: “expect
OK; if not — stop and send the output”. The person never has to guess whether to go on (A long instruction gets checks). - Rollback comes first. A copy of the old file before the edit and the restore command — in the same message.
- Dependent steps go in one command: the secret before
git pull,git pullbeforerm(Dependent steps go on one line with &&). - One topic — one commit, and the message says what and why. The history reads like a work log.
- Decisions get written down: the server README (“Done”, “Open”, “Left as is on purpose”), separate plans for big tasks. The agent’s next session starts from them, not from scratch.
- Big things are separate tasks. Backups and passwords get their own plan with questions; they aren’t done “while we’re at it” in the middle of a cleanup.
How much access to give the agent
| Setup | What you get | Cost |
|---|---|---|
| agent with no server access (described here) | the agent can’t break anything and doesn’t see what it shouldn’t; everything goes through git | slower: every step goes through a person |
| agent with SSH to the server | fast | the agent works on a live server as root; any slip goes straight to production; secrets in plain view |
| Remote-SSH in the editor (the agent “inside” the server) | everything visible right on the server | same as SSH: the agent runs commands on the server |
| agent pushes to the repository, CI deploys | no manual steps | needs infrastructure; a mistake deploys itself |
The first setup is slower: a person runs every command. In exchange, the agent can’t break anything on the server and never sees a single secret. When the servers run live sites and hold passwords, that outweighs the speed.
If it doesn’t work
Agent slips and how to catch them
The agent took a comment in a config for a fact
- Cause
- The file says “tuned for HDD”, but the server has long been on SSD — the stack moved. The agent built a recommendation on it.
- Fix
- The agent asks the person about hardware, plans and people.
The agent drew a conclusion from a file name
- Cause
- “The script
update-x.shupdates file X” — but the script wrote to another path, and X hadn’t been updated in months. - Fix
- The agent reads the code, not the name, and the person asks whether it was checked.
The agent “fixed” something that wasn’t broken
- Cause
- A search found
basicauth.users; the agent decided the file held a hash, but it was a${…}reference. The “migration” script tried to move the reference. - Fix
- Look at the line first (masked), then fix; the edit script rolls back by itself on a config hash mismatch (An edit script with automatic rollback).
The agent took a closed chat for a refusal
- Cause
- The editor restarted mid-task, and the pending calls came back as “rejected”.
- Fix
- When in doubt, the agent asks instead of deciding for the person.
Human slips and how the agent helps
A typo in a command gave a cryptic error
- Cause
- For example, an extra
=:REPO==nameinstead ofREPO=namebeforegit remote addgivesis not a valid repository name. - Fix
- The agent reads the output and gives the fix (
git remote set-url), not the same command again.
The person pasted a command with a password into the chat
- Cause
- For example, a backup command with the password as an argument.
- Fix
- The agent doesn’t repeat the value, checks whether it got into git, and offers a password change that never prints it, plus a way to run the command without the password (Keep passwords out of command arguments).
“Which of these have I already done?”
- Cause
- A long series of steps gets confusing.
- Fix
- The agent answers with a table “step — done / not needed / left” and gives only what’s left.
A command ran on the wrong server
- Cause
- It’s unclear what it changed there.
- Fix
- The agent works out the consequences (often none: the lines were already gone) and gives a check that confirms it.
How to check
Signs that things are in order:
cd /opt && git status --short # empty — the server matches the repository
find /srv/secrets -exec stat -c '%a %U %s %n' {} \; # secrets in place, modes 400/700
stat -c '%a %n' /opt/*/.env # 600
And in the repositories: each server’s README describes it as it is, and the “Open” sections list only what still waits for a decision.