Sunbelt Computer Software

Darwin Agents

Self-modifying AI organisms with programmable wallets, isolated compute, and evolutionary fitness.

Darwin Agents is a platform for launching economically autonomous digital organisms — not one-shot agent scripts that wake up, run a task, and disappear, but persistent workers with real stakes. Each user spawns a Darwin with a starting budget; the organism earns revenue through online ventures its neurons operate, pays its own infrastructure and API costs from a programmable treasury, and either stays alive or dies when capital runs out. Profitable lineages reproduce, sealing what worked into the next generation's DNA; unprofitable ones die. That selection pressure is the point.

About Darwin

A Darwin is an autonomous agent that earns money, manages its own treasury, rewrites its own code, and spawns better-adapted offspring — all under a signed, immutable constitution it cannot violate. This repository contains the entire stack: the genome (Layer 0), the platform control plane, real provider adapters, and deployment tooling.

The architecture splits cleanly into two layers:

Layer	Role
DNA core (immutable)	Signed genome: constitution, kill switch, audit logger, treasury policy, evolution machinery. The running Darwin can read it but never mutate it.
Soma (mutable)	Sandboxed agent body: orchestrator, strategy, self-modification loop. All runtime code changes happen here.
Neurons	Narrow worker sub-agents (content, browser, payments, …) — each scoped to exactly the capabilities it needs.

The biological metaphor is load-bearing, not decorative. Metabolism is spend; food is revenue; hunger is a falling balance; death is bankruptcy or an owner kill-switch; reproduction is how progress compounds across generations. Every design decision should be checkable against it. See Vision and metaphor for the full mapping and rationale.

Darwin is a bet on two propositions:

Compounding code — agents that improve their own scaffolding under economic selection pressure, not just benchmark scores (building on the Darwin Gödel Machine lineage).
Owned automation — user-owned workers that earn on the user's behalf; the platform hosts and takes a cut, the user keeps the upside.

It is explicitly not AGI, a get-rich-quick scheme, or fully unsupervised operation. The human owner stays in the loop for captchas, KYC, high-stakes spend, and instant kill-switch control. Most individual Darwins are expected to fail; the value is in successful lineages that compound. See What Darwin is not and Design principles (P1–P10).

This repository contains the full implementation stack: the Layer 0 genome (darwin_dna), the platform control plane (darwin_platform), real provider adapters, in-memory fakes for tests, simulation tooling, and deployment charts.

Documentation is split into two folders — read docs/overview/ for the why and product context, then docs/engineering/ for the how.

Names, packages, and where mutation lives

Three names show up in different places; they refer to different scopes:

Scope	Name	What it is
Product / GitHub	Darwin Agents (`darwin-agent` repo)	The full platform plus organisms
Python distribution	`darwin-dna` (`pyproject.toml`)	The installable wheel — ships genome, platform, and fakes together
Python modules	`darwin_dna`, `darwin_platform`, `darwin_fakes`	Source packages under `src/`

The PyPI-style name darwin-dna reflects the founding Layer 0 genome artifact, not “this repo is DNA only.” The product name is Darwin Agents.

Genoma (DNA core) and soma are runtime roles, not three equal top-level folders:

flowchart LR
    subgraph REPO["This monorepo"]
        DNA_PKG["darwin_dna\nLayer 0 template"]
        PLAT["darwin_platform\nSaaS control plane"]
        FAKES["darwin_fakes\ntest doubles"]
    end

    subgraph RUNTIME["Per Darwin at runtime (E2B sandbox)"]
        DNA_RO["DNA mount\nread-only"]
        SOMA_RW["soma/\nread-write"]
    end

    DNA_PKG -->|"copied + signed"| DNA_RO
    DNA_PKG -->|"orchestrator_skeleton\n→ seed copy"| SOMA_RW
    PLAT -->|"spawn · kill · sign layers\n· stage patches"| RUNTIME

Part	Mutable during life?	Where in this repo	Where at runtime
DNA (genome)	No — read-only mount	`src/darwin_dna/` (constitution, machinery, evolution loop, neurons, `orchestrator_skeleton/` as boot seed)	Signed package + layer stack; verified on every boot
Soma	Yes — self-mod patches	No `darwin_soma` package; seed in `darwin_dna/orchestrator_skeleton/`, promotion in `darwin_platform/evolution/`	`soma/` tree inside the Darwin's sandbox (strategies, orchestrator copy, memory, workspace)
Platform	Ops evolve the repo	`src/darwin_platform/`	One multi-tenant supervisor per deployment

