Installation

Run a simulator on your machine and point your app, your tests or your agent at localhost. Same state every run.

Running an agent with Slack MCP in Harbor? Start with Slack MCP in Harbor for the licensed environment image, tool connection and episode reset. The standalone installation below is for HTTP API clients.

New to the words these pages use? The Glossary defines each one, from simulator, environment and scenario to seed and register, in a sentence.

What you need

1. Mac or Linux, 64-bit. (Windows: zip on request.)
2. A Rystic account. The install signs you in through the browser; sign up there with GitHub or Google and a new account starts on Free, 10 hours a month. Plans and API keys explains the plans.
3. A network connection while a simulator runs: it checks in with Rystic. Docker only if you want containers later.

Enterprise, with a license file or install link instead? See Enterprise: license files.

Install

curl -fsSL https://www.rystic.ai/install.sh | sh

The install ends by running rystic login. It opens your browser on www.rystic.ai , or prints a link and a code on a headless or SSH machine. Sign up or sign in, check the code, click Approve; a new account gets an organization on Free. The CLI stores a Free API key that does not expire.

installed rystic 0.0.34 → /usr/local/bin/rystic     # or ~/.local/bin; RYSTIC_BIN overrides
to sign in, open: https://www.rystic.ai/device?...
confirm the code on the page reads ABCD-1234 — waiting for approval (Ctrl-C to stop)
approved · Free plan

RYSTIC_NO_LOGIN=1 skips the login step; run rystic login later.

Without a browser: CI and agents

Create an API key and sign the CLI in with it:

rystic login rys_…

rystic login --token-stdin < key.txt keeps the key out of your shell history. Success ends like this:

signed in: the API key is stored in /Users/you/.rystic/token
docker login registry.rystic.ai: ok — `docker pull registry.rystic.ai/<product>:<version>` and `rystic run --runner docker` now work
next: rystic run <product>  ·  rystic docs

The key is stored in ~/.rystic/token, readable by you only, and never printed. If Docker isn’t running, the last line says skipped and names the command to run later; the native runner doesn’t need it.

Check everything

rystic doctor stripe-twin

Every ✗ is followed by a → line with the command that fixes it. ! is a warning, not a failure. Before your first pull, ✗ install no installed version is normal — the first run pulls for you.

doctor checks your API key first: ✓ api key names the organization and plan it belongs to. ✗ api key plan means your plan leaves that simulator out; a refused key exits 11 with the same message rystic pull prints.

First run

rystic run stripe-twin

stripe-twin 0.0.18 (model 95c5dbcd) → http://localhost:8080  [native default]

That line is the simulator’s identity: version, model hash, URL, runner. On an Enterprise license it also names the licensee and expiry. Port is 8080 unless you say otherwise; --port 0 takes a free one and prints it. Ctrl-C stops it.

In the background:

rystic run stripe-twin -d --name dev --port 0
rystic ps
rystic stop dev

Make a first request

Second terminal — create a charge, refund it, read both back:

CH=$(curl -s localhost:8080/v1/charges -u sk_test_twin: \
  -d amount=2000 -d currency=usd -d source=tok_visa | jq -r .id)
# -> ch_…

curl -s localhost:8080/v1/refunds -u sk_test_twin: -d charge=$CH

curl -s localhost:8080/v1/charges/$CH -u sk_test_twin:
# -> "refunded": true, "amount_refunded": 2000

curl -s 'localhost:8080/_rystic/egress?tail=5'
# -> charge.succeeded, refund.created, charge.refunded, … — the webhooks it would have sent

Any Authorization header works, and none of your requests leave your machine. Point your SDK’s base URL at http://localhost:8080 and your existing code runs unchanged — each simulator page shows the one-line client change.

Start from a named scenario

Every simulator ships named scenarios compiled into the binary — no data files, no network.

A simulator boots empty unless you name a scenario, and reset clears state and reseeds the simulator’s built-in records, the state it boots in without one. Stripe’s scenario is design_studio: Website Design Contractors’ account, 30 customers and 269 charges since November 2024. The same studio is on Lob, PayPal, Resend and Slack. Naming a scenario boots the same state on every plan:

rystic run stripe-twin --scenario design_studio

GitHub and Kalshi ship more scenarios; GET /_rystic/scenarios lists them with a one-line summary each, and the binary’s --list-scenarios prints the same menu. A running simulator takes a scenario without a restart. This resets state, applies the scenario, answers 204:

curl -X POST localhost:8080/_rystic/scenario \
  -H 'content-type: application/json' -d '{"name":"design_studio"}'

The same call works on every simulator; only the scenario names differ. The Kalshi simulator holds no markets until you give it some, so a trading bot needs a scenario before it can place an order — see Kalshi simulator. Control plane and plans has what a simulator boots and what reset keeps.

Next

1. Agent quick start — hand the simulator to a coding agent.
2. Docker builder — pick your simulators and copy a ready rystic.yaml, CLI lines and Compose file.
3. The rystic CLI — every command, flag, exit code.
4. Control plane and plans — every /_rystic route and the plan that serves it.
5. Docker — the same simulator as a container; your API key is the credential.
6. Integration tests in CI — the simulator as a GitHub Actions service container.

If it didn’t work

Stuck anyway? Send us rystic doctor output — it names the broken piece without revealing your key.