# Darwin for developers

> Developer portal for Darwin: quickstart, the darwin CLI, the local HTTP and WebSocket API, configuration keys, and an offline sandbox mode.

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

```bash
# 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 network
```

Hacking on Darwin itself? Clone [the repository](https://github.com/KarthikSubramanian07/Darwin) 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. `--task` picks a task id: a built-in such as `coding_bench` (the default), `legal`, or `support`, or one of your own, `--offline` forces every integration off, `--echo` prints 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/run` with 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/status` returns `{"running": bool, "task": string | null, "events": number}`.
- `WS /ws` streams 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=1` with `FIREWORKS_API_KEY` for LLM mutation and the model race.
- `FEATURE_BRAINTRUST=1` with `BRAINTRUST_API_KEY` to log every evaluation as an experiment.
- `FEATURE_DAYTONA=1` with `DAYTONA_API_KEY` to 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](https://trydarwin.pages.dev/) replays a recorded evolution and [the Lab](https://trydarwin.pages.dev/app) 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 run `darwin --offline` for a deterministic, key-free evolution run; read the fitness curve from stdout.
- Run `darwin-server` to start the local HTTP and WebSocket API on 127.0.0.1:8000, then `POST /api/run` with `{"task": "coding_bench", "offline": true}` and stream events from `WS /ws`.
- Poll `GET /api/status` to see whether a run is active. Run records are written as JSON under `~/.darwin/runs/` (or `data/runs/` in a clone; override with `DARWIN_DATA_DIR`).
- Add your own task as a JSON file under `~/.darwin/task/` (or `data/task/` in a clone) and pass its id with `--task`.

---

Canonical page: https://trydarwin.pages.dev/developers · Site index for agents: https://trydarwin.pages.dev/llms.txt