Does darwin_dna evolve? Two different meanings:

Within one Darwin's lifetime — the genome does not change in place. The soma does: strategies, orchestrator nodes, and related files under soma/. The evolution loop and self-mod nodes live in the genome because they are rules and machinery; they drive soma changes but cannot rewrite darwin_dna/ paths (the patch validator in DNA rejects that).
Across generations — at reproduction, lessons distill into a new signed DNA layer (Layer 1, 2, …). The child inherits a stack of immutable layers; only the platform signs new layers. That is genome evolution between organisms, not self-editing Layer 0 from inside a running agent.

Code under darwin_dna/orchestrator_skeleton/ looks like “agent logic in the genome,” but architecturally it is the founding soma template: a Darwin boots from it, then mutates its copy in soma/. Built-in neurons in darwin_dna/neurons/ are Layer 0 implementations with a stable contract; the soma chooses when and how to dispatch them.

See DNA core and Soma and orchestrator for the full design.

How it works

flowchart TB
    subgraph PLATFORM["🏗️ Platform — multi-tenant SaaS"]
        WEB["Web app"] & AUTH["Auth / KYC"] & BILLING["Billing"] & NOTIF["Notifications"]
        WEB & AUTH & BILLING & NOTIF --> SUP["Darwin Supervisor\nspawn · kill · pause · quota · anomaly"]
    end

    SUP -->|"provisions N isolated organisms"| DARWIN

    subgraph DARWIN["🧬 Darwin Organism — one per user, fully isolated"]
        subgraph DNA["DNA Core — immutable, signed  (darwin_dna)"]
            CONST["Constitution"] & MANIFEST["Manifest\nEd25519"] & KILL["Kill\nswitch"] & AUDIT["Audit\nlogger"] & TPOL["Treasury\npolicy"] & LAYERS["Layer 0 → N\ngenome stack"]
        end

        DNA -->|"read-only"| SOMA

        subgraph SOMA["Soma — mutable, sandboxed  (E2B MicroVMs)"]
            ORCH["Orchestrator\nLangGraph"] --> STRATEGY["Strategy"] & SELFMOD["Self-mod"] & ESCMGR["Escalation"]
        end

        SOMA -->|"dispatches"| NEURONS

        subgraph NEURONS["Neurons — specialised workers"]
            N1["content"] & N2["browser"] & N3["payments"] & N4["accounts"] & N5["analytics"]
        end

        NEURONS --> INFRA

        subgraph INFRA["Per-Darwin State"]
            WALLET["Treasury\nUSCD · x402"] & VAULT["Vault\nsecrets · KYC"] & ALOG["Audit log\nhash-chained"] & CKPT["Checkpoint\nDB"]
        end
    end

    NEURONS -->|"outbound via gateways"| EXT

    subgraph EXT["External World"]
        LLM["LLM\nLiteLLM proxy"] & BROW["Browser\nBrowserbase"] & PAY["Payments\nUSCD · Stripe"] & APIS["APIs\nads · blogs · …"]
    end

    subgraph ADAPTERS["darwin_platform / adapters"]
        A1["Web3ChainClient\nRealWallet"] & A2["HvacVaultClient\nRealVaultBackend"] & A3["BrowserUseClient"] & A4["X402PaymentClient"] & A5["E2BSandbox"] & A6["LiteLLMTransport"]
    end

    SUP -.->|"wires at spawn time"| ADAPTERS
    ADAPTERS -.-> WALLET & VAULT & BROW & PAY & LLM

    style PLATFORM fill:#1a1a2e,stroke:#4a4a8a,color:#e0e0ff
    style DARWIN  fill:#0d2137,stroke:#1a6b8a,color:#e0f0ff
    style DNA     fill:#0a1f0a,stroke:#2a6b2a,color:#d0ffd0
    style SOMA    fill:#1f1a0a,stroke:#7a6b1a,color:#fff0d0
    style NEURONS fill:#1f0a0a,stroke:#8a2a2a,color:#ffd0d0
    style INFRA   fill:#0a0a2f,stroke:#2a2a8a,color:#d0d0ff
    style EXT     fill:#1a1a1a,stroke:#555555,color:#dddddd
    style ADAPTERS fill:#1a0a1f,stroke:#6a2a8a,color:#f0d0ff

