Getting Started

Getting Started

Canonical installation and supported workflow: README.md. This page expands the first-run walkthrough.

Prerequisites

• Node.js 22 or newer
• npm 10 or newer
• Git
• Wrangler authentication for Cloudflare work
• OpenAI and GitHub credentials only when testing live reasoning/execution

Clone both repositories

Darwin and ProjectFlow are independent repositories. Place them beside each other:

mkdir C:\codex
cd C:\codex
git clone https://github.com/sjohnston1972/darwin.git
git clone https://github.com/sjohnston1972/projectflow.git

Install Darwin

cd C:\codex\darwin
npm install
Copy-Item .env.example .env

The minimum local .env is:

DARWIN_AI_MODE=live
OPENAI_API_KEY=
OPENAI_MODEL=gpt-5.6
OPENAI_LAB_AGENT_MODEL=gpt-5.6-luna
OPENAI_TIMEOUT_MS=60000
VITE_API_BASE_URL=http://localhost:8787
VITE_PROJECTFLOW_BASE_URL=http://localhost:5174

Collection and evidence generation work without an OpenAI key. Live mutation reasoning fails closed until the key is present.

Start Darwin

npm run dev

This starts:

• control room at http://localhost:5173;
• Worker API at http://localhost:8787.

Start ProjectFlow

In a second shell:

cd C:\codex\projectflow
npm install
npm run dev

Use the URL printed by ProjectFlow, normally http://localhost:5174.

Verify the workspace

cd C:\codex\darwin
npm run lint
npm run typecheck
npm run test
npm run build

First measured cycle

1. Open Darwin and select Target application.
2. Verify the configured ProjectFlow repository and local/remote study URL.
3. Open the measured study.
4. Interact with semantic targets and complete or abandon a task attempt.
5. Return to Observations and wait for the event count to update.
6. Generate evidence.
7. Open Mutations and invoke GPT when configured.

Local in-memory persistence is used when no D1 binding is supplied. Restarting the Worker clears that state.

First Darwin Lab population

1. Start Darwin and ProjectFlow locally.
2. Open Darwin Lab, define a task and success criterion, and create the experiment.
3. Queue the population.
4. From the Darwin repository, run npm run lab:runner.
5. Watch the automated population operate the real target, replay actions, and inspect deterministic L-EV-* evidence populate in the Lab section.
6. When live reasoning is configured, run the single population analysis and approve an implementation brief.

The runner uses gpt-5.6-luna by default for inexpensive per-action decisions. The population-level analysis continues to use gpt-5.6. Both integrations fail closed without OPENAI_API_KEY. Only targets in DARWIN_LAB_ALLOWED_ORIGINS are accepted; the default is local ProjectFlow.

Deterministic scale replay

npm run simulate -- --seed=1859 --variant=baseline

The simulator always produces 10,000 events for the configured variant. It does not populate the real measured study.