If you’d rather see it than read about it, this page is for you. In about ten minutes you can watch Evolve run a whole change on your own machine, then watch it catch a bad one. Here’s how.
What you need
Linux, Go 1.27 or newer (the programming language Evolve is written in), Git and bubblewrap. That last one is a small sandboxing tool, which runs programs sealed off from the rest of your machine; your Linux distribution packages it as bubblewrap. Evolve keeps its records in a single SQLite file (a database that lives in one file), so there’s no database to install.
You don’t need an AI key, the code an AI service gives you to use it. Normally a coding agent (an AI tool that writes code) makes each attempt at a goal. In the demo, a script stands in for the agent, and it says so.
1. Start it
Type these into a terminal. The first downloads Evolve with Git; the second uses make, a standard build tool, to start it.
git clone https://gitlab.com/earnest-ventures/evolve.git && cd evolve
make up
This starts Evolve’s server and its web interface, its worker (the part that does the jobs), and a small pretend “production” (the live version customers would use) with pretend customers. When it’s done, it prints a link to sign in to the web interface.
Something missing? bin/evolve doctor (bin/evolve is Evolve’s command, just built) checks everything Evolve needs and tells you how to fix what isn’t there.
2. Run a change
make demo
This hands Evolve the checkout goal from A change run, start to finish and follows it live: three attempts, the checks (the tests Evolve runs on each), the decision, the canary (the winner tried on 10% and then 50% of the pretend customers), and the promotion, when it goes live for everyone. It takes a few minutes. Open the web interface while it runs and you can watch the run (everything Evolve does for this goal) draw its family tree as it goes.
3. Make one go wrong
make demo-regression
This one sends in a change with the hidden coupon bug from When it goes wrong. Watch it pass every check, fail on the canary, and roll back by itself, which means the old version is put back.
4. Ask the record some questions
Evolve writes down everything it does, in its record. The first line below lets the evolve command reach the server; the rest ask questions. A digest is the fingerprint of a built version, shown by evolve status.
source .evolve/env
bin/evolve status # what's running, and what should be
bin/evolve run show <run-id> # attempts, evidence, decision, rollout
bin/evolve why <digest> # why is this version here?
bin/evolve confidence # can Evolve be trusted to ship by itself?
After the bad change, the demo agent is supervised: its next change waits for your approval before it goes live. You can approve it on the run’s page in the web interface, or with bin/evolve run approve <run-id>. That’s earned autonomy doing its job.
Stop and clean up
make down stops everything. make purge also deletes the database and Evolve’s data.
Next
Your first project: evolve init in your own code, then a real agent.