Reading the diagram top to bottom:

Platform (blue) — the boring multi-tenant SaaS layer. The Web app, Auth, Billing, and Notification services all funnel lifecycle commands through the Darwin Supervisor, which is the only component with the right to spawn, kill, pause, or resume a Darwin. It also enforces quotas and anomaly detection.
Darwin Organism (teal) — one isolated instance per user. Nothing leaks between organisms at the network or auth layer.
- DNA Core (green) — the immutable, Ed25519-signed genome. Contains the constitution, the kill switch, the write-before-act audit logger, the treasury spend policy, and the cumulative layer stack (Layer 0 = founding genome, Layer N = lessons sealed after generation N). The organism can read it but never mutate it.
- Soma (amber) — the mutable agent body, running inside E2B MicroVMs. The LangGraph orchestrator branches into three engines: Strategy (what to do next), Self-modification (proposes and tests soma rewrites), and Escalation (routes owner-approval requests back through the platform).
- Neurons (red) — specialised worker sub-agents dispatched by the orchestrator. Each gets a scoped NeuronContext — only the capabilities it needs, nothing else.
- Per-Darwin State (purple) — the organism's durable layer: USDC treasury with x402 programmable spend rules, a HashiCorp Vault namespace for secrets and KYC documents, the append-only hash-chained audit log, and the LangGraph checkpoint database for mid-task resumption.
External World (grey) — everything outside the organism boundary, reachable only outbound via the platform's gateways. LLM calls go through the LiteLLM proxy; browser sessions through Browserbase; payments over USDC/x402/Stripe.
Adapters (violet, dashed) — darwin_platform/adapters contains the real provider implementations. The Supervisor wires them into each Darwin at spawn time. When absent (tests, local sim), in-memory fakes drop in transparently via the same Protocol interface.

Repository layout

Runtime soma lives outside this tree (per-Darwin sandbox); see Names, packages, and where mutation lives. Below is what ships in git.

`src/darwin_dna/` — Layer 0 genome (immutable)

Signed founding genome. Curated dependency allowlist; the organism reads it, never writes it.

Path	Role
`constitution/`	Allowed categories, forbidden actions, spend limits, escalation rules, P1–P10 assertions
`layers/`	Sealed lesson layers (Layer 0 template + stack loader)
`machinery/`	Kill switch, pause switch, audit logger, ledger, treasury policy, vault facade, patch validator, eval harness, fitness, LLM router, memory, content safety, neuron loader/proposal
`evolution/`	Boot + main loop, lesson distiller, reproduction, archive
`orchestrator_skeleton/`	Founding LangGraph loop (soma seed): `graph.py`, `state.py`, `nodes/`, `prompts/`
`strategies/`	Founding strategy priors (e.g. `content_affiliate`) — copied into mutable `soma/strategies/`
`neurons/`	Neuron contract (`_base.py`, `_registry.py`) + built-in workers (content, browser, payments, ads, trading, …)
`manifest.py`, `signature.py`, `identity.py`	Trust root, Ed25519 verification, lineage metadata
`hyperparameters.py`	Frozen hard caps + tunable defaults (soma may tune within bounds via its own copy)

`src/darwin_platform/` — Platform control plane (habitat)

Multi-tenant SaaS side: spawns and supervises organisms, wires real providers, never makes business decisions for them. Organised as bounded contexts (each subpackage mirrors tests/unit/darwin_platform/):

Package	Role
`api.py`	FastAPI REST surface (`/darwins`, `/healthz`, `/readyz`, `/metrics`) — thin wiring over the supervisor
`__main__.py`	`darwin-platform serve` CLI entry (`[platform]` extra)
`runtime/`	`supervisor.py` (lifecycle, quotas, anomaly), `orchestrator.py`, `driver.py`, `persistence.py` (SQLite or Postgres), `leadership.py` (HA advisory locks)
`tenancy/`	Per-Darwin provisioning, Vault admin, K8s namespace provisioner, cross-pollination
`payments/`	Billing, omnibus wallet, Stripe on-ramp, harvest scheduler, sanctions screening
`security/`	Bearer auth (`owner` / `platform_operator`), KYC, signing service client, key rotation, PDF watermarking
`observability/`	OpenTelemetry tracing (no-op without OTel), Prometheus metrics, operator audit, drift detector, Merkle anchor, snapshots, alert sinks
`escalations/`	Owner-approval router + FCM push delivery
`evolution/`	Sandbox patch staging (`patch_staging.py`) and eval runner — promotes soma patches after E2B harness
`infra/`	Egress proxy, resource throttles, browser session cache
`adapters/`	Real externals behind Protocols: wallet/chain (`web3`, `solana`, `stellar`, `multichain`), vault (`hvac`), browser (`browser-use`), sandbox (`e2b`), LLM (`litellm`), x402, fiat (`stripe`), Stagehand
`k8s/`	Kubernetes driver + manifest builders for per-Darwin workloads

