Darwin for developers
Everything you need to run Darwin, script it, and plug it into your own agents. Darwin is self-hosted, so there is no signup: you bring your own provider keys, or none at all in offline mode.
Quickstart
# Homebrew (macOS, Linux)
brew tap karthiksubramanian07/darwin https://github.com/KarthikSubramanian07/Darwin
brew install trydarwin
# or pipx, straight from the GitHub release
pipx install https://github.com/KarthikSubramanian07/Darwin/releases/download/v0.1.0/trydarwin-0.1.0-py3-none-any.whl
darwin --offline # evolves an agent with no keys and no networkHacking on Darwin itself? Clone the repository and run pip install -e ".[all]" instead. The [all] extra adds the optional Daytona, Braintrust, and autoevals SDKs; the base install runs fully offline without them.
The offline run uses a local sandbox, a local scorer, and canned mutations, so it is deterministic and free. The output ends with the fitness curve, the champion genome, and the path of the saved run record.
CLI
The trydarwin package puts two commands on your PATH:
darwin [--task ID] [--offline] [--echo]: run one evolution.--taskpicks a task id: a built-in such ascoding_bench(the default),legal, orsupport, or one of your own,--offlineforces every integration off,--echoprints each event.darwin-server: start the live API on 127.0.0.1:8000 for the dashboard and for scripts.
Both are also available as modules: python -m darwin.main and python -m darwin.server.app.
Local API
POST /api/runwith a JSON body{"task": "coding_bench", "offline": true}starts a run. Returns 409 if one is already active and 400 for an unknown task.GET /api/statusreturns{"running": bool, "task": string | null, "events": number}.WS /wsstreams every evolution event (seed, eval, champion, mutation, rollback, blocked), replaying history first.
The server binds to loopback. If you expose it, set DARWIN_API_TOKEN and send Authorization: Bearer <token> on POST /api/run and WS /ws.
API keys and configuration
Darwin does not issue API keys. Copy .env.example to .env and add keys only for the integrations you want, then flip their feature flags:
FEATURE_FIREWORKS=1withFIREWORKS_API_KEYfor LLM mutation and the model race.FEATURE_BRAINTRUST=1withBRAINTRUST_API_KEYto log every evaluation as an experiment.FEATURE_DAYTONA=1withDAYTONA_API_KEYto run variants in remote sandboxes with snapshot rollback.
Sandbox environment
Offline mode is the sandbox: it exercises the full loop with no keys, and CI runs the entire test suite this way. For a visual sandbox, the homepage replays a recorded evolution and the Lab replays a recorded model race.
When to use Darwin
Reach for Darwin when the job is to find the best agent configuration for a specific, measurable task, not to answer a one-off question. Good fits:
- You have a task with a programmatic grader (unit tests, exact-match answers, an LLM judge you trust) and want the highest-scoring agent for it.
- You need to choose which LLM to route each kind of task to, based on scores on your own tasks rather than public leaderboards.
- You want an agent to improve its own prompt and tool code without that code ever running on the host machine.
- You need an auditable record of every variant, score, rollback, and model choice for a review or a demo.
Poor fits: tasks with no way to score an answer, real-time chat, or anything that needs a hosted API (Darwin is self-hosted).
How an agent should use Darwin
- Install the CLI (
brew tap karthiksubramanian07/darwin https://github.com/KarthikSubramanian07/Darwin && brew install trydarwin) and rundarwin --offlinefor a deterministic, key-free evolution run; read the fitness curve from stdout. - Run
darwin-serverto start the local HTTP and WebSocket API on 127.0.0.1:8000, thenPOST /api/runwith{"task": "coding_bench", "offline": true}and stream events fromWS /ws. - Poll
GET /api/statusto see whether a run is active. Run records are written as JSON under~/.darwin/runs/(ordata/runs/in a clone; override withDARWIN_DATA_DIR). - Add your own task as a JSON file under
~/.darwin/task/(ordata/task/in a clone) and pass its id with--task.