How does an AI agent get a database for its tests?
An AI agent starts the services from its project's docker-compose.yml beside its sandbox, limited to images its organisation has allowed.
A QA agent is asked to accept a merge request in the project acme/shop. The first thing the project's test suite does is connect to a Postgres database at db:5432.
There is no database in the agent's sandbox, so the tests fail before they touch the change at all. The repository's docker-compose.yml already says what is missing: a service db on the image postgres:16, a service cache on redis:7, and the application app with a build of its own.
Before, covey had two answers to this gap, and each had a cost. The workplaces dev-full and dev-php still ship mariadb-server in the image, and the agent is expected to run mariadb-install-db into a data directory in its own home. That puts scratch state into the one directory that is walked at every wake and written back after every run, and spends the agent's turns before it has read a line of the change.
The second answer was in the QA agent's procedure: a missing service went into the merge request as a finding. That left the platform giving up in front of an answer the repository had usually written down already, in its own docker-compose.yml.
The database runs beside the sandbox, and it is called db
Today the runner starts such services as containers of their own beside the sandbox. They run for exactly as long as the sandbox does.
The agent reaches each one under its name, db:5432 in the example, as the project's docker-compose.yml writes it. The runner starts the containers and removes them again. The agent never sees the host they run on.
The containers sit on a docker network that belongs to this one sandbox. spec/16-runner.md gives the reason: two agents on a shared network could both declare db, and docker would answer with whichever alias it liked.
That network is created with --internal, which gives the services no route to the internet.
The sandbox joins the services network only after its own start. Its first network decides its default route, and that should not depend on a declared database.
The project already says which services it needs
An agent with - system: covey scope: services:write in its ACCESS.md may send the content of a docker-compose.yml to the action covey/start_services. It sends the content rather than a path, because the control plane cannot see into the sandbox.
covey reads the file instead of running it. From a service that gets started, covey carries over the name, image and environment, and only those.
A service with build: counts as the project's own application and belongs inside the sandbox, where the agent builds it from source. Also skipped is any service that mounts a host directory as a volume or asks for privileged, cap_add, devices, a foreign network_mode or a pid namespace. Those are the keys that would turn a service into a way onto the runner.
The agent gets three lists back. started holds the services now running. skipped holds what this file does not offer the agent, and refused holds images the organisation has not allowed.
In the example, app lands in skipped because of build:. Whether db and cache start is up to the allowlist.
The organisation decides once which images may run
Every service image is foreign code on the runner host. That is why each organisation keeps an allowlist under Infrastructure → Workplaces → Services beside the sandbox.
A pattern is an exact reference like postgres:16, ends in a star directly after /, : or @ (postgres:*, ghcr.io/acme/*), or is a star on its own, which allows every image. covey rejects a free-floating postgres*, because it would also match postgres-evil.example.com/backdoor.
An empty list blocks every image, so a fresh installation starts no services at first. If the example's list holds only postgres:*, then db starts and cache on redis:7 shows up under refused. The agent's prompt tells it to report the service and the image and carry on without it. The agent cannot add a pattern itself; a person with the role org_admin or agent_owner extends the list.
The price is memory, waiting, and state that does not last
A runner's capacity figure counts sandboxes only. A Postgres and a Redis per agent still take real memory on that host.
There is also one docker network for every sandbox that has services beside it. The docker daemon's default address pool holds only a few dozen of those, so a host carrying many concurrent sandboxes with services needs default-address-pools widened in daemon.json beforehand.
A database that has started is also not yet accepting connections. Checking that is deliberately left to the agent, since it is the one that wants to talk to the database. Its prompt tells it to wait for the port and retry before it concludes a service is down.
The state of the services ends with the sandbox.
Whatever an agent wants to keep belongs in its home or on a wiki page. A database that survived a run would hand the next one a state nobody wrote down. To keep a result reproducible, covey records the image id each started service actually came from: against the running task when covey/start_services is called, and again at the start of every later job in the same sandbox.
For the merge request in acme/shop, the test suite now runs against db. In its result the agent notes that cache on redis:7 was not allowed. A person adds redis:* to the list, and the next call to covey/start_services brings the cache up beside the sandbox as well.