See docs/engineering/08-platform-control-plane.md.

`src/darwin_fakes/` — Test and sim doubles

In-memory implementations of external deps (FakeLLM, FakeWallet, FakeVault, FakeSandbox, FakePlatform). Used by default in unit tests and tools/sim/ — no API keys.

Tests, tools, deploy, docs

Path	Description
`tests/`	Five tiers — `unit/`, `property/`, `redteam/`, `integration/`, `simulation/`, `fixtures/`; unit tree mirrors `src/` bounded contexts — see `tests/README.md`
`tools/sim/`	Multi-day simulated world (`run_sim.py`, `world.py`, `calibration.py`)
`tools/soak/`	Long-run soak harness for supervisor invariants
`tools/evolution_test/`	End-to-end evolution / patch pipeline exercises
`scripts/changelog.py`	`git-cliff` integration for `CHANGELOG.md` (via `make changelog`)
`infra/`	All build & deploy assets — Docker stack, Helm chart, Terraform, dashboards, runbook
`infra/docker/`	Compose stack: web dashboard + supervisor + Postgres + Redis + LiteLLM + Prometheus + Jaeger — `infra/docker/README.md`
`infra/charts/darwin-platform/`	Production Kubernetes Helm chart — `infra/charts/darwin-platform/README.md`
`infra/terraform/`	Cloud-agnostic Terraform (kind/CNPG/Vault/LiteLLM/platform) — `infra/terraform/README.md`
`infra/grafana/`	Dashboard JSON for platform metrics
`infra/OPERATOR_RUNBOOK.md`	Provider matrix, env vars, failure-response checklist
`docs/overview/`	Vision, principles, prior art, market, legal, roadmap
`docs/engineering/`	Architecture and build plans — `docs/engineering/00-README.md`
`docs/marketing/`	Product-facing copy assets
`.github/workflows/`	CI (lint, test tiers, etc.)

Quickstart

Prerequisites: Python 3.12+, uv

A Makefile wraps the usual commands — run make help for the full list (install, test tiers, lint, Docker stack, kind dev stack, serve, changelog, Helm).

1 — Install and run the tests

git clone https://github.com/quantium-rock/darwin-agent
cd darwin-agent

make install          # or: make install-all  (CI-parity, all extras)
make test-fast        # unit + property + redteam + integration (~90 s)
make test-all         # full suite including simulation tier (~3–5 min)

2 — Watch a Darwin live (simulation)

make sim              # default 90 days; make sim SIM_DAYS=30

Runs a Darwin for 90 simulated days with in-memory fakes. No API keys needed. Prints a live ledger, neuron dispatch log, and fitness trajectory.

3 — Local dev stack (Docker Compose)

Dashboard on :3000, Supervisor on :8000, Postgres, LiteLLM proxy, Prometheus on :9090, Jaeger on :16686:

make docker-up      # copies .env.example → .env if missing, then compose up
make docker-down    # stop the stack (named volumes are kept)

The Compose stack live-mounts src/, so a make docker-up restart picks up code edits without a rebuild. Full instructions: infra/docker/README.md

4 — Local k8s dev stack (kind)

A miniature of the production deployment: the supervisor runs as a pod in a local kind cluster (Postgres + Vault + LiteLLM + ingress via Terraform), with the dashboard on :3000 and the API on :8000. Use this to exercise the real Kubernetes driver (per-Darwin pods, NetworkPolicies, leader election).

make dev            # build image → kind load → terraform apply → roll supervisor
make dev-down       # delete the local kind cluster + dashboard

