basforge

Search titles, text and the “If it doesn’t work” cases.

    RU
    ManualAIAI agents

    Running a server with an AI agent: roles, checks, secrets

    The agent reads configs from git on your computer and prepares commands; a person runs them on the server and sends the output back. The agent needs neither root on the server nor secrets: inventory by paths, checks with masked values.

    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

    1. Inventory is paths and names only: find, docker compose ls, variable names. The agent doesn’t need what’s in .env.
    2. 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).
    3. 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.
    4. Every command comes with an explanation: what it does, what it changes, what output to expect.
    5. “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).
    6. Rollback comes first. A copy of the old file before the edit and the restore command — in the same message.
    7. Dependent steps go in one command: the secret before git pull, git pull before rm (Dependent steps go on one line with &&).
    8. One topic — one commit, and the message says what and why. The history reads like a work log.
    9. 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.
    10. 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.sh updates 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==name instead of REPO=name before git remote add gives is 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.