WorldFixture runs reproducible software worlds on a local computer. A world can contain people, messages, repositories, mail, files, and a live timeline. Applications, MCP servers, tests, scripts, people, and AI agents use normal provider-shaped APIs and protocols to work with that world.

[!WARNING] WorldFixture is pre-release software. See the release checklist for the external-use proof.

What you get

One local Docker container with a complete synthetic world.
Slack, GitHub, Google, Stripe, S3, SMTP, IMAP, and other service interfaces.
A CLI for lifecycle, health, people, messages, mail, and events.
An optional Workbench for inspection and manual actions.
A deterministic world compiler and schema-validated artifacts.
A world-relative clock and scheduled arrivals that use the same provider interfaces as manual actions.
No hosted runtime and no model calls in the default experience.

All included people, organizations, messages, and financial records are synthetic.

Quick start

Requirements

Docker with Buildx
Node.js 22 or later
An arm64 or amd64 computer

Build the local image:

PYTHONPATH=compiler python3 -m worldfixture_compiler build \
  worlds/business.saas-company.v3/world.json \
  --output dist/business.saas-company.v3
docker buildx build --load -t worldfixture:local .

Start the default business.saas-company:v3 world:

node runtime/bin/worldfixture.mjs up

The command starts one background container. It uses the preferred local ports when they are free and selects free ports when they are in use. It records and prints the actual addresses.

A full v3 start takes about two minutes, because the mail service creates a mailbox for every person and delivers all 3,069 seeded messages over LMTP. The Workbench URL is printed after a couple of seconds and is usable while the rest of the world is still loading.

Start only the parts you need and that wait mostly disappears:

node runtime/bin/worldfixture.mjs up --only slack,github

Measured on an arm64 machine: every part 117s, everything except mail 41s, slack,github 1s. The parts are slack, github, site, mail, s3 and providers; the default is all of them.

Use the world from another terminal:

node runtime/bin/worldfixture.mjs status
node runtime/bin/worldfixture.mjs people
node runtime/bin/worldfixture.mjs slack history --channel general
node runtime/bin/worldfixture.mjs mail inbox --as maya
node runtime/bin/worldfixture.mjs open
node runtime/bin/worldfixture.mjs events --follow

Run node runtime/bin/worldfixture.mjs env to print application bindings. Use Ctrl-C to stop events --follow. The background world continues to run.

Restore or stop the instance:

node runtime/bin/worldfixture.mjs reset
node runtime/bin/worldfixture.mjs down

reset restores provider, mail, storage, runtime, clock, and timeline state to the accepted start. It preserves PostgreSQL and MySQL application data. down stops and removes the container but keeps the local diagnostic state in .worldfixture/.

If startup or a service fails, run:

node runtime/bin/worldfixture.mjs doctor

doctor reports problems and recommended commands. It does not change state.

Example applications

Start WorldFixture first. Then use one of these examples:

Relay Digest is a normal Node.js SaaS application. It reads and changes the world through provider APIs.
Renewal Copilot is an MCP server with a review UI and a human approval step.
The protocol application is a small Python release gate for SMTP, IMAP, HTTP, and S3.

Connect your application

An application connector maps neutral world packs to an application's existing domain model. It can seed a starting state and accept live events. The connector is enabled only for local development or tests.

Run these commands from the application root:

npx worldfixture up
npx worldfixture connector prompt http://localhost:3000
npx worldfixture run -- npm run dev

Give the generated prompt to a coding agent. The portable add-worldfixture-connector skill is in skills/add-worldfixture-connector. After the agent adds the connector, check and seed it:

npx worldfixture connector check http://localhost:3000
npx worldfixture connector plan http://localhost:3000
npx worldfixture connector seed http://localhost:3000

The Workbench provides the same connect, prompt, preview, seed, and live event operations under Target. See the connector overview.

Optional PostgreSQL or MySQL database

Select optional services in .worldfixture/project.json:

{
  "api_version": "worldfixture.project/v1",
  "application_url": "http://localhost:3000",
  "services": ["mysql"]
}

Use "postgres" instead for PostgreSQL. worldfixture run supplies the active connection bindings. MySQL-compatible MariaDB 10.11 provides MYSQL_HOST, MYSQL_PORT, MYSQL_USERNAME, MYSQL_PASSWORD, MYSQL_DATABASE, and MYSQL_URL. PostgreSQL provides the equivalent POSTGRES_* bindings. Ports can change when a preferred port is in use, so applications must use these values.

