Seed and determinism

Given the same boot controls and the same requests in the same order, an emulator answers the same bytes: ids, timestamps, which requests a fault hits, jitter, and the journal. The seed is what fixes every random choice.

#Interface

A seed is a number or a string. A string of digits is that number, so --seed 7, {"seed": 7} and x-mockingbird-seed: 7 are the same seed. The default is 0.

#Admin page

Overview shows the namespace's seed and does not edit it. Change it with PUT /__admin/controls and {"seed": …}, from Routes or the API. Reset returns the seed to the value the process booted with.

#The recipe

Three controls make a run replay exactly:

{ "seed": 7, "clock": { "now": "2030-01-01T00:00:00Z", "frozen": true, "autoAdvance": "1s" }, "virtualTime": true }

npx mockingbird-stripe serve --seed 7 --clock 2030-01-01T00:00:00Z --freeze --auto-advance 1s --virtual-time

#Admin API

#PUT /__admin/controls

Reseed the namespace: its random streams restart from the new seed.

curl -X PUT localhost:8787/__admin/controls -d '{"seed": 7}'

{ "namespace": "default", "seed": 7 }

The response is the namespace's whole control document; seed is the part shown.

#GET /__admin/controls

Read the seed back, with the rest of the namespace's controls.

curl localhost:8787/__admin/controls

#Request header

x-mockingbird-seed: <seed> restarts the namespace's random streams from this seed before the request is handled, and persists.

curl -X POST localhost:8787/v1/customers -H 'x-mockingbird-seed: 7' \
  -H 'authorization: Bearer sk_test_mockingbird' -d email=ada@example.com

#At boot

const stripe = createRuntime({ seed: 7 })
const same = createRuntime({ adminControls: { seed: 7 } })

npx mockingbird-stripe serve --seed 7
MOCKINGBIRD_SEED=7 npx mockingbird-stripe serve

The seed option wins over adminControls.seed when both are given.

#In process

runtime.configure({ seed: 7 })              // reseed "default"
runtime.configure({ seed: 7 }, "worker-3")
runtime.controls("worker-3").seed
runtime.headers({ seed: 7 })                // { "x-mockingbird-seed": "7" }

#What the seed covers

A namespace has three seeded streams, each independent of the others:

Because they are separate, adding latency never shifts which requests a fault hits, and adding a fault never changes a generated id.

• Every namespace draws from the same seed, and each has its own streams and counters, default included. A test gives the same result in worker-1 as in worker-7, and one worker's requests never shift another's.
• Reset rewinds the streams to the boot seed. Restore puts them back where the snapshot left them. A test replays whether it runs first or last.

#Ids that outlive a boot

Id counters restart at 0 on every boot, so by default every boot issues the previous boot's ids, and seed does not change that. A consumer whose database outlives the emulator then meets unique-key collisions. The id base is a separate, boot-time choice that moves a boot onto its own run of ids:

npx mockingbird-twilio serve --id-base 7
npx mockingbird-twilio serve --id-base boot

• A base is a non-negative integer. The same base issues the same ids, a different base issues none of them, and the default 0 is today's ids, so nothing changes until you ask.
• boot takes the base from the wall clock when the emulator starts, so every boot gets a fresh run. That run is not reproducible; use a number when you need one.
• The base is a property of the boot, not of the state: reset and restore leave it as it was.
• A value that is not a non-negative integer or boot stops the command before anything listens.

#Outside the seed

• Key material. Signing keys, vault keys and encryption nonces come from the platform's random source by design. Pin them with the emulator's own fixture option (a vaultKey, a signing key).
• Real waits. Without virtualTime, durationMs is measured and a live clock reads the wall clock.
• Overlapping requests. Order decides which request draws first. Two requests in flight at once in one namespace, or in two namespaces of an emulator built on the shared provider core (Apple, AWS, Clerk, GitHub, Google, Linear, Microsoft, MongoDB Atlas, Okta, Resend, Slack, Twilio, Vercel), can swap the ids they mint. Send them one at a time when you assert on exact ids.

#Errors

#Related

• Clock and Latency and timeouts for the other two parts of the recipe.
• Namespaces for running the same test in parallel workers.