Skip to Content
WorldsTime

Time

One clock per sandbox. Offset it or freeze it.

Every twin in a sandbox reads one clock, and by default it tracks real time. Move it through any twin’s control URL and all of them move together, so a token minted by an identity twin expires on the same timeline the calendar twin is using.

$CONTROL_URL is one twin’s control URL, printed by veris sandbox services get — see the control plane.

Offsetting with offset_seconds

veris sandbox clock set --offset +31d
curl -X PATCH "$CONTROL_URL/veris/data" \
  -H 'Content-Type: application/json' \
  -d '{"data": {"clock": [{"id": 1, "offset_seconds": 2678400}]}}'

Thirty-one days ahead. Time still advances, from a different starting point. Use it to test a trial expiring, a subscription renewing, a token going stale or a retention window closing.

Freezing with mode frozen

veris sandbox clock set --freeze-at 2026-11-01T00:00:00Z
curl -X PATCH "$CONTROL_URL/veris/data" \
  -H 'Content-Type: application/json' \
  -d '{"data": {"clock": [{"id": 1, "mode": "frozen", "frozen_time": 1793491200}]}}'

With the clock frozen, two runs of the same requests against the same world produce byte-identical output, generated ids included.

Freeze it when a test sits on a boundary and you do not want it failing at midnight.

Things to watch

  • Do not move it backwards mid-suite. Rows already written carry timestamps from the old position and would now be in the future. Reset instead.
  • Keep your application’s clock in step. If your code signs or verifies tokens and its own clock disagrees with the twin’s, the skew becomes the test result.
  • An offset can expire the credential you are holding. Jump a year forward and the access token you were using may be past its expiry, exactly as in production.
  • A frozen clock stops callback delivery, because nothing is ever due. Leave the clock live while testing webhooks, or freeze it after delivery.

Returning to live time

veris sandbox reset returns the clock to real time along with everything else. To move only the clock, without touching any twin’s rows:

veris sandbox clock set --live
curl -X POST "$CONTROL_URL/veris/reset-world" -d '{}' \
  -H 'Content-Type: application/json'
Failures and faultsCredentials