AI coding agents often start each task on a fresh cloud machine. That machine needs the right runtimes, services and packages before the agent can build or test anything. When it isn’t ready, the agent guesses, skips the tests it can’t run, or hands back code nobody tested. And every agent platform wants its setup in its own file and format, so a team using three agents writes the same setup three times. The copies drift and fail quietly.
Preconfiguration prepares the machine before the agent starts. You describe what the project needs once, in a short preconfig.yaml. The preconfig tool compiles it into the setup file each platform reads, checks those files against each platform’s format, and runs the setup on a clean machine with the project’s own tests. When a setup fails, Preconfig Doctor reads the log, names the cause and, when the cause is in the spec, writes the fix.
The Pitch in Four Numbers
- About 1 minute, 49.6 to 73.0 seconds, from a clean Ubuntu 24.04 machine to passing tests with PostgreSQL and Redis running.
- 32 of 32 bugs planted in the core on purpose were caught by its tests.
- 14 of 14 caught by Doctor’s tests.
- 20 of 20 Doctor fixes, rerun on a clean machine, removed every failure.
How It Works
The spec covers runtimes, packages, services, environment variables, setup commands and a ready check. Four commands do the work. preconfig build compiles the spec into each platform’s file. preconfig check reads the setup files a repository already has and reports what each platform would reject or ignore, and what has drifted from the spec. preconfig verify runs the setup and the ready check on a clean machine and names the step that failed. preconfig doctor reads a failed log and fixes the spec when it can. Doctor uses no AI model and no service, so logs stay local, and when no rule fits it says so and changes nothing.
The engine writes for nine destinations: GitHub Copilot’s cloud agent, Cursor’s cloud agents, the dev container standard behind Codespaces and VS Code, Ona, Devin, Claude Code cloud sessions, OpenAI Codex, fresh virtual machines through cloud-init, and a plain shell script for anything else. It writes plain files and stops. Nothing runs while the agent works.
Secrets are listed by name only, and a spec is refused if a secret-looking variable has its value written in it. Facts about each platform that change often live in one dated place in the engine, so keeping up with a platform change means one edit. It’s one binary with no daemon, no account and nothing beyond Go’s standard library.
The case studies tell the story. One service’s hand-written agent setup had fifteen errors, none flagged when they were written. A clean machine was ready in 49.6 seconds, with a missing Redis caught at the ready step. Upgrading PostgreSQL from 16 to 17 took one line, and every platform’s files followed.
Who It’s For
- Teams running AI coding agents on one or several platforms.
- Platform engineers who want every repository’s agent setup checked on each pull request.
- Anyone tired of agents returning untested code because the machine wasn’t ready.
Limits
The project calls itself early. The engine works, but real agents doing real work on every platform is the next step, and so far only Claude Code has run preconfig’s setup on its own platform. The demo repositories are samples written for it. The engine has run only on Linux x86-64, verify needs Docker and network access, and generated setups target Ubuntu 24.04. And it isn’t a replacement for AGENTS.md or rules files, which govern how an agent behaves. Preconfiguration governs the machine.
The Four-Question Screening
Every project featured here gets the same four questions, the way you’d screen a startup idea.
1. Where is the money in it?
The core, the engine, format, tests and binaries, is free under Apache 2.0. The roadmap is unusually clear about the paid part: a team layer, described as the parts companies would pay for. That’s a view of every repository’s agent setup, drift alerts, failure diagnosis, install rules for agent machines, hosted checks and prebuilt machines that start faster. Companies rolling out coding agents across many repositories have exactly that problem, and the bill for agent time that’s wasted on broken machines is easy to measure.
2. What real problem does it solve?
Agents working on machines that aren’t ready. That shows up as skipped tests, guessed installs and untested code, and it’s worse with several agents because each needs its own setup file. Preconfiguration makes one spec the source of truth and proves it works on a clean machine.
3. The technology in plain words
Think of a hotel that gets a list of what a guest needs, a desk, a kettle and a quiet room, and sets the room up before they arrive. Different hotel chains want the list on different forms, so Preconfiguration fills in every chain’s form from one list, then checks a room actually works by staying in it first.
4. Moat and differentiation
Each platform has its own setup format and docs, and teams write them by hand. Preconfiguration is the layer above them all, with one spec, nine outputs, verification on a clean machine and a doctor that fixes the spec. The moat that can grow is the dated knowledge of every platform’s quirks, which takes constant work to keep current, plus the team layer that turns it into something companies pay for.
Why It Matters
Coding agents are only as good as the machine they work on. A ready machine means real tests and real answers. Making that the default, across every platform a team uses, is a quiet multiplier on everything the agents do.
Follow the Project
Read the introduction and how it works, try the live demo and the Doctor demo, see the roadmap, or get the code from the Preconfiguration repository on GitHub. Preconfiguration is listed with the other open-source projects on SoftDevStudio.com, and more featured projects are in the Projects section.