ChronoStack: time-travel testing for Docker Compose stacks

Stripe Test Clocks for your Docker Compose stack.

Move Postgres, Redis and your services forward in time together, run the jobs that depend on it, and verify what happened. No code changes.

curl -fsSL https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.sh | CHRONOSTACK_VERSION=0.1.0-alpha.8 sh

Alpha · v0.1.0-alpha.8 · MIT or Apache-2.0

Trials expire. Sessions time out. Renewals, dunning, retention purges and webhook retries all wait for a date. Time-dependent code is some of the least-tested code in any SaaS product.

How it gets tested today:

  • Editing timestamps in the database by hand
  • Shortening durations with a test-only flag
  • Waiting real days in staging
  • Not at all

None of these exercise the real interaction between the database's now(), Redis expiry, your schedulers and your services.

One clock for the whole stack.

Every service reads the same virtual time. Advance it, and the jobs that depend on it actually run, at the virtual time they're due.

+00d 00:00chronostack up --wait

How it works

One clock for every service.

A small C library loaded with LD_PRELOAD makes wall-clock reads (now(), Date.now(), time.time(), Redis expiry) return virtual time. It adds about 12–16 ns per read in C and 10–26 ns in Python and Node, measured on three machines (benchmarks). Monotonic clocks are left alone, and absolute deadlines are translated back to real time, so the timed waits behind locks and timeouts return on time instead of hanging (tested nightly in C, Python, Node and the JVM).

Moving the clock runs your scheduled work.

Changing the clock doesn't fire timers. So advance stops at each interesting virtual time, runs the triggers you declare (“the nightly job at 03:00”), and waits on barriers (“the queue is empty”) before moving on. pg_cron is detected and handled automatically.

Everything is verified.

After each advance, every service is probed to confirm it sees the new time, and chronostack doctor explains anything it can't reach.

Try it here.

A simulation of the demo app, running in your browser: one user on a 14-day trial, a nightly job at 03:00 that ends expired trials, and a webhook when it does. Type a command or pick one below. The real CLI drives Docker; this one only pretends.

simulated

virtual time+00d 00:00

postgres
trial_ends_at +14d 00:00
redis
webhook:received 0
api
plan: trial
worker
nightly job ran 0 times

Script the outage.
Assert the outcome.

Scenarios are repeatable tests in virtual time. Take the partner's webhook receiver down on day 14 from 02:00 to 06:00, advance, and check that the webhook was retried and delivered exactly once.

steps:
  - fault: { target: webhooks, from: +14d2h, for: 4h }   # partner down on day 14, 02:00–06:00
  - advance: 14d
  - advance: { by: 12h, step: 1h }
  - assert:
      redis:
        service: cache
        command: [HGET, webhook:received, "trial.expired:${user_id}"]
        equals: "1"

Failure reports a newcomer can read.

When something breaks, the Markdown report says what was expected, what happened, and what the services did. JSON too, with secrets redacted.

Built to sit on the stack you already have.

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.

How it compares.

Faking the time isn't new. The orchestration, safety and lifecycle workflow are what ChronoStack adds.

ToolWhat it doesWhat ChronoStack adds
libfaketimeFakes time per process (LD_PRELOAD)Live control across containers, deadline safety, scheduler-aware stepping, probes, outages, scenarios
Stripe Test ClocksSimulated time for Stripe objectsThe same idea for your database, cache and jobs
Fake timers Node MockTimers, freezegun, time-machineIn-process time for unit testsIntegration across processes and services
ToxiproxyTCP faults in real timeOutages scheduled on the virtual timeline

Found in real projects.

Each bug was reproduced on the project's own published image, with the whole stack's clock moved forward, and reported upstream. Thanks to the maintainers for their work and their time.

ProjectWhat was wrongStatus
SaleorUnpaid orders set to expire after a day or more expired far too late: 24 h became about 47.6 h, and 48 h about 62 days.Fix proposed · issue · PR
TwentyThe trash cleanup permanently deleted records up to a day before the retention period ended.Fixed · issue · PR
ChatwootConversations whose snooze ended while background jobs were down for more than 3 days were never reopened.Confirmed by maintainers · issue · community fix PR
FormbricksWith a scheduling time zone at UTC+12 or later, such as New Zealand, surveys opened and closed a day late.Confirmed by maintainers · issue
tududiMonthly recurring tasks moved to the wrong day: for users in the Americas, “on the 1st” became the last day of the previous month, and “last Friday” skipped months.Fix proposed · issue · PR
WorklenzMonthly “Nth weekday” recurring tasks landed on the wrong date: “1st Monday” moved back into the previous month and then stopped recurring, and “2nd Tuesday” came a week early.Fixed · issue · PR