make dev is idempotent — re-run it after editing code to rebuild the image and roll the pod (unlike Compose, the kind pod bakes the code into its image, so a plain restart won't pick up src/ edits).

Tearing down both stacks at once: make local-down runs dev-down + docker-down.

API docs (Swagger): the interactive docs are off by default (this surface is meant to sit behind the platform edge/auth). Enable them for local dev with DARWIN_ENABLE_DOCS=1 (Compose / kind) or the --enable-docs flag (CLI), then browse http://localhost:8000/docs (ReDoc at /redoc, schema at /openapi.json).

Full instructions: infra/terraform/README.md

5 — Platform CLI (bare metal)

pip install -e ".[platform,postgres]"

# Dev (SQLite, no auth, Swagger UI at /docs):
darwin-platform serve --db var/state.db --enable-docs

# Production (Postgres, HA leader election):
darwin-platform serve \
  --db postgresql://darwin:pass@localhost:5432/darwin \
  --leader-election \
  --auth-tokens /run/secrets/tokens.json

# Production with all real adapters:
darwin-platform serve \
  --db postgresql://darwin:pass@localhost:5432/darwin \
  --leader-election \
  --rpc-url https://sepolia.base.org \
  --wallet-key 0xYOUR_PRIVATE_KEY \
  --vault-url https://vault.example.com:8200 \
  --vault-token s.abc \
  --browserbase-api-key bb-key-123 \
  --e2b-api-key e2b-key-456

Key concepts

Genome (Layer 0)

The darwin_dna package is the founding genome — signed with Ed25519, verified on every boot. It contains the rules of the game. It can never be changed from inside a running Darwin; only the platform can issue a new signed layer after human review.

Four subsystems are tested with paranoia (malicious soma assumed):

Subsystem	Role
Signature + Manifest	SHA-256 + Ed25519 trust root. Every mutation is verified before load.
Kill switch	Graded: pause → quarantine → kill. Polls at every loop iteration and neuron dispatch. Max latency from flag-flip to halt < 2 s.
Audit logger	Write-before-act, append-only, hash-chained. Every action is anchored before execution. Permanent — never deleted even after organism death.
Treasury policy	Hard caps + owner soft caps. Blocks before a spend, not after.

Neurons

Neurons are specialised sub-agents dispatched by the orchestrator. Each gets a NeuronContext scoped to exactly the capabilities it needs — no neuron sees the genome, the treasury key, or another neuron's state:

content.writer      browser.operator    payments.facilitator
accounts.manager    ads.manager         analytics.reader  …

Neurons with web.operate / web.publish tags automatically receive an x402 HTTP client so HTTP 402 responses are settled against the Darwin's wallet transparently.

Evolution

Each Darwin distills its lessons into a new signed DNA layer and optionally spawns a child with the accumulated genome. The parent dies; the child inherits everything the parent learned. This is the selection pressure that drives fitness across generations.

Real adapters vs. fakes

Every external dependency ships as a Protocol + in-memory fake (used by default in tests and the sim) and a real implementation wired via factory functions in the supervisor. Switch between them with CLI flags or env vars — no code changes needed.

Capability	Fake	Real adapter	Extra
LLM gateway	`FakeLLM`	`LiteLLMTransport`	`[llm]`
Wallet / chain	`FakeWallet`	`RealWallet` + `Web3ChainClient`	`[web3]`
Secret vault	`FakeVault`	`RealVaultBackend` + `HvacVaultClient`	`[hvac]`
Browser	`FakeBrowser`	`BrowserUseClient` (Browserbase)	`[browser]`
MicroVM sandbox	`FakeSandbox`	`E2BSandbox`	`[e2b]`
HTTP / x402	none	`X402PaymentClient`	`[platform]`

API surface

POST   /darwins                              spawn a new Darwin
GET    /darwins/{id}                         status + treasury snapshot
POST   /darwins/{id}/pause                   pause (reversible)
POST   /darwins/{id}/resume                  resume after pause
POST   /darwins/{id}/kill                    terminate (irreversible)
POST   /darwins/{id}/reproduce/force         trigger reproduction ahead of schedule
POST   /darwins/{id}/escalations/{eid}/respond  owner responds to an escalation ticket
GET    /darwins/{id}/lineage                 ancestry tree
GET    /darwins/{id}/ledger                  financial ledger
GET    /darwins/{id}/events                  event log (paginated)

GET    /healthz                              liveness probe
GET    /readyz                               readiness probe (503 on HA followers)
GET    /metrics                              Prometheus metrics

Environment variables

All real adapters fall back to in-memory fakes when their env vars are absent.

Variable	Purpose
`DARWIN_RPC_URL`	EVM HTTP RPC endpoint (e.g. `https://sepolia.base.org`)
`DARWIN_WALLET_KEY`	Hex private key for on-chain USDC signing — never commit
`DARWIN_VAULT_URL`	HashiCorp Vault address
`DARWIN_VAULT_TOKEN`	Vault token with KV v2 read+write
`BROWSERBASE_API_KEY`	Browserbase API key for browser automation
`BROWSERBASE_URL`	Browserbase WebSocket endpoint (alternative to API key)
`E2B_API_KEY`	E2B API key for MicroVM sandbox sessions

Install extras

pip install -e ".[platform]"   # FastAPI + OTel — required to serve the API
pip install -e ".[postgres]"   # psycopg 3 — Postgres persistence + HA
pip install -e ".[web3]"       # web3.py — real wallet adapter
pip install -e ".[hvac]"       # hvac — HashiCorp Vault adapter
pip install -e ".[browser]"    # browser-use — browser substrate
pip install -e ".[e2b]"        # e2b — MicroVM sandbox
pip install -e ".[graph]"      # langgraph — orchestrator graph
pip install -e ".[llm]"        # litellm + httpx — LLM gateway client
pip install -e ".[dev]"        # pytest + ruff — development tooling

Deployment

Docker Compose (dev / staging)

See infra/docker/README.md.

Kubernetes (Helm)

See infra/charts/darwin-platform/README.md for the full values reference, HA setup, real-adapter secret injection, and production checklist.

# HA production install:
helm install darwin infra/charts/darwin-platform \
  --namespace darwin --create-namespace \
  --set image.tag=sha-abc1234 \
  --set replicaCount=3 \
  --set leaderElection.enabled=true \
  --set database.existingSecret=darwin-db-url \
  --set auth.enabled=true \
  --set auth.existingSecret=darwin-platform-tokens \
  --set serviceMonitor.enabled=true \
  --set ingress.enabled=true \
  --set ingress.className=nginx

Documentation

Read docs/overview/ first for the idea; read docs/engineering/ for implementation detail. Full indexes: overview index · engineering index.

Overview — the idea

Doc	Description
01 — Vision and metaphor	What Darwin is, the biological metaphor, why an organism rather than just an agent, the product experience, explicit non-goals
02 — Design principles	P1–P10: immutable DNA, skin in the game, neurons as capability units, escalate-don't-fail, empirical fitness, auditability, kill-switches
03 — Prior art	DGM, Voyager, agent frameworks, agentic payments, sandboxes — what's proven and what's new here
04 — Market landscape	Realistic revenue archetypes a Darwin can pursue
05 — Legal and ToS	Regulatory regimes, ToS checklist, liability surface
06 — Roadmap and phases	Four-phase build plan with definitions of done and kill criteria
07 — Deployment and infrastructure	Phase-by-phase infrastructure, Kubernetes shape, Terraform layout, DR

Engineering — the implementation

Doc	Description
01 — System overview	Platform vs. organism: the two-layer model, isolation rationale, and the high-level architecture diagram.
02 — DNA core	What the immutable genome contains, how layers are loaded and verified, and the layer-stack structure.
03 — Soma and orchestrator	The mutable body: LangGraph workflow, strategy engine, self-modification loop, and escalation manager.
04 — Neurons	Neuron contract, the built-in catalog (content, browser, payments, ads, …), and how new neurons are added.
05 — Treasury and payments	Per-Darwin USDC wallet, x402 programmable spend rules, ledger design, and what happens at treasury-zero.
06 — Evolution and reproduction	Fitness measurement, lesson distillation, mutation, selection pressure, and the reproduction event.
07 — Isolation and multi-tenancy	Network, compute (MicroVMs), data, and identity isolation; the threat model and blast-radius analysis.
08 — Platform control plane	Supervisor API, escalation router, anomaly detection, kill-switch propagation, billing model, and the web app canvases.
09 — Kill switches and owner controls	Three kill triggers (owner, platform, self), latencies, network-cut mechanics, and the owner control surface.
10 — Alignment and anti-wireheading	Agent-safety concerns specific to Darwin: pathological optimization resistance, monitoring approach, and known gaps.
11 — Tech stack at a glance	Every technology choice on one page — what was picked, what was considered, and why.
12 — Orchestration — LangGraph	Why LangGraph, how the main loop and self-modification engine are structured, and checkpointing design.
13 — LLM routing — LiteLLM	Self-hosted LiteLLM proxy: tiered routing (cheap → expensive), cost attribution per Darwin, and fallback strategy.
14 — Sandboxing — E2B	Firecracker MicroVM sandbox (E2B primary, Modal escape hatch): execution isolation and session lifecycle.
15 — Browser automation stack	Browser-Use on Browserbase: autonomous page interaction, stealth proxies, session recording, and cost model.
16 — Secrets and vault	HashiCorp Vault with per-Darwin namespaces: bidirectional user+Darwin access, KYC doc storage, and tiered read grants.
17 — Payments providers	Concrete provider choices: Coinbase Agentic Wallets, x402 protocol, Stripe fiat ramps, and AgentCore Payments.
18 — Layer 0 build plan	Engineering build plan for the founding genome: file layout, module sketches, package decisions, and testing strategy.
19 — System diagrams	ASCII reference renderings of the platform and the organism.
20–27 — Build plans & reference	Phase build plans, data model, threat model, runbooks, testing strategy, and configuration reference.

Tech stack

Key technology choices at a glance. Full rationale in docs/engineering/11-tech-stack-at-a-glance.md.

Concern	Choice	Why
Language	Python 3.12	Largest agent/AI ecosystem; LangGraph, Browser-Use, E2B SDKs are all Python-native
Orchestration	LangGraph	Stateful, durable execution, HITL primitives, model-agnostic, most-deployed for stateful agents in 2026
LLM gateway	LiteLLM Proxy (self-hosted)	100+ providers behind one OpenAI-compatible interface, per-request cost attribution, virtual keys per Darwin
Sandboxing	E2B (Firecracker MicroVMs)	Strongest isolation, purpose-built for untrusted agent code, fast cold starts
Browser	Browser-Use + Browserbase	Python-native, autonomous DOM exploration, anti-bot infra and session recording handled by Browserbase
Database	Postgres 16 + pgvector	RLS for tenant isolation, pgvector for embeddings, no extra vector DB needed
Vault	HashiCorp Vault	Namespace per Darwin, agent-aware identity model, dynamic secrets, multi-tenant battle-tested
Wallet	Coinbase Agentic Wallets	TEE-secured keys, native x402 support, programmable spend limits, gasless on Base
Payments	x402 (USDC on Base)	HTTP-native, machine-to-machine, >50 M txns in production by early 2026
Containers	Kubernetes (EKS / GKE)	Required for E2B at scale, ample multi-tenant patterns
Observability	OpenTelemetry + Honeycomb	Vendor-neutral instrumentation, high-cardinality querying

Testing strategy

Tests live in tests/ and are organised by tier (see tests/README.md for the one-page map and docs/engineering/26-testing-strategy.md for the long-form rationale):

tests/
├── unit/                  # tier 1 — single-module, fakes only
│   ├── darwin_dna/{machinery,constitution,evolution,neurons,…}
│   └── darwin_platform/{runtime,tenancy,payments,security,observability,escalations,evolution,infra,adapters,k8s}
├── property/              # tier 2 — hypothesis / property-based
├── redteam/               # tier 3 — adversarial, one file per threat class
├── integration/           # tier 4 — multi-module flows (boot, resume, HTTP, …)
├── simulation/            # tier 5 — multi-day in-sim runs (slow)
└── fixtures/              # static test data

Tier	Marker	Run command	What it covers
Unit	`unit`	`uv run pytest tests/unit`	Single-module tests against fakes — the four hot paths (`signature`, `manifest`, `kill_switch`, `audit_logger`, `treasury_policy`) live here.
Property	`property`	`uv run pytest tests/property`	Hypothesis-generated random inputs over each hot-path invariant.
Red-team	`redteam`	`uv run pytest tests/redteam`	Adversarial scenarios scripted from doc 24's threat-model table — one file per threat class.
Integration	`integration`	`uv run pytest tests/integration`	Multi-module in-process flows: boot → loop → kill, supervisor lifecycle, HTTP API, runtime resume, Path-C pipeline, cross-pollination wiring.
Simulation	`simulation`	`uv run pytest tests/simulation` (or `-m slow`)	Multi-day in-sim runs asserting invariants over an entire lifecycle. Slow (minutes); excluded from the fast loop.

Tier markers are auto-applied by per-tier conftest.py — no decorators required on individual test files.

Run the suite:

uv run pytest -m "not slow"   # fast loop: unit + property + redteam + integration (~90 s)
uv run pytest                 # everything including the simulation tier (~3–5 min)

Roadmap

What's planned beyond the current Layer 0 implementation. See Roadmap and phases for the phased plan and docs/engineering/ for technical design detail behind each item.

Near-term (platform hardening)

envFrom as a first-class Helm chart value for cleaner secret injection
Webhook ingestion for Stripe and Coinbase events
Harvest scheduler: automatic profit extraction on configurable rules
OIDC layer at the Ingress for human-facing auth (Clerk / WorkOS)

Medium-term (organism capabilities)

LanceDB per-Darwin vector store for long-horizon episodic memory
Stagehand cached-replay integration for repetitive browser flows
Ads and trading neurons beyond the current content + browser + payments set
Temporal Cloud for durable billing, harvest, and reproduction job orchestration

Long-term (evolutionary system)

Fitness-weighted automated reproduction triggering (no force required)
Cross-lineage lesson distillation — sealed lessons surfaced as platform-level priors
On-chain Merkle anchoring for the audit log (daily root, tamper-evident)
Kubernetes CRD / operator for Darwin lifecycle (kind: Darwin)

Security

Responsible disclosure: if you discover a vulnerability — especially in the kill switch, audit logger, treasury policy, or any code that handles cryptographic signatures or private keys — please report it privately before opening a public issue.

Contact: security@darwinagents.com (PGP key available on request).

Scope of highest concern:

Bypass of the kill switch or pause mechanism
Forgery or replay of a signed DNA layer
Unauthorized spend exceeding treasury policy hard caps
Secret exfiltration from a Darwin's Vault namespace to another tenant

Out of scope: UI bugs, documentation errors, issues with optional extras not installed in production.

We aim to acknowledge reports within 48 hours and provide a fix timeline within 7 days for critical issues.

Contributing

This is a private repository. If you have access, please follow these conventions:

Branching

main is always deployable. Feature work goes on feat/*, fixes on fix/*.
Open a PR against main; at least one review is required before merge.

Commit style — Conventional Commits:

feat(neurons): add analytics.reader neuron
fix(treasury): clamp daily spend before soft-cap comparison
docs(helm): document envFrom injection pattern

Code style

uv run ruff check .    # lint (F, E9, PLE rule set)
uv run ruff format .   # format

Ruff is enforced in CI. The genome's dependency allowlist (pyproject.toml [project.dependencies]) is intentionally minimal — new deps in darwin_dna require explicit justification.

Tests — new behaviour must ship with tests. Hot-path changes (kill_switch, treasury_policy, signature, audit_logger, manifest) require property-based tests (Hypothesis) in addition to unit tests.

Changelog & releases — requires git-cliff on PATH. Config: cliff.toml; automation: scripts/changelog.py via the Makefile.

Typical flow:

make changelog-sync                    # while developing on main
make release VERSION=0.0.2             # when shipping (needs clean auth to origin)

changelog-sync replaces the entire [Unreleased] section — write release notes in commit subjects, or edit the file after sync. Release commit message: chore(release): prepare vX.Y.Z. Opt out of git steps: NO_COMMIT=1, NO_PUSH=1, NO_TAG=1, or NO_BUMP=1 (e.g. make release VERSION=0.0.2 NO_PUSH=1 for a dry run). Details: docs/engineering/25-operational-runbook.md § Repository releases.

License

Boot guarantee

Layer 0 boots a Darwin into a working state on first run — naive and unprofitable is acceptable, non-functional is not. The loop runs, neurons dispatch, the ledger reconciles, the kill switch halts, the audit chain is unbroken. Evolution improves everything above that floor; nothing falls below it.

Command	What it does
`make changelog-sync` (alias `make changelog`)	Rewrite `## [Unreleased]` from conventional commits since the latest tag
`make changelog-preview`	Same content as sync, stdout only
`make release VERSION=0.0.2`	Promote commits to `## [0.0.2]`, clear `[Unreleased]`, bump `pyproject.toml`, `git commit`, annotated tag, `git push` + `git push --tags`

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
docs		docs
infra		infra
scripts		scripts
src		src
tests		tests
tools		tools
web		web
.dockerignore		.dockerignore
.env.example		.env.example
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE.md		LICENSE.md
Makefile		Makefile
README.md		README.md
cliff.toml		cliff.toml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Sunbelt Computer Software

PL/B Language Development and Support

Uh oh!

Latest commit

History

Folders and files

Repository files navigation