Normal worldfixture reset preserves database data. The connector always declares database reset unavailable and never deletes application records. A future destructive database rebuild must use a separate, explicit command.

Main commands

worldfixture up [world]        Start or reuse a local instance
  --only <parts>               Start only these parts of the world
worldfixture open              Open the recorded Workbench URL
worldfixture status            Show live service health
worldfixture env               Print application bindings
worldfixture doctor            Diagnose the local setup
worldfixture reset             Restore the accepted starting state
worldfixture down              Stop and remove the instance
worldfixture people            List people and provider identities
worldfixture slack ...         Read or send Slack messages
worldfixture mail ...          Read mail over IMAP
worldfixture events [--follow] Read the runtime event ledger
worldfixture connector ...     Check, seed, or send events to an application
worldfixture run -- <command>  Run an application with active bindings

Run node runtime/bin/worldfixture.mjs --help for options.

Build a world artifact

The default v3 world is the active product world. The smaller v2 world remains the compatibility and byte-parity fixture.

Validate and compile v3:

PYTHONPATH=compiler python3 -m worldfixture_compiler validate \
  worlds/business.saas-company.v3/world.json
PYTHONPATH=compiler python3 -m worldfixture_compiler build \
  worlds/business.saas-company.v3/world.json \
  --output dist/business.saas-company.v3

Create one deterministic bundle:

PYTHONPATH=compiler python3 -m worldfixture_compiler bundle \
  worlds/business.saas-company.v3/world.json \
  --output dist/business.saas-company.v3.tar

Bundle members have fixed ownership, permissions, timestamps, and order. The same source produces the same artifact bytes.

Architecture

world definition -> deterministic artifact -> environment lock -> instance
                                                               -> reset

The runtime has three main concepts:

A world is immutable starting data, relationships, identities, history, and optional scheduled arrivals.
A service provides a real interface, such as Slack, SMTP, IMAP, GitHub, or S3, from a projection of the world.
The runtime owns the clock, commands, observations, schedules, causal rules, and local lifecycle.

The default image uses tini as PID 1. One Node.js supervisor starts the provider composer, HTTP targets, Cyrus IMAP, SMTP, SeaweedFS, SQLite runtime, and Workbench. Applications do not read internal stores. They use the published interfaces.

Repository guide

compiler/worldfixture_compiler/   deterministic world compiler
schemas/                          public JSON Schema contracts
worlds/                           reviewed synthetic world sources
runtime/                          CLI, resolver, supervisor, state, and UI
emulators/                        provider, HTTP, mail, and S3 services
examples/                         normal app, MCP server, and protocol client
tests/                            contracts, parity, and image tests
docs/                             release checks

Each service in emulators/ has a README with its protocol, ports, test command, and current limits.

Provider coverage is documented by provider. See the Notion support matrix and the provider implementation process.

Development

Run the dependency-free compiler and contract tests:

PYTHONPATH=compiler python3 -m unittest discover -s tests -t .

Run the runtime tests:

cd runtime
npm test

Some runtime and protocol tests require Docker or a built worldfixture:local image. See CONTRIBUTING.md for the full test groups and change rules.

Open-source foundations

Project	Role	Pinned version	License
`emulate`	Provider-shaped APIs	`0.10.0`	Apache-2.0
Cyrus IMAP	Mailbox storage and IMAP	`3.6.1`	BSD-3-Clause-CMU and component notices
SeaweedFS	S3-compatible object storage	`4.41`	Apache-2.0
PostgreSQL	Optional PostgreSQL database	`15.19`	PostgreSQL License
MariaDB	Optional MySQL-compatible database	`10.11.18`	GPL-2.0
SQLite	Runtime events, schedules, cursors, and state	System package	Public domain

Dependency versions stay pinned. Third-party notices for the mail and S3 images are in their emulator directories. A complete release inventory is still required before public distribution.

Project status

The product scope is the local runtime, v3 world, compiler, Workbench, and examples that work today. The release proof is one outside developer who can build the image, start the world, use it, reset it, and stop it from this README. See the release checklist for that proof.

WorldFixture is available under the Apache License 2.0.