- No code changes
- Works on your existing
compose.yml, as a separate copy with its own containers and named volumes. Your files are untouched, and up stops if a writable bind mount would let the copy change your real data.
- Scheduler-aware stepping
- Triggers run at their exact virtual times. BullMQ and Celery beat fire on their own. For pg_cron, the clock stops on each job’s minute so fixed-time jobs run; jobs like
*/5 * * * * run once per stop unless you pass --pg-cron-all.
- Waits for your jobs
- Built-in
bullmq and sidekiq barriers hold each step until the queues are drained, and running jobs finish before the clock moves.
- Outages in virtual time
- A small proxy in front of HTTP dependencies makes “the payment API is down on day 3 from 09:00 to 11:00” a one-liner.
- Scenarios and reports
- YAML steps with SQL, Redis, HTTP and exec checks. JSON, Markdown and JUnit reports.
- Simulated users
- Seeded cohorts of users follow scripted journeys: sign up, think for days, come back, branch. In a scenario they act on the virtual clock, so 20 trialists over 30 days takes minutes, and the same seed gives the same timeline.
- Reach the copy
expose: [api:3000] publishes chosen ports of the copy on 127.0.0.1, and service://api:3000 works in triggers, checks and journeys.
- CI ready
- Exit codes, a GitHub Action, and a strict mode.
- AI agents
chronostack mcp is an MCP server with a fixed, safe tool set: inspect the stack, move time, schedule outages, run scenarios with simulated users, and compare two runs.
- Host-native Node
node -r sdk/node/register.js app.js puts a Node process outside Docker on the same clock.
- Safe by design
- Never changes the host clock, needs no privileged containers, gives no container the Docker socket, and its API is local-only with a token.