recorded-traffic API mocking

API mocks from
real traffic,
verified.

Wraith records your app's calls to third-party APIs, synthesizes a fast local mock, and checks the twin against the original recordings. Deterministic, stateful, and proven against the real thing. Build CI, demos, and agents against a dependable service, not hand-written stubs.

quickstart install notes [email protected]
install 
curl -fsSL https://wraith.cx/install.sh | sh

Local-first CLI. Checksum verified. Prebuilt binaries for Linux x86_64 and macOS Apple silicon. Latest release: v0.9.0 — overlay support. Pin a version with WRAITH_VERSION.

100% corpus conformance
23 recorded service twins
9,040 verified exchanges
1,754 routes, 1,878 variants
network · init
Wraith records real API traffic and serves a verified local twin A product workflow diagram showing your app sending requests through Wraith to a real API, then Wraith synthesizing and serving a deterministic local twin. YOUR APP :3000 REC wraith :8080 REAL API api.example.com TWIN deterministic :8081 · 0ms GET /users POST /pay GET /order/7 GET /users SCAFFOLDING TWIN twins/myapi/ SCHEMA ROUTES User12 f Order8 f Payment14 f Session6 f Webhook9 f Refund7 f Invoice11 f GET/users/:id GET/users POST/users GET/orders/:id POST/orders POST/payments DEL/sessions/:id PATCH/refunds/:id CONFORMANCE · 4/4 SESSIONS · EXIT 0 ◆ deterministic ◆ stateful ◆ 0ms p50 ◆ 100% PHASE 00 · INIT scaffold created · ready to record
§01 · loop

Five commands. Traffic replay to twin.

~/projects/myapi · zsh 80×24
§02 · fidelity

A twin that proves it matches.

conformance report • pass
github-actions · 4 sessions · 247 exchanges
GET /repos/:owner/:repo100.0%
GET /repos/:o/:r/commits/:sha100.0%
POST /repos/:o/:r/statuses/:sha99.2% · 2 suppressed
GET /user100.0%
GET /rate_limit100.0%
✓ 4/4 sessions passed · exit 0

Every mock library ships a promise. Wraith ships a proof. Every exchange you recorded is replayed through the synthesized model and compared with a semantic diff.

Divergences are categorized, counted, and either suppressed intentionally or fail the build. The twin isn't a sketch of your API. It's an assertion.

  • 01
    Anti-unification
    Finds the shared shape across all responses. Constants stay constant. Variables get classified by how they're sourced.
  • 02
    Hole classification
    Echoed from request? Generated ID? Timestamp? Counter? Each variable field gets a resolver the state engine understands.
  • 03
    Semantic diff
    Type mismatches, missing fields, and value drift are categorized and scored. Suppress what's expected. Fail the rest.
§03 · surface

Built for the messy shape of real services.

  • /01

    Stateful CRUD, free

    The synth stage detects create/read/update/delete on entities. POST then GET returns what you POSTed. Generated IDs stay consistent across routes.

    STATE · inferred
  • /02

    3-layer scrubbing

    Secrets are removed before anything hits disk. Header redaction, body pattern matching, and pluggable rules per twin. Your recording never contains tokens.

    SCRUB · pre-write
  • /03

    Deterministic playback

    Same request, same response. Counters, pseudo-random generators, and time all seed from request context. Your flaky integration test isn't flaky anymore.

    DETERMINISTIC · seeded
  • /04

    Lua escape hatches

    When inference isn't enough, write a handler. Sandboxed, hot-reloaded, with access to request/response/state. Ten lines to make the twin behave exactly right.

    HOOKS · per-route
  • /05

    Fail like production

    Inject errors, delays, timeouts, and 429s. Rate-limit by route. All deterministic from a single seed, so the same run gets the same failures every time.

    CHAOS · deterministic
  • /06

    Machine-readable everything

    Every command emits JSON on demand. Reports, diffs, symbols, state. Drop wraith into CI and let your pipeline reason about it.

    OUTPUT · --format json
  • REST
    shipped
    JSON bodies, path params, query routing, RFC 7807 errors.
  • GraphQL
    shipped
    Operation-aware capture, field selection replay, variables-as-holes.
  • gRPC
    shipped
    Unary + server-streaming RPCs. Live frame forwarding, byte-preserving replay, HTTP/2 trailers.
  • SSE
    shipped
    Per-event timing replay, hole rotation, suffix anchoring on terminal sentinels. WebSocket on the roadmap.
§04 · use

Why a twin, not a mock.

  • FOR AGENTS

    A service they can drive, not simulate.

    Agents do better when the environment behaves. Twins give them a loop they can trust: every POST persists, every GET returns, and rate limits fire when they should.

  • FOR TESTS

    CI that doesn't flake.

    Point tests at localhost. No rate limits, no auth dance, no shared sandbox stepping on your fixtures. Millisecond replies, every time, forever.

  • FOR DEMOS

    An offline copy that still feels alive.

    Ship a twin with the demo. It's small, deterministic, and behaves like the real thing. Conference wifi has never been a problem again.

§05 · fit

Built for local twins, not every mock job.

  • Use Wraith when the real API behavior matters. Record traffic from Stripe-style, GitHub-style, GraphQL, gRPC, or SSE services, then run the verified API mock locally in CI, demos, or agent loops.
  • Do not use Wraith for a hand-authored mock UI. If you only need a static example response, a simpler API mocking tool or Postman collection may be the better fit.
  • Do not treat it as hosted production traffic replay. Wraith is local-first service virtualization for development and tests, not a managed observability or production replay platform.
  • Check protocol boundaries before a rollout. REST, GraphQL, gRPC unary/server-streaming, and SSE are shipped. WebSocket and pure bidirectional streaming remain outside the current fit.

Give your code a service
it can actually trust.

Five commands between you and a recorded-traffic mock that's been proven correct against the API it shadows.

read the quickstart email [email protected]