The simulated clock

Everything simulated reads the universe’s clock: message dates, reply delays, working hours, promises, inbound streams and fault windows. So a test can live through a week of correspondence in seconds.

The clock is per universe. Skipping ahead in your CI universe does not move the clock in Staging.

Modes

Mode	What happens	API
Live	Simulated time is real time, at 1×.	POST /api/clock/live
Speed	Time runs at a multiple of real time. 60 is an hour per minute.	POST /api/clock/speed with {"factor": 60}
Frozen	Time stands still. Nothing new falls due.	POST /api/clock/freeze (the same as speed 0)
Skip ahead	Time jumps forward by a duration.	POST /api/clock/advance with {"duration": "3d"}

Durations are strings such as 90m, 2h or 3d.

Skipping ahead

When you skip ahead, everything that falls due on the way runs, at its own due time and in order. Replies that would have come at 14:10 and 16:45 are written as of 14:10 and 16:45. Jobs that run can schedule more inside the same window; those run too.

curl -s -X POST https://c1.simmail.dev/api/clock/advance \
  -H "Authorization: Bearer smk_your_key" \
  -H "Content-Type: application/json" \
  -d '{"duration": "1d"}'

{
  "clock": { "now": "2026-10-11T09:12:00Z", "speed": 1, "frozen": false, "real": "2026-10-10T09:12:00Z" },
  "jobs_run": 4
}

Back to live

POST /api/clock/live puts the clock back on real time, at 1×. Things already scheduled for later simulated times happen when real time gets there. The dashboard shows when a universe is not live, with a link to go back.

Reading the clock

curl -s https://c1.simmail.dev/api/clock -H "Authorization: Bearer smk_your_key"

Field	Meaning
now	The simulated time.
speed	The rate; 0 when frozen.
frozen	Whether time stands still.
real	The real time when it was read.

Restarts

The clock survives restarts. A running clock catches up on the time that passed while the server was down, at its speed. A frozen clock stays where it was.

The clock and tests

Most tests do not need to move the clock at all. GET /api/wait/reply?fast=true has a person write their due reply now. Move the clock when you test what happens over time: a promise that slips, a nudge two days later, a week of inbound leads.

Note

When the simulated clock is more than an hour away from real time, the spam check leaves out date-based findings, since the odd dates are simmail’s doing, not your app’s.

The pace setting is separate from the clock: it scales how long people take to reply. See Behaviour settings.