Honest compatibility.

Listed as tested only where an automated test covers it.

ComponentStatus
PostgreSQL 16 (Debian, Alpine), including pg_cron · Redis 7 (Debian, Alpine)Tested in CI
Node.js 22 · Python 3.10 / 3.12 (Debian, Alpine)Tested in CI, plus a nightly no-hang suite
JVM 17 / 21 · Ruby 3.3 · PHP 8.3 · .NET 8Nightly no-hang suite and clock check; not yet tried on real apps
BullMQ, Celery beat, pg_cronWork without triggers (measured)
node-cron, APScheduler, Spring @Scheduled, Laravel schedule:work, sidekiq-cron, setTimeout-style loopsNeed a trigger (measured)
Node.js 20, Python 3.13+, MariaDBExpected to work; not covered by tests
Hosts: Linux x86_64 / arm64 · Windows 11 (Docker Desktop)CI · tested by hand
Host: macOS Intel (native CLI, Docker in a Linux VM)CI (nightly)
Host: macOS Apple silicon: installer and native CLICI (release)
Host: macOS Apple silicon: running containers (Docker Desktop, OrbStack)Untested · help wanted
Go and other static or setuid binariesNot supported; flagged by doctor

Limitations

  • Time only moves forward.
  • App timers don't fire early; use triggers.
  • Postgres now() is fixed within a transaction.
  • Outage URLs must come from environment variables.
Full list of limitations

Questions.

Does ChronoStack change my computer's clock?

No. It never touches the host clock and needs no privileged containers. Virtual time exists only inside the copy of your stack that ChronoStack starts: a small library loaded with LD_PRELOAD makes wall-clock reads in those containers return virtual time.

Do I have to change my code or my compose file?

No. ChronoStack works on your existing compose.yml, as a separate copy with its own containers and named volumes, and leaves your files untouched. Bind mounts and external volumes can't be copied, so up stops if one is writable. When a scheduler needs help firing at the right virtual time, that's one line of YAML (a trigger).

Which languages and databases does it support?

Tested in CI: PostgreSQL 16 (including pg_cron), Redis 7, Node.js 22 and Python 3.10 / 3.12. JVM 17 and 21, Ruby 3.3, PHP 8.3 and .NET 8 pass a nightly no-hang suite and clock check but haven't been tried on real apps yet. Node.js 20, Python 3.13+ and MariaDB are expected to work but aren't covered by tests.

Does it work with Go?

Not yet. Go and other static or setuid binaries don't load LD_PRELOAD libraries, so their clocks can't be redirected. chronostack doctor flags them.

Why doesn't my app's timer fire when I advance the clock?

Changing the clock doesn't fire timers that are already waiting. So advance stops at each interesting virtual time and runs the triggers you declare, such as “the nightly job at 03:00”. BullMQ, Celery beat and pg_cron fire on their own; node-cron, APScheduler and setTimeout-style loops need a trigger.

Can I move time backwards?

No. Virtual time only moves forward, the way real deadlines, expiries and logs expect it to.

Can I run it in CI?

Yes. Scenarios return exit codes and write JSON and Markdown reports, there's a GitHub Action, and a strict mode for pipelines.

Does it work on macOS or Kubernetes?

macOS on Intel is tested in CI (the native CLI with Docker in a Linux VM). On Apple-silicon Macs the installer and the native CLI are tested in CI, but running containers there (Docker Desktop, OrbStack) is untested; issue #5 has a 5-minute test if you can help. Kubernetes is out of scope for the 0.x releases; ChronoStack targets Docker Compose.

Is it free?

Yes. ChronoStack is open source, licensed under MIT or Apache-2.0, at your option.

Install in one line.

You need Docker with Compose v2. No admin rights needed. The installer verifies checksums and puts chronostack on your PATH.

curl -fsSL https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.sh | CHRONOSTACK_VERSION=0.1.0-alpha.8 sh

Or with a package manager. Homebrew on macOS and Linux: brew install asmodeus14/tap/chronostack. Scoop on Windows: scoop bucket add chronostack https://github.com/Asmodeus14/scoop-bucket, then scoop install chronostack/chronostack.

Then run the demo

A small SaaS app with a 14-day trial, a nightly job and webhooks.

git clone https://github.com/Asmodeus14/ChronoStack && cd ChronoStack/examples/saas-trial-demo
chronostack up --wait
chronostack advance 15d        # the trial expires at the nightly job
chronostack run scenarios/trial.yml

Try it on your own stack, and tell us what breaks.

ChronoStack is in alpha. Run chronostack up --wait && chronostack doctor on your compose project and send a short report, whether it worked or not. Have a Mac? You'd be among the first to run it there.