Setup

WorldFork has two setup paths:

  1. Agent-guided setup, which is the preferred onboarding path.

  2. Complete manual setup, for operators who want every command.

Agent-Guided Setup

Paste this prompt into your agent:

Run this command to install the WorldFork skill, then use it to set up WorldFork on this computer:

npx skills add Hilo-Hilo/WorldFork/skills/worldfork --all

After installing it, use the setup module in the skill to guide me through prerequisites,
.env configuration with OPENROUTER_API_KEY, CLI installation, Docker Compose
startup, migrations, seeding, readiness verification, a short explanation of
Big Bangs, multiverses, ticks, branches, endpoint ledgers, and reports, and the
onboarding demo if I confirm I want to spend live API credits. Be welcoming and
proactive: explain what each setup phase proves, use `worldfork setup` to show
provider options, ask which providers I want to configure, recommend the
fast-cheap cohort plus stronger governance/report split for Atlas, and narrate
what Atlas is doing while it runs.
Use the configured split for live API-credit runs: OpenRouter `deepseek/deepseek-v4-flash` for fast cohort/hero/action/event-summary/single-report work, and OpenAI Codex `gpt-5.4` for initializer, God-review, endpoint-ledger, report fallback, and final multiverse report synthesis.

Complete Manual Setup

Use this path when you want to run each command yourself.

Prerequisites

  • Docker Desktop or another Docker Compose runtime

  • Python 3.11 or newer

  • uv

  • Node.js 20 or newer for npx skills

  • An OpenRouter API key

Configure Environment

Copy the example environment:

cp .env.example .env

Set OPENROUTER_API_KEY in .env.

WorldFork can route cohort, hero, action, event-summary, predicate, and single-report work to deepseek/deepseek-v4-flash through OpenRouter. Initializer, God-review, endpoint-ledger, report fallback, and final multiverse report routes use OpenAI Codex gpt-5.4 by default unless you intentionally choose another configured strong model.

Install The CLI

Install the CLI package from the monorepo:

python3.11 -m pip install -e ./cli
worldfork --help

If worldfork resolves to an old global shim, reinstall the editable CLI and check which -a worldfork. While repairing a shim, use the source-checkout fallback from cli/:

uv run --extra dev worldfork --help

The CLI chooses its backend target in this order:

  1. --base-url

  2. WORLD_FORK_API_BASE

  3. BACKEND_API_BASE

  4. http://127.0.0.1:8003

After the CLI is installed, configure the strong governance/report route. For OpenAI Codex OAuth:

worldfork settings openai-codex-login

This writes the default auth file under ~/.worldfork/. Operators may instead set OPENAI_CODEX_OAUTH_TOKEN or OPENAI_CODEX_AUTH_FILE in .env.

Start The Stack

make build
make up
make migrate
make seed

Use make logs if the API or worker fails to start.

If startup or readiness fails, check Docker Desktop first, then check for host port conflicts on 8003, 5433, and 6379.

Update Later

Use the CLI updater for normal code refreshes:

npx skills add Hilo-Hilo/WorldFork/skills/worldfork --all
worldfork update --dry-run
worldfork update --yes

Refresh the worldfork skill first so the agent has the latest update runbook. The updater only fast-forwards the source checkout. It does not overwrite .env, local Docker overrides, run folders, artifacts, or database state, and it does not run migrations unless a future command explicitly adds that behavior.

Verify Readiness

worldfork status
worldfork query GET /readyz --no-api-prefix

Readiness should show the database and Redis checks as healthy. OpenRouter is healthy when OPENROUTER_API_KEY is set, and OpenAI Codex is healthy when OAuth auth is present if that provider is part of the configured route policy.

Confirm the effective model and provider routes before spending live API credits:

worldfork setup
worldfork settings llm

worldfork setup is the compact provider-choice helper for agents and first-time operators. It lists available provider options, shows the recommended Atlas profile, and tells the agent what to ask before configuring API keys or model routes. Use worldfork setup --include-patch only when the agent needs the full Atlas routing PATCH payload. Local OpenAI-compatible providers such as Ollama, vLLM, LM Studio, and LocalAI are supported through provider rows with api_key_env: "none" and can be routed to any audited agent type; use host.docker.internal in the base URL when the backend runs inside Docker on macOS. If a strict local proxy rejects bearer headers, set payload.omit_auth_header: true on that provider row.

For actor calls, prefer the audited route names cohort_agent and hero_agent. The internal worker job for one actor decision is actor_deliberation_call.

First Big Bang

worldfork init \
  --name "Atlas onboarding" \
  --scenario-file examples/test-big-bang.md \
  --max-ticks 4 \
  --tick-duration-minutes 720

The command waits for backend initialization to return and then prints the initialized workspace, actors, traits, graph baseline, sociology baseline, and emotion baseline. This verifies setup and initialization. Use worldfork demo atlas for a full tick, branch, endpoint-ledger, and report demonstration.

Inspect the initialized workspace:

worldfork watch big-bang <big-bang-id> --once
worldfork runs workspace <big-bang-id>
worldfork runs cost <big-bang-id>
worldfork ledgers list <big-bang-id>
worldfork logs list --status failed

For the detailed initializer, tick, queue, timing, and ledger flow behind this first run, see Runtime Walkthrough.

Stop Or Reset

Stop services without deleting data:

make down

Stop services and remove Docker volumes:

make clean-data