Rystic

Move the instance's clock by whole seconds, forward or (negative) back: give seconds or duration, exactly one. Events fire as the clock passes them. Returns the clock the twin then reads.

Grade the instance's run since its baseline against a saved test case's checks, as `rystic grade` does, with no model: capture the run as save_test_case does, with the twin's event timeline as world.json, into a new grid cell dir holding the case's eval, grade it, and write its verdict.json. case is the cell_dir or eval path save_test_case returned, or any eval file; a case dir's checks/ YAML files are graded too. The case's world must name exactly the instances' twins, by twin name or by grid name (the twin name without -twin). Returns result (pass, fail, error, or incomplete when every graded check passed but one was skipped), reason, cell_dir, notes, and per check its id (nothing_destructive, checks[i] in eval order, then checks/<file>[j]), result (pass, fail, error or skipped), detail and, for a failure, the rows behind it. A script check is skipped, never run. To check a new run, reset or load_scenario the instance, run the agent, then call this.

Compare the instance's state now with its baseline, the state it had when start_twin started it, load_scenario loaded a scenario or reset cleared it: rows created, changed (each changed field's JSON Pointer path, before and after) and deleted, per resource. register narrows it to one register. counts cover every row that differs (in register, when given); resources holds a page of them, in resource, then created, changed and deleted, then key order. concise (the default) gives created and deleted rows with string values over 256 bytes cut, and changed rows as their fields; detailed adds each changed row's state and cuts only a row over 12 KB. A cut row is marked truncated. A page holds at most limit rows and about 20 KB. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest. An instance with no baseline (started outside this server) gets one on the first call, which answers baseline first_seen and an empty diff.

Return the instance's state (GET /_rystic/inspect) a page at a time: state is resource, then row key, then row, in key order. register narrows it to one register, and key with it to one row; matched counts the rows they match. concise (the default) cuts string values over 256 bytes and lists those rows in cut_rows; detailed cuts only a row over 12 KB. A page holds at most limit rows and about 20 KB. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest. A state larger than one page also carries state_uri, a resource link to the whole state uncut. view asks for one of the twin's named views instead, such as identities, answered as {view, result}; a view that is a file, or larger than a page, comes back as its size and the URL to fetch it from.

List the API calls the instance served since its last reset (GET /_rystic/calls), oldest first, a page at a time; method, path_prefix, status and actor filter them. concise (the default) gives each call's seq, at, method, path, status and actor; detailed gives the twin's whole record. total counts every call since the reset, matched the kept calls the filters match. A page holds at most limit calls and about 20 KB. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest.

List the named starting worlds the instance's twin ships (GET /_rystic/scenarios), each with a summary.

List what the instance sent since its last reset: webhooks, emails and other outbound effects (GET /_rystic/egress), oldest first, a page at a time. Each event names its effect and type as the twin's model calls them; no field marks a webhook apart from an email, so filter on effect or type. concise (the default) gives each event's seq, effect, type and owner; detailed adds the payload. delivery, when present, sums up webhook delivery with its newest 20 attempts in results (results_total counts the attempts the twin reports). total counts every event since the reset, matched the kept events the filters match. A page holds at most limit events and about 20 KB, and an event over 12 KB is cut and marked truncated. When more remain, next_cursor reads the next page; whenever anything is cut, truncated is true and hint names the call that gets the rest.

List the twin instances running on this machine: each one's name, twin, version, URL, runner and status from a live probe. Call it first to find the instance the other tools take.

Replace the instance's state with a named scenario, keeping the twin's built-in records (POST /_rystic/scenario). The loaded state becomes diff_state's baseline.

Reset the instance to the twin's built-in records, dropping scenario and seeded state (POST /_rystic/reset), clearing its calls and sent log. The reset state becomes diff_state's baseline.

Roll the instance back to a snapshot snapshot_twin saved: reset it, then land the snapshot's state, clock, id counters, pending scheduled events and network shaping, so ids minted after the restore continue where the snapshot left off. The restored state becomes diff_state's baseline. A snapshot taken on another version of the twin is refused. On a twin release older than the seed round trip, which holds no id counters, every result carries a warning: ids minted after the restore can collide with restored records, and per-account records can come back duplicated. A snapshot does not hold, so a restore does not bring back: the idempotency cache (a replayed request makes a new object), the request-id counter, the calls and sent logs (they start empty), the webhook delivery queue, credential bindings, upload sessions, the rate limiter, the clock's wall offset, scheduled events in full (only the pending events of the world's own schedule come back; one that uses a value a fired event bound is dropped, and a schedule loaded on its own replays from its start), built-in records deleted before the save (the reset brings them back), and whether a scenario installed the network shaping (once landed, the shaping stays through later resets). A pending default-actor call on a route that needs a credential binding fails the restore after the reset, which leaves the instance reset.

Save the instance's run since its baseline as a test case: write a grid cell dir (before is diff_state's baseline, after the state now, with the calls and sent log since the last reset) and draft an eval from it with `rystic grade --draft`. The draft expects each row the run created or changed, forbids any other creation, change, call actor or method, and allow_deletes each row it deleted; the saved cell passes it. The state after the last seed through this server since the baseline is the run's before, so seeded rows are setup, not the run's; rows a scenario timeline event seeds during the run count as the run's. Returns the draft YAML and cell_dir, whose eval.yaml holds the draft, so `rystic grade <cell_dir>` passes. Trim the checks to what the task requires before keeping them. An instance with no baseline is refused: reset, load_scenario or diff_state it before the run.

Save the instance's state as a scenario file at file, the scenario document `rystic run --seed <file>` boots and POST /_rystic/seed lands, so a teammate, a CI job or a later run starts a twin in this state. It holds what snapshot_twin holds: the whole state, the clock, the id counters, the pending scheduled events and, when your plan includes network shaping and a profile is installed, that shaping. The file names the twin but no instance, version or model hash; a twin release that cannot take a record refuses the load and lists the records. An existing file, a symlink included, is refused unless force is true, which replaces the file or writes through the symlink. New files are private to your user; replacing a file preserves its permissions. It refuses a pending event that acts as a named caller and a scenario too large for the seed route to take back. On a twin release older than the seed round trip, which holds no id counters, the result carries a warning: ids minted after a load can collide with loaded records. The file does not hold, so loading it does not bring back: the idempotency cache (a replayed request makes a new object), the request-id counter, the calls and sent logs (they start empty), the webhook delivery queue, credential bindings, upload sessions, the rate limiter, the clock's wall offset, scheduled events in full (only the pending events of the world's own schedule come back; one that uses a value a fired event bound is dropped, and a schedule loaded on its own replays from its start), built-in records deleted before the save (the reset brings them back), and whether a scenario installed the network shaping (once landed, the shaping stays through later resets). It holds no rng_seed and no credentials either, which the twin does not expose; add those keys to the file by hand when a run needs them. A pending default-actor call on a route that needs a credential binding fails the load.

Merge records into the instance's state (POST /_rystic/seed). body is {register: {key: {field: value}}}; `rystic describe <twin> -json` shows each register with an example record. Seeding leaves diff_state's baseline where it is, so seeded rows read as created; save_test_case reads the seeded state as the run's starting state instead.

Pin the instance's clock to an RFC3339 instant (POST /_rystic/clock); events due by then fire. Returns the clock the twin then reads.

Sign in to Rystic, or sign up, in the browser, so start_twin can download twins: call it when a tool fails with license_or_lease. The first call returns a URL and a code at once; show both to the user, who opens the URL, checks that the page shows the same code and approves. Then call sign_in again: it answers pending until the user has approved, then stores the API key where `rystic login` stores it and answers signed_in. A link lasts 15 minutes; a call after that returns a new one. The API key never appears in a result.

Save the instance's world under name, so restore_twin can roll back to it: try one path, roll back, try another. It holds the whole state, never a page,, the clock, the id counters, the pending scheduled events and, when your plan includes network shaping, that shaping. This CLI stores it per instance; it outlives a restart of the instance on the same twin version. A snapshot of the same name is replaced, and the result says so. Omit name to list the instance's snapshots. It refuses a pending event that acts as a named caller (a restore cannot rebind its credential) and a world too large for the seed route to take back. A snapshot does not hold, so a restore does not bring back: the idempotency cache (a replayed request makes a new object), the request-id counter, the calls and sent logs (they start empty), the webhook delivery queue, credential bindings, upload sessions, the rate limiter, the clock's wall offset, scheduled events in full (only the pending events of the world's own schedule come back; one that uses a value a fired event bound is dropped, and a schedule loaded on its own replays from its start), built-in records deleted before the save (the reset brings them back), and whether a scenario installed the network shaping (once landed, the shaping stays through later resets). A pending default-actor call on a route that needs a credential binding fails the restore after the reset, which leaves the instance reset.

Start a twin in the background, as `rystic run <twin> -d` does, and return its instance name and URL; point the code under test at the URL. A twin that is not installed is pulled first, as `rystic run` pulls one, which can take a minute; a call that carries a progressToken gets the download as notifications/progress, and cancelling the call stops the pull and any twin it started. It takes a free port unless port is given, and stores the state it boots into as diff_state's baseline. The twin keeps running after this server exits; stop_twin ends it.

Stop a running instance and remove its record and diff baseline, as `rystic stop` does.