ChronoStack
Detects Celery beat and lets scheduled Celery tasks fire during virtual-time advances, with scenario barriers for draining work.
Provides tools for inspecting and controlling a Docker Compose stack on ChronoStack’s virtual clock, including advancing time, scheduling dependency outages, and running scenarios against the stack.
Puts .NET services on the shared virtual clock for time-dependent behavior testing.
Puts Node.js services on the shared virtual clock, including host-native Node processes, so time-dependent logic and scheduled work can be advanced and verified.
Puts PHP services on the shared virtual clock for time-dependent behavior and scheduled-work testing.
Moves PostgreSQL to virtual time, detects and steps through pg_cron jobs, and probes the database after advances so time-dependent SQL and scheduled jobs can be tested.
Puts Python services on the shared virtual clock so time-dependent code and scheduled work can be advanced and verified.
Applies virtual time to Redis expiry and probes Redis after each advance, enabling TTL and cache-expiry behavior to be exercised in scenarios.
Puts Ruby services on the shared virtual clock for time-dependent behavior and scheduled-job testing.
Provides Sidekiq queue barriers so scenario steps wait for jobs to drain and running jobs to finish before time advances.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
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.
Why
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 reportRelated MCP server: chuk-mcp-time
Quickstart
1. 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.
How it works
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" --> SVCOne 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.
Scenarios: repeatable tests in virtual time
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" } }Failure reports a newcomer can read
When something breaks, the Markdown report says what was expected, what happened, and what the services did:
Features
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.
Compatibility
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 ( | ✅ Work without triggers (measured) |
Celery beat crontab tasks under django-celery-beat's | ⚠️ May not fire after a jump; use triggers (#9) |
BullMQ and Sidekiq barriers | ✅ Nightly, with real workers |
node-cron, APScheduler, Spring | Need a trigger (measured) |
Go and other static or setuid binaries | ❌ Not supported ( |
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.
How it compares
Tool | What it does | What ChronoStack adds |
Fakes time per process ( | Live control across containers, deadline safety, scheduler-aware stepping, probes, outages, scenarios | |
Simulated time for Stripe objects | The same idea for your database, cache and jobs | |
Fake timers (Node | In-process time for unit tests | Integration across processes and services |
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.
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.
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. | |
Twenty | The trash cleanup permanently deleted records up to a day before the retention period ended. | |
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. | |
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. |
The setups, scenarios and run reports are in docs/launch/outreach.
Documentation
Install, demo, your first project, cheat sheet, FAQ | |
| |
The SaaS example used above | |
How it works, and why | |
Milestones M0–M5 and their test results | |
The index |
Contributing
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.
License
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.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Calculate API and subscription costs, meeting time zones, recurring schedules and cron matches.
Date/time math for agents: business days, holidays, time zones, cron, RRULE. 25 free calls/day.
Current time, timezone conversion & date math for AI agents. On Cloudflare Workers.
Deterministic time tools for AI agents: timezone conversion, business-day math, cron interpretation.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides comprehensive time manipulation capabilities including timezone conversions, date arithmetic, business day calculations, duration calculations, and recurring event handling. Enables natural language time queries with high performance and intelligent caching.113MIT
- AlicenseAqualityFmaintenanceProvides high-accuracy time information by querying multiple NTP servers for consensus time, and comprehensive timezone support using IANA tzdata for conversions, DST handling, and clock drift detection independent of system time.73Apache 2.0
- AlicenseAqualityDmaintenanceMCP server providing various date/time functions including current time, timezone conversion, and relative time calculations. Supports both local stdio and remote HTTP access via Cloudflare Workers.6243 npm2MIT
- AlicenseNot gradedqualityFmaintenanceProvides real-time temporal drift to SOUL.md agent identities, enabling agents to check their current behavioral state through tools like get_daily_drift.MIT