Concepts
Digital twins
A Blobfish service twin is a stateful, deterministic replica of a production service — Slack, Stripe, GitHub, Attio, Trolley — that your agent can read from, write to, break, and reset without a production consequence. A twin is not a recording and not a stub: every mounted operation executes against the twin’s own seeded SQLite state, so a record created in one call is there in the next, a guarded lifecycle rejects an illegal transition the way the real service does, and two runs from the same seed see the same world.
Why twins beat the alternatives
| Approach | Stateful | Behavioral | Deterministic | Safe |
|---|---|---|---|---|
| Real service | yes | yes | no | no |
| Static mocks | no | no | yes | yes |
| Service twins | yes | yes | yes | yes |
The fidelity ladder — and what we refuse to fake
Every twin declares which runtime backs it, and the console shows the rung on its card:
- First-party IR— a vendored, spec-grounded model of the vendor’s API (entities, operations, guarded lifecycles), proven by an executable scenario battery before it ships. Tier labels:
captured API,docs-transcribed,domain twin,spec-grounded. - Captured contract — a pinned, captured MCP-server contract (for example Attio via
sm--attio) rekeyed onto seeded state. The tool surface is exactly what was captured. - Roadmap — named, not mounted, and never pretended.
One deliberate difference from stub-based emulators: an operation outside a twin’s surface is not mounted at all — it does not answer with schema-shaped filler. We mount fewer, real operations rather than let a test pass against an endpoint that was never implemented. What a twin cannot do is written on its page as Known limitations, straight from the spec’s own fidelity record.
Determinism, sessions, reset
- Seeded state — every twin starts from a deterministic seed (
<service>-seed-1); reads are state-hash invariant, writes produce inspectable row-level diffs. - Copy-on-write sessions — create a session with your API key and pass
x-blobfish-session; each session forks the state so parallel rollouts can never contaminate each other. - Reset — one call restores the seed baseline, per service, per session or for the shared world.
Surfaces
One environment serves the same state through vendor-shaped REST (per-operation routes), MCP (a world-level endpoint plus one per service, for tool-calling agents), a generated CLI (bf-twin, synthesized from the environment’s own specs), and — for first-party twins — a live explorer UI where you browse state, run operations, and watch diffs.
19 twins ship API + UI; 9 are API-only. The full list with per-twin runtimes is in the twin reference.
Next
Twins quickstart — key to running environment in about a minute · Local testing — point a local app at hosted twins · Custom scenarios — seed the state your test needs.