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.
Getting started · Guide · Demo · Docs
Note
Alpha. The latest release, v0.1.0-alpha.8, is tested in CI on Linux (x86_64 and arm64) and on macOS (Intel, Docker in a Linux VM), and by hand on Windows. On Apple-silicon Macs, the installer and the native CLI are tested in CI, but running containers there is untested: if you have one, issue #5 has a 5-minute test.
Trials that expire, sessions that time out, renewals, dunning, retention purges, webhook retries: time-dependent code is some of the least-tested code in any SaaS product. It's usually tested by editing timestamps in the database, shortening durations with a flag, or not at all. None of these exercises the real interaction between the database's now(), Redis expiry, your schedulers and your services.
ChronoStack gives your whole stack one virtual clock that you control:
$ chronostack up --wait # a copy of your compose stack, on a virtual clock
$ chronostack advance 14d # 14 days later in Postgres, Redis, Node, Python, …
# and your nightly job ran at each virtual 03:00
$ chronostack run scenarios/trial.yml # a scripted, repeatable test with a report1. Install. You need Docker with Compose v2. No admin rights needed.
# Linux / macOS
curl -fsSL https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.sh | CHRONOSTACK_VERSION=0.1.0-alpha.8 sh# Windows (PowerShell)
$env:CHRONOSTACK_VERSION = "0.1.0-alpha.8"; irm https://github.com/Asmodeus14/ChronoStack/releases/download/v0.1.0-alpha.8/install.ps1 | iexOr with a package manager:
# Homebrew (macOS, Linux)
brew install asmodeus14/tap/chronostack# Scoop (Windows)
scoop bucket add chronostack https://github.com/Asmodeus14/scoop-bucket
scoop install chronostack/chronostack2. 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.yml3. Use it on your project: cd to your compose project and run chronostack init (a starter chronostack.yml for your schedulers and queues), then chronostack up --wait and chronostack doctor. Then follow Getting started, a 10-minute walkthrough with a cheat sheet and FAQ.
Update any time with chronostack update. The installer verifies checksums and puts chronostack on your PATH; details and uninstall.
flowchart LR
CLI["chronostack CLI<br/>(your machine)"] -- "localhost API + token" --> CLOCKD["clockd container<br/>the only clock writer"]
CLOCKD -- writes --> PAGE[("shared clock page<br/>(Docker volume)")]
PAGE -- "read-only" --> SVC["your services<br/>Postgres · Redis · Node · Python · JVM · Ruby · PHP · .NET"]
CLI -- "triggers · barriers · probes" --> SVC
- One clock for every service. A small C library loaded with
LD_PRELOADmakes 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. That's checked in C, Python, Node and the JVM (results), and re-run every night in CI. - Moving the clock runs your scheduled work. Changing the clock doesn't fire timers (why). So
advancestops at each interesting virtual time, runs the triggers you declare (e.g. "the nightly job at 03:00"), and waits on barriers (e.g. "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
doctorexplains anything it can't reach.
Script the story, including an outage of an HTTP dependency in virtual time, and assert the outcome:
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" } }When something breaks, the Markdown report says what was expected, what happened, and what the services did:
- No code changes: 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, soupstops if one is writable instead of letting 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
bullmqandsidekiqbarriers 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 (
httporhttps) 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 and Markdown reports, with secrets redacted.
- Simulated users:
chronostack users runsends seeded cohorts of users through scripted journeys (requests, think times, branches) and reports failures and latency per step (guide). - CI ready: exit codes, a GitHub Action, and a strict mode.
- AI agents:
chronostack mcpis an MCP server with a fixed, safe tool set: inspect the stack, move time, schedule outages, run scenarios with simulated users and compare runs (claude mcp add chronostack -- chronostack mcp --project-dir <project>; Cursor, Gemini CLI). - Host-native Node:
node -r sdk/node/register.js app.jsputs a Node process outside Docker on the same clock (details). - 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.
Listed as tested only where an automated test covers it.
| Component | Status |
|---|---|
| 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 8 | ✅ Nightly no-hang suite and clock check; not yet tried on real apps |
| Node.js 20, Python 3.13+, MariaDB | Expected to work; not covered by tests |
BullMQ, Celery beat (beat_max_loop_interval ≤ 1), pg_cron |
✅ Work without triggers (measured) |
Celery beat crontab tasks under django-celery-beat's DatabaseScheduler |
|
| BullMQ and Sidekiq barriers | ✅ Nightly, with real workers |
node-cron, APScheduler, Spring @Scheduled, Laravel schedule:work, sidekiq-cron, setTimeout-style loops |
Need a trigger (measured) |
| Go and other static or setuid binaries | ❌ Not supported (LD_PRELOAD can't reach them); flagged by doctor |
| 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, Colima) |
| Host: macOS Apple silicon: installer and native CLI | ✅ CI (release install test) |
| Host: macOS Apple silicon: running containers (Docker Desktop, OrbStack) | ❓ Untested (help wanted) |
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.
| Tool | What it does | What ChronoStack adds |
|---|---|---|
| libfaketime | Fakes time per process (LD_PRELOAD) |
Live control across containers, deadline safety, scheduler-aware stepping, probes, outages, scenarios |
| Stripe Test Clocks | Simulated time for Stripe objects | The same idea for your database, cache and jobs |
Fake timers (Node MockTimers, freezegun, time-machine) |
In-process time for unit tests | Integration across processes and services |
| Toxiproxy | TCP faults in real time | Outages scheduled on the virtual timeline |
Faking the time isn't new; the orchestration, safety and lifecycle workflow are what ChronoStack adds. Full analysis.
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.
| Project | What was wrong | Status |
|---|---|---|
| Saleor | Unpaid 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 |
| Twenty | The trash cleanup permanently deleted records up to a day before the retention period ended. | Fixed · issue · PR |
| Chatwoot | Conversations whose snooze ended while background jobs were down for more than 3 days were never reopened. | Confirmed by maintainers · issue · community fix PR |
| Formbricks | With a scheduling time zone at UTC+12 or later, such as New Zealand, surveys opened and closed a day late. | Confirmed by maintainers · issue |
| tududi | Monthly 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 |
| Worklenz | Monthly "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 |
The setups, scenarios and run reports are in docs/launch/outreach.
| Getting started | Install, demo, your first project, cheat sheet, FAQ |
| Guide | doctor, triggers, barriers, outages, scenarios, CI, troubleshooting |
| Demo app | The SaaS example used above |
| Architecture · Decisions | How it works, and why |
| Project status | Milestones M0–M5 and their test results |
| All documents | The index |
The most useful help right now:
- Try
chronostack up --wait && chronostack doctoron your own compose project and tell us what breaks. Include thedoctoroutput. - Run the macOS test in #5.
- Share how you test time-dependent code today.
See CONTRIBUTING.md to build from source, and the Code of Conduct. Security issues go through SECURITY.md, not public issues. Accessibility barriers are bugs: see ACCESSIBILITY.md.
Licensed under either of Apache License, Version 2.0 or MIT license, at your option. Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

