docs · observability
The dashboard
Every stunt up serves its own localhost dashboard — no daemon, no IPC; it reads the server's in-process state directly. A real-time request inspector, a state browser for what your tests created, snapshot/restore for deterministic runs, and a multi-instance manager. Every command has --json for agents & CI.
$ stunt up$ stunt ui # open it$ stunt requests --follow # live feed in the terminalRequest inspector
A real-time feed of every request hitting your sims — REST, gRPC, and WebSocket — with method, path, status, and sub-microsecond timing.
Each row records a monotonic sequence number, timestamp, service, transport, method, path, status, and duration, plus the request/response headers and bodies. The feed is live (WebSocket push) and gap-free on reconnect — drop a connection, reconnect, and the server backfills anything you missed.
Filter instantly by service, method, status, or free-text on the path. Click any row for full detail — redacted headers, bodies, copy-as-curl, and replay (re-issues the request against current state).
stunt requests- captured requests (table)
stunt requests --json- machine-readable (agents / jq)
stunt requests --follow- live stream — like tail -f
stunt replay <id>- re-issue a request against current state
State browser
stunt's defining property is stateful simulation — your POSTs create data the sim remembers. The state browser answers the #1 debugging question: did my POST create the right state?
Browse, read-only, the three backing stores per service: collections (SQLite documents, with live counts), kv (namespaced pairs), and blobs (uploaded files). Drill into a collection to inspect the actual documents — it reflects exactly what the sim will return on the next read.
stunt state collections <svc>- list collections (+ counts)
stunt state collection <svc> <name>- list documents in a collection
stunt state kv <svc> [--ns <ns>]- kv namespaces, or pairs in --ns
stunt state blobs <svc> [--ns <ns>]- uploaded blobs
Snapshot, restore & reset
Non-determinism is the enemy of reliable tests. Capture a known-good state, run a flaky test against it, then restore the exact pre-test state — so reruns are reproducible.
A snapshot is a portable .tar.gz of a logical dump (collections + kv + blobs, not a raw DB copy), so it survives layout changes and is debuggable as JSON. Restore wipes current state and re-seeds through the real primitives. The request log is not snapshotted — it's observational, not sim state.
Instance manager
Running more than one server? The global registry tracks every running stunt across all manifests; stunt ps lists them and dead entries self-prune.
stunt ps shows PID, mode, age, manifest, and dashboard for every running server. stunt stop gracefully shuts one down (SIGTERM → SIGKILL). The dashboard's instances tab lists the same servers and lets you jump to another instance's dashboard or stop it.
stunt ps [--json]- list running servers across all manifests
stunt stop [<pid>]- stop one (by PID, or the current manifest’s)
stunt down- stop the current manifest’s server
Localhost-only, by design
The admin server binds loopback only, requires a random session token on every request, and rejects non-localhost Host headers as a DNS-rebinding defense. Sensitive headers are redacted before they're stored; bodies are on by default (the killer feature for a dev tool you chose to send these requests to). Logging is async — a parked dashboard tab never backpressures your sims.
Go deeper
The exhaustive reference — every flag, the architecture (embedded per-server, hot-path safety, state layout), full security reasoning, common workflows, and troubleshooting — lives in the repo: