An objective-driven system for discovering web workflows, researching complex questions, and building reusable tools for agents.
Darwin starts with what you want to achieve, not a script describing how to get there. It can search for a better browser strategy, investigate a question across sources, and preserve the evidence behind its results. Workflows that survive compilation and live certification become callable skills that other agents can use without repeating the original search.
The system combines structured planning, browser execution, evolutionary search, source-grounded analysis, and a persistent skill library. Different strategies can coexist: the fastest workflow need not be the cheapest, and a cautious approach need not be discarded because another route scores better overall.
Darwin is built in Go, runs against local Chrome or Solari cloud browsers, and provides a dashboard, a CLI, an HTTP skill API, and an MCP server. It is designed for developers who need both inspectable answers and repeatable web capabilities.
Overview | How it works · Quick start | Configuration · Architecture | Verification
Give Darwin a measurable objective and a readable source:
Find the cheapest book rated at least four stars with at least three copies in stock.
Find the cheapest game under $40 with at least 85% positive reviews, 10,000 reviews, and a release date after 2023.
Darwin discovers and evaluates different ways to navigate, filter, enumerate, inspect, and verify candidates. It returns an archive of successful strategies with their outcomes and execution characteristics, while selecting one for compilation.
These examples describe listing objectives: one item, a numeric goal, and constraints on that item's attributes. A particular website must expose the required data and permit automated access. The game example is not a certified integration with a named game store.
Built-in task classes cover books, remote jobs, and flights. Scout can also create a data-defined blueprint for a new listing site without changing Go code. Bookstore has the most extensive recorded demonstrations; a class or blueprint still needs validation against the site it targets.
For a question involving multiple purchases, sources, or conditions, Darwin constructs a research plan rather than reducing the request to one price:
Find me the cheapest legitimate way to attend a major tech event in London from Lagos, for 5 days, without spending more than GBP 1,500 total. Include the event ticket, flight, accommodation, transport, and mandatory fees. Prefer refundable options and official/verified sources. If the budget is impossible, find the cheapest viable alternative and explain why.
The output is an evidence report: researched components, candidate options, itemized costs, requirement checks, tradeoffs, source receipts, and unresolved questions. It distinguishes a complete verified total from a partial subtotal and an above-budget alternative from an option that fails the requirements.
For event trips, the plan covers admission, return travel, accommodation, airport/local transport, entry fees, and necessary living costs. Earlier findings guide later research, such as discovering event dates before looking for compatible travel. Unknown passport status and travel dates remain questions, not invented facts.
Research reads public pages and follows discovered links. General booking-form interaction is not implemented, so a request can remain incomplete when applicable fares, rooms, fees, or eligibility cannot be established. An incomplete search is not proof that the budget is impossible.
A selected evolutionary workflow can become a deterministic Playwright script with typed inputs, assertions, and selector fallbacks. Once certified against the live site, it can run as a local skill, an HTTP endpoint, or an MCP tool. A Solari sandbox can host the HTTP service on a public URL.
Certified skills can also be registered as standing objectives. Darwin reruns them on a schedule, records changes and failures, and can evolve a repair population when explicitly configured to do so.
These tool and scheduling capabilities apply to compiled evolutionary workflows. Multi-source research reports are a separate output; they do not currently compile into skills or enter the archive, predictor, or standing-objective pipeline.
The dashboard's planner separates single-listing optimization from multi-source research. It preserves hard constraints, preferences, assumptions, and any personal facts that require clarification.
For listing tasks, Scout examines page structure, measures candidate selectors, and validates the fields needed for scoring. The resulting blueprint contains the site bindings, objective, constraints, and access policy. Supplying a relevant URL is more reliable than asking the model to discover a starting page.
For research, the planner builds a dependency-ordered set of components and requirements. A domain-specific event-trip planner supplies the cost ledger and compatibility checks for travel objectives.
An evolutionary individual is structured data: tactics, their arguments, behavioral traits, an execution tier, and lineage. The browser interpreter executes that strategy and records what actually happened. Fitness combines the objective outcome with time, actions, estimated cost, and repeatability, subject to legitimacy checks.
The generation loop evaluates individuals, retains elites, breeds children, mutates strategies, and can stop weak attempts at a mid-run checkpoint. Models help propose valid combinations of observed strategies; structural fallbacks allow breeding to continue when model calls fail.
Selection preserves diversity through a MAP-Elites archive. Individuals compete inside behavior cells, and parents can be sampled across occupied niches. The default map uses wall-clock speed, action count, and source-seeding approach; cost, tier, and risk are additional configurable axes. Coverage and aggregate archive fitness track discoveries that a single best-score curve would miss.
For broader exploration, the population can be split into independently seeded islands with different fitness weightings, local archives, and adaptive mutation. Elites migrate between islands periodically. The default is one population; up to six weighting profiles are available, with at least six individuals needed per island. A source-family or risk label describes behavior, not proof of legitimacy.
Evolution normally runs against a frozen capture so trials see comparable data. Live comparisons and certification are separate checks: reproducibility on a captured site does not establish that a workflow still works on today's web.
Research processes components in dependency order, collecting direct-source text, links, timestamps, and screenshots where available. Search results locate leads; they do not certify claims.
A model proposes options and a separate model call reviews their applicability. Go checks source quotations, required cost coverage, currencies, constraints, and arithmetic. Model-supplied totals are not accepted as calculated results. Unknown fees stay unknown, headline prices are not complete quotes, and currency conversion needs supporting evidence.
The report distinguishes verified, incomplete, rejected, and above-budget outcomes. A run with no candidate options shows No verified results, with findings and failure details still accessible. Verification is against the retrieved evidence and implemented checks, not a guarantee of global optimality or bookability.
The skill library preserves champion records, trait priors, discovered vocabulary, and reusable compiled artifacts. Later populations can inherit class-specific knowledge or begin a repair from a previous champion.
Vocabulary growth produces executable macros rather than descriptive labels.
During a stall, the model can propose a schema-validated tactic. Separately,
darwin mine finds tactic sequences enriched among high-fitness individuals
across recorded runs; explicit admission preserves their observed arguments in
the class vocabulary for future searches.
Recorded runs also provide labeled data for darwin predict. It trains a
classifier for whether a genome will produce an answer and a regressor for fitness
conditional on success. Evaluation holds out entire runs, excludes halved
attempts, and reports AUC, rank correlation, and single-feature diagnostics.
Prediction is currently an offline evaluation capability, not an active filter in the generation loop. Mining admission is explicit, not automatic after every run. Neither mechanism establishes general transfer across unrelated tasks.
Compilation removes the model from execution of the selected workflow and emits a Playwright script plus a typed manifest, assertions, and selector fallbacks. Live certification gates access through the callable skill library.
HTTP and MCP share the executor. HTTP calls have bearer authentication, rate and concurrency limits, deadlines, and entry-host restrictions. MCP uses stdio; publishing an HTTP endpoint does not create an HTTP MCP transport. Public deployment is an explicit operation using a Solari sandbox.
A standing objective monitors a certified skill against its live reference. Changed values, failed assertions, and execution errors are recorded as distinct states. Selector fallback use surfaces drift even when a check still succeeds. Opt-in repair waits for repeated failures, seeds from the previous champion, and respects a six-hour cooldown. Scheduling needs a running process, and neither repair success nor an external notification service is assumed.
The dashboard keeps discovery and its evidence inspectable:
- The menu: an archive of the best strategies in different behavior niches.
- How it searched: lineage, node inspection, generation playback, and session replay when available.
- Progress and round-by-round views: fitness, diversity, execution behavior, and generation records.
- What changed and rule breaks: genome differences and disqualification details.
- Saved shortcuts: the compiled skill library.
- Results: research options, itemized costs, questions, requirement checks, source receipts, and failure details.
Research reports open automatically on completion and can be restored after a refresh. Answering follow-up questions or choosing retry starts another research run and can incur additional costs.
Requirements:
- Go compatible with the version declared in go.mod, currently 1.26.5.
- Local Chrome/Chromium, or a Solari account for cloud browser execution.
- A configured model key for planning, scouting, and model-driven research.
- Node.js and Playwright only when running emitted JavaScript independently.
From the repository root in PowerShell:
go build -o darwin.exe ./cmd/darwin
if (-not (Test-Path .env)) { Copy-Item .env.example .env }
# Configure your keys in .env before continuing.
.\darwin.exe doctor
.\darwin.exe serveOpen the local dashboard and choose New search.
The prompt is routed to listing evolution or research. Research reports open
Results automatically and can be restored after refresh. If port 8420 is
occupied, use serve -addr 127.0.0.1:8421.
On Linux/macOS, build with go build -o darwin ./cmd/darwin and use ./darwin.
Commands below use darwin as shorthand; use your platform's executable path.
The dashboard assets are embedded, so UI changes require rebuilding and
restarting the server.
darwin analyze -plan-only -objective "Compare the complete cost of two conference trips"
darwin analyze -objective "Find a complete five-day trip from Lagos to a major tech event in London under GBP 1500. Prefer refundable options." -pages 30 -out artifacts/trip-plan-only still calls the model but does not open a browser. -url supplies an
optional source. -answers accepts a JSON object mapping question text to answers.
-pages allows 1-40 page/search attempts. The CLI prints JSON and writes
report.json plus available screenshots to the output directory.
A successful process exit or a job's done phase means processing finished,
not that an option passed verification. Check the report's status,
options, and warnings. Zero options are displayed as No verified results.
darwin evolve -class bookstore -pop 24 -islands 4 -gens 6 -concurrency 4 -live
darwin scout -url https://books.toscrape.com/ -objective "Find the cheapest book rated at least four stars"
darwin evolve -blueprint <blueprint-id> -dims speed,effort,approach
darwin predict -class bookstore -v
darwin mine -class bookstoreAfter inspecting the mining results, darwin mine -class bookstore -admit
promotes a qualifying tactic into that class's vocabulary.
Evolution defaults to a frozen capture for comparable trials and compilation of
the selected champion. -live adds a live champion/baseline comparison.
-frozen=false trains directly against the live site. -repair seeds from the
previous champion.
For a built-in class, -objective changes the text seen by the operator, not the
scorer. Use -param key=value to change scoring constraints, or use Scout to
create a blueprint for a new listing objective.
darwin skill -list
darwin skill -certify <skill-id>
darwin serve -api -addr 127.0.0.1:8422 -token new
darwin mcp
darwin deploy -skill <skill-id> -keep
darwin standing -add <skill-id> -every 6h -auto-repair
darwin standing -watchThese are separate commands/processes, not a single shell script. HTTP discovery
is GET /v1/skills; invocation is POST /v1/skills/<id>/call with JSON input
and the configured bearer token. serve -api serves the API instead of the UI.
serve -standing can run the scheduler alongside the dashboard or API.
Deployment needs SOLARI_API_KEY. -keep leaves the sandbox running after the
command exits; its lifetime is still limited by sandbox policy. Scheduling
requires a running process. Neither deployment nor monitoring is free hosting.
darwin doctor checks configuration and runtime readiness. doctor -deep adds
an end-to-end genome check; darwin bench measures runtime behavior before a
larger population is launched. Deep checks and benchmarks perform real work and
can use paid services. Every subcommand exposes its options through -h.
Start with .env.example. Existing process environment variables
take precedence over the root .env file.
| Variable | Purpose |
|---|---|
LLM_BASE_URL, LLM_API_KEY, LLM_MODEL |
Model endpoint, credentials, and model ID |
LLM_FALLBACK_MODEL |
Fallback model; available quotas and capabilities depend on the provider |
LLM_API_KEY_2 through LLM_API_KEY_5 |
Optional additional configured keys |
DARWIN_RUNTIME |
local by default; solari selects cloud browsers when a key is present |
SOLARI_API_KEY, SOLARI_BASE_URL |
Cloud sessions and sandbox deployment |
BRAVE_SEARCH_API_KEY |
Indexed discovery for multi-source research |
DARWIN_SEARCH_USD_PER_CALL |
Search-call cost estimate, default USD 0.01 |
DARWIN_MAX_USD |
Estimated run spend ceiling, default USD 5 |
DARWIN_MAX_SESSIONS, DARWIN_MAX_LLM_CALLS |
Evolution/session and model-call limits; defaults 400 and 300 |
DARWIN_DATA_DIR |
Storage root, default ./data |
DARWIN_TRUST_PROXY |
Trust forwarded addresses only behind a proxy that controls them |
Without a search key, research tries model-proposed direct URLs and verifies them by reading the pages. This is narrower and less reliable than indexed search. Missing evidence stays missing. Local Chrome needs no Solari key but provides no Solari session recording.
Cost figures are estimates, not provider invoices or guaranteed per-result prices. Research compacts large source contexts before inference; this reduces oversized requests but cannot eliminate provider quotas, outages, or all token limits. Do not commit keys, bearer tokens, or private session URLs.
The Go backend uses chromedp to drive browsers over CDP. Local execution uses
Chrome/Chromium; Solari provides cloud browser sessions, session recordings, and
sandbox hosting for deployed skill services. Emitted standalone workflows use
Playwright. The dashboard is embedded in the Go binary.
| Module | Responsibility |
|---|---|
internal/reasoning |
Intent planning, dependency-ordered research, citations, option review, cost validation |
internal/scout, internal/blueprint |
Readable-page discovery, measured bindings, data-defined listing tasks |
internal/orchestrator, internal/archive |
Population execution, islands, migration, niche preservation |
internal/genome, internal/recombine, internal/vocab |
Structured strategies, breeding, mutation, executable macros |
internal/predict, internal/mine |
Offline prediction and evidence-based tactic promotion |
internal/exec, internal/frozen, internal/fitness |
CDP execution, captured environments, scoring and legitimacy gates |
internal/compiler, internal/skills |
Deterministic artifacts, certification, priors, and vocabulary persistence |
internal/endpoint, internal/standing |
HTTP/MCP calls and scheduled checks/repair |
internal/dashboard, internal/store |
Results, archive map, lineage, charts, run records, and receipts |
Evolution records live under data/runs; compiled skills and learned vocabulary
under data/skills; standing checks under data/standing. Dashboard research
reports live at data/analyses/<job-id>/job.json. Open a saved research report
with /?analysis=<job-id> or retrieve it through GET /api/jobs/<job-id>.
Research receipts include source text, exact quoted evidence, timestamps, screenshots when capture succeeds, and a session recording link when available. Search snippets are leads, not proof. Quotes must match retrieved direct sources. Unknown fees are not zero, headline prices are not complete totals, and currency conversions need evidence. Model review of dates, eligibility, and applicability can still be wrong; deterministic arithmetic does not establish those meanings.
- Read-only, logged-out discovery: no purchases, bookings, account creation, or human-facing submissions.
- Robots directives and access restrictions are respected. A blocked source is not permission to bypass its controls.
- Listing blueprints are site-scoped. Research may combine public sources but does not yet compile the combined workflow.
- Desktop tier traits and cost pressure exist, but execution still uses the browser interpreter rather than a general vision-driven desktop executor.
- Frozen repeatability is not proof of live-site stability. Certification and scheduled checks are separate steps.
- A verified result is verified against the retrieved evidence and implemented checks, not guaranteed globally optimal, currently bookable, or legally sufficient.
- Keep the dashboard local unless you provide appropriate deployment protection; its run controls can trigger paid work.
A fresh full-suite run on 8 September 2026 passed 181 top-level tests across
22 tested packages, with zero failures and three skips. Build and
go vet ./... also passed. Coverage includes real Chrome dashboard interaction,
desktop/mobile report rendering, result restoration, empty-result handling,
evidence evaluation, archives, islands, compilation, endpoints, and scheduling.
The separate live Lagos-to-London test attempted 15 pages, saved five source records, and produced zero verified options. That integration test did not pass; complex trip research is implemented but is not validated end to end. Skips, environment constraints, and the live outcome are documented in the verification report, with machine-readable results.
Earlier evolutionary demonstrations and performance measurements are preserved in the project history. They are historical observations, not current performance guarantees.
go test ./... -short
go test ./... -count=1
go vet ./...
go build ./cmd/darwinThe full suite includes Chrome and network-dependent checks; inspect skips rather than counting them as passes. Some live tests require keys in the process environment because Go runs package tests from their package directories.
Further reading: research contracts, verification report, Solari runtime notes, historical experiments.