An AI agent on your own server: what it can do, and what it should never be allowed to

An agent that reads your code, runs the tests and proposes changes is a fine colleague. It is also a program with a shell. Here is how we give it the first without the second getting out of hand.

Why your own server

A coding agent needs three things: the code, a way to run it, and somewhere to keep its work. You can rent all three from a cloud service, and for many teams that is the right choice. On your own server, though, the arrangement is easier to see:

• your code and your test data stay where they already are;
• the agent works under rules you can read in a file, not in someone else's settings page;
• everything it does leaves a trace: files on disk, commits in Git, lines in a log.

The server does not need to be large. Most of the heavy thinking happens at the model provider; the server runs the tools, the tests and Git. A small virtual machine with a few gigabytes of memory is plenty for one project.

What it does well

• Reading. It goes through a large, unfamiliar codebase and explains what it found faster than a person can open the files. For a system with no documentation, that alone is worth the setup.
• The boring parts. Tests, database migrations, the fifth form that looks like the other four, the translation file with three hundred keys.
• Patience. It runs the tests, reads the error, changes one line and tries again, as often as it takes, at three in the morning, without sighing.
• First drafts. A refactoring plan, a list of risks, a summary of what changed between two versions.

What it must never do

The rules below are not about the agent being malicious. They are about it being confident and occasionally wrong, which is a dangerous combination near anything live.

• Hold production secrets. No live database passwords, no payment keys, no customer data. Give it a test copy and an anonymised dump.
• Push to the main branch, deploy or send anything to a customer. Its work ends at a branch and a pull request.
• Work as root, or as the user that runs your live site. It gets a user of its own and no sudo.
• Decide what is done. A person writes the task and a person accepts the result.

The agent proposes. A person reads the change, runs it and decides.

The setup

Nothing exotic: a separate user, a project folder, Git as the safety net.

# a user of its own, with no sudo
sudo useradd --create-home --shell /bin/bash agent

# the project, as a clone the agent may change
sudo -u agent git clone git@github.com:you/project.git ~agent/project

# every task on its own branch
git switch -c agent/fix-invoice-rounding

On the repository host, protect the main branch: changes reach it only through a pull request with an approving review. Give the agent's key or token the right to push branches and open pull requests, and nothing more. If it cannot merge, a bad afternoon stays on a branch.

A rules file it reads first

Most coding agents read a file in the repository before they start: what the project is, how to run the tests, which folders not to touch, how to name branches. Keep it short enough that a person reads it too. A good one fits on a screen:

# Project rules
- PHP 8.5, no Composer. Tests: `php tools/run-tests.php`.
- Never edit `config/live.php` or anything in `uploads/`.
- One task, one branch, one pull request. Explain the change in plain English.

Tests that run with one command

An agent is only as good as the feedback it gets. If checking the work takes a person half an hour of clicking, the agent will guess. If it takes one command, it will check, every time.

A normal day

1. A person writes the task: what exists, what should change, how we will know it works. (We have a whole guide on that: How to write a task a developer cannot misunderstand.)
2. The agent works on its branch, runs the tests and fixes what they find.
3. It opens a pull request with a summary in plain language: what changed, why, and what it was not sure about.
4. A person reads the diff, tries it on the test server and merges it, or sends it back with a comment.

The last step is the one that matters. Reviewing a change you did not write is a skill; it is also the reason the setup is safe.

What it costs, honestly

The model provider charges for use, so a busy week costs more than a quiet one. The server costs what a small server costs. The real expense is the review: a person has to read every change. That is not overhead to be optimised away. It is the job.

Checklist

• A separate user with no sudo and no production secrets.
• Test data only: a copy, or an anonymised dump.
• Every task on a branch; merging only by a person, enforced by the repository host.
• Tests that run with one command.
• A short rules file in the repository, read by the agent and by people.
• A person who writes the task and accepts the result.

We work this way on our own projects every day. If you would like the same on your server, send us a request.