Skip to content
WonderTwin docs

Integrating WonderTwin

This guide walks the lifecycle of bringing WonderTwin into your application: getting twins running on your laptop, wiring your app to talk to them in dev, moving to hosted staging, running them in CI, and the bright line at production.

Audience: engineers integrating WonderTwin into an existing codebase. Pre-reqs: you’ve installed the wt CLI and know which external services your application talks to.

The substitution model

Section titled “The substitution model”

WonderTwin substitution model — twins replace external services in dev and staging; production talks to real services directly

WonderTwin is an environment-specific layer, not a permanent dependency:

  • Dev (local) and staging (CI / hosted non-prod) — your agents talk to WonderTwins; the WonderTwin Stack (Registry · Runtime · Telemetry) sits between your code and the external-services boundary.
  • Production — that entire layer is removed. Your software and your agents talk to real external services directly, the same way they would in a world without WonderTwin.

The substitution is layer-level, not endpoint-level. You don’t twin some calls and leave others real within the same environment; you either have the twin layer (dev/staging) or you don’t (production).

The bright line: twins are never used in production. WonderTwin’s SLAs, durability, and operational posture are dev-grade by design. Routing production traffic through a twin is unsupported and explicitly not approved. See prod-no-twins.md for the production-safety check that enforces this in your build.

Reading order

Section titled “Reading order”
  1. Running twins locally — get a single twin running on your machine
  2. Running your app against local twins — wire your application code to talk to the local twin instead of the real vendor in dev
  3. Running twins in hosted non-prod environments — staging / preview / shared dev hosts
  4. Running twins in CI — twinning external services on CI runners
  5. Running against production services (no twins) — the bright line and how to enforce it in your build
Section titled “Related”
  • ECOSYSTEM.md — map of WonderTwin repos and how they connect
  • guides/ci/ — general CI strategy patterns (this guide layers on top for the twin-specific bits)
  • adr/ — architectural decisions behind the twin runtime and registry