Concepts
Glossary
Each term in one sentence, with where you meet it.
Clock
Every simulator keeps its own clock, which supplies every timestamp, moves one millisecond per request that stamps a time, and follows wall time only when paced or while a Kalshi tape or live feed drives it.
Where: POST /_rystic/clock, initial_clock on GET /_rystic/version, rystic run --clock and --speed. Reset and determinism → The clock.
Control plane
The routes under /_rystic/ that every simulator serves beside the vendor’s API (plus /_replay/ on Kalshi), to load a scenario, seed records, move the clock, read state and egress, and reset.
Where: /_rystic/*, rystic tail, the state UI. Control plane and plans lists every route.
Egress log
What a simulator would have sent out, in order: Stripe’s webhooks, Resend’s emails, Kalshi’s WebSocket frames.
Where: GET /_rystic/egress, the state UI’s Effects card, rystic run --egress-retain. Observing → Egress, Webhooks.
Entitlements
The features a Free or Pro simulator’s lease grants, ["state_view","state_set","scenarios","ui","replay"] on Free and ["*"] (every feature) on Pro, along with grants such as verified_ui.
Where: GET /_rystic/version, under lease.entitlements. Control plane and plans.
Environment
The simulators your code or agent acts on, started, stopped and clocked together.
Where: a rystic.yaml stack, rystic up, rystic down, rystic clock, the Harbor environment image. Multi-simulator environments.
Feature
A named group of control routes and boot inputs that a plan unlocks (state_view, state_set, scenarios, faults, ui, replay); a route whose feature the plan lacks answers 403 naming it.
Where: the feature key of a 403 from /_rystic/*. Control plane and plans maps each route to its feature.
Fidelity
How closely a simulator matches the real API it models, checked by three gates: unit tests against the live API field by field, multi-step workflow tests and real-world usage.
Where: the Fidelity cards, whose matches live figure is the share of a simulator’s endpoint checks whose answers matched the live API.
Gateway
The local HTTPS proxy, one per project on 127.0.0.1, that terminates TLS for each vendor host an --intercept simulator claims and forwards the call to that simulator.
Where: rystic gateway, rystic exec, rystic env, ~/.rystic/run/gateway/. Intercept vendor calls.
Harbor
A runner for agent tasks that runs each episode in a sandbox; Rystic’s Slack MCP image puts a seeded Slack simulator, the native Slack MCP server and the episode runtime inside it, on an Enterprise license.
Where: Slack MCP in Harbor, Slack Harbor reference run.
Intercept
Running a simulator behind the local gateway, so your code’s calls to the vendor’s own hosts (api.stripe.com, slack.com, …) land on the simulator with no base-URL change.
Where: rystic run <product> --intercept, rystic exec -- <command>. Intercept vendor calls.
Lease
The grant Rystic signs when a Free or Pro simulator starts and renews as the simulator checks in every 30 seconds; it carries the plan’s entitlements, and an Enterprise build runs on a license file instead.
Where: lease on GET /_rystic/version, https://lease.rystic.ai, RYSTIC_LEASE_URL. Plans and API keys → What a running simulator sends.
Named scenario
A starting state built into a simulator’s binary and loaded by name, such as design_studio: one company, Website Design Contractors, on Lob, Okta, PayPal, Resend, Slack and Stripe.
Where: rystic run <product> --scenario <name>, POST /_rystic/scenario, GET /_rystic/scenarios, rystic describe <product>, rystic docs <product> scenarios. Scenarios and seeding → Named scenarios.
Network profile
Per-endpoint latency and rejections a simulator applies to its vendor routes, on Pro and Enterprise (the faults feature).
Where: /_rystic/network, RYSTIC_NETWORK, rystic run --network, the state UI’s Network card. Network profiles and fault injection.
Provider action
Something the simulated provider does on its own, not in reply to your request, such as a Resend bounce, a Stripe dispute, a Lob tracking scan or a Kalshi settlement.
Where: control routes such as POST /_dispute, POST /_bounce, POST /_tracking_event and POST /_settle, a timeline event, and GET /_rystic/egress for any event it emits. Webhooks → Provider actions.
Register
One kind of record in a simulator’s state, such as state_customer or state_address, keyed by its key_fields.
Where: GET /_rystic/registers, GET /_rystic/inspect (keyed by register), the body of POST /_rystic/seed, rystic describe <product>, the state UI’s Store card. Scenarios and seeding → Registers.
Reset
Clearing a simulator’s state without a restart and reseeding its built-in records: every register cleared, id sequences and the egress log restarted, the clock back at initial_clock.
Where: POST /_rystic/reset, the state UI’s Reset button. Reset and determinism.
Scenario
One configuration of an environment: its starting state (a named scenario, seeds or both), the timeline events it preloads and its network behavior.
Where: rystic run --scenario, RYSTIC_SCENARIO, the scenario: key in rystic.yaml, POST /_rystic/scenario, GET /_rystic/scenarios, SCENARIOS.md. Kalshi’s rate_limited, brownout_503 and flaky_500 scenarios carry their own faults. Scenarios and seeding.
Scenario file
A JSON file holding a register map under seed, beside optional clock, rng_seed, network, credentials and events: a scenario of your own.
Where: POST /_rystic/seed, rystic run --seed <file>, RYSTIC_SEED; errors call it a world document, as in keys a world document does not take. Scenarios and seeding → Two shapes.
Seed
Records you land directly in a simulator’s registers without calling its API; a seed merges into what the simulator already holds.
Where: POST /_rystic/seed, rystic run --seed <file>, RYSTIC_SEED; not the RNG seed, which POST /_rystic/seed-rng pins. Scenarios and seeding → Seeding.
Simulator
A local, stateful stand-in for a third-party API: one binary that serves the vendor’s routes on localhost, holds state between requests and models the vendor’s lifecycle, conflict and error paths.
Where: rystic run <product>, rystic ps, registry.rystic.ai/<product>. Installation.
State UI
The browser view every simulator embeds on every plan, with cards for its live activity, its state register by register, its egress log and its network profile.
Where: http://localhost:$PORT/_rystic/ui. Observing → The state UI.
Tape
A captured Kalshi market day that the Kalshi simulator replays, moving its markets and its clock with the tape.
Where: rystic run kalshi-twin --tape, /_replay/*, rystic batch. Kalshi → Replay.
Timeline
A schedule of events a simulator fires as its clock passes them: a scenario’s own events, or a schedule posted to /_rystic/inject or loaded with --inject.
Where: POST /_rystic/inject, GET /_rystic/inject, rystic run --inject. Control plane and plans → Timelines.
Twin
The word “twin” appears in product and package names, such as stripe-twin and rystic pull lob-twin, and the CLI’s help text and reference also use it for a simulator.
Where: rystic pull <name>-twin, registry.rystic.ai/<name>-twin, ~/.rystic/twins/, the CLI flag reference.
Verified UI
A client app built against the service’s real UI and checked against it, shipped as its own image beside the simulator’s, on Pro and Enterprise.
Where: rystic ui <simulator>, registry.rystic.ai/<simulator>-ui:<ver>. Plans and API keys.