Developer documentation

Quickstart

Mint an API key with Rig scopes in the Ironfang portal, then commit an ironfang.rig.yaml beside the application. The file declares the external identities a run needs and what the run must observe.

version: 1
project: acme-shop
suite: checkout
name: Checkout flow
defaults:
  run_ttl: 30m
resources:
  customer_email:
    type: email
  stripe_callback:
    type: callback
    connector:
      route: stripe
  shipping_api:
    type: mock_http
    rules:
      - match: { method: POST, path: /v1/ship/* }
        respond: { status: 201, json: { tracking: "IF-1" } }
expectations:
  - id: order_email
    resource: customer_email
    event: email.received
    match: { subject_contains: "Your order" }
  - id: stripe_forwarded
    resource: stripe_callback
    event: connector.request.completed
    match: { outcome: delivered, status: 200 }

The command line client syncs the file, starts a run, exports each resource's address to the command after --, runs it, and finishes the run with a verdict.

export IRONFANG_API_KEY=if_live_...
ironfang-rig run -- npm test

# In the test process:
#   IRONFANG_RIG_RUN_ID           the run
#   IRONFANG_RIG_CUSTOMER_EMAIL   run-....@inbox.rig.ironfang.uk
#   IRONFANG_RIG_STRIPE_CALLBACK  https://hooks.rig.ironfang.uk/h/...
#   IRONFANG_RIG_SHIPPING_API     https://mock.rig.ironfang.uk/m/...

The same run is available over HTTP. Every request carries the key as a bearer token and the base URL is https://api.ironfang.uk/rig.

curl -X POST https://api.ironfang.uk/rig/v1/suites/$SUITE_ID/runs \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "ttl": "30m", "external_id": "ci-4821" }'

The complete OpenAPI 3.1 description is served at https://api.ironfang.uk/rig/openapi.yaml.

Model

Suites persist, runs are disposable, resources have explicit lifetimes. Nothing here runs your code: Ironfang Rig is the outside world your tests talk to and the record of what it saw.

Everything is organisation-bound. An object that belongs to another organisation is reported as not found, never as forbidden.

API keys and scopes

Platform API keys are minted in the portal and start with if_live_. A key's scopes are its permissions and it acts only in the organisation it was minted for. Send it as a bearer token.

Authorization: Bearer if_live_...

• rig:readList and read projects, suites, runs, resources, faults, connectors and events; wait on the timeline; export evidence
• rig:writeCreate and revise projects and suites
• rig:runStart, finish and cancel runs; allocate resources; change mock rules; arm faults; replay callbacks
• rig:connectorMint connectors and their bootstrap tokens
• rig:*All of the above

A Warden user token is accepted as well, with the acting organisation in X-Ironfang-Tenant; each route then needs the matching tenant permission (rig.read, rig.write, rig.run, rig.connector).

Errors

Every error is a JSON object with a stable code, a message for people and the request id to quote to support.

{
  "error": { "code": "run_not_active", "message": "the run has already ended" },
  "request_id": "..."
}

The suite file

ironfang.rig.yaml lives in the repository beside the application it tests. It carries exactly the definition the API stores, so what a developer commits is what a run is created from. Syncing the file creates the project and suite on first use and records a new suite version whenever the definition changes.

Resource specs

Route labels match ^[a-z0-9][a-z0-9-]{0,62}$. The platform only ever names a label; what it points at is decided on the connector's command line and never leaves your machine.

Matching

A match object is a set of conditions on the top-level fields of an event's data, and every key must hold. A plain key compares as JSON, so numbers, booleans, strings and whole objects compare by value. A key ending in _contains requires the field to be a string containing the value. The same rule evaluates suite expectations, the wait endpoint and the CLI's --match, so a condition means one thing everywhere. Up to 16 keys, 4096 characters each.

Resources

Starting a run allocates every declared resource. Each one is unguessable, belongs to this run alone, and stops accepting activity when the run ends. More can be allocated on an active run with POST /v1/runs/{runId}/resources.

Email inboxes

An email resource is an address such as run-k7c3m2wp9e4q5r6t@inbox.rig.ironfang.uk. Mail for it is received by mx.rig.ironfang.uk, parsed, and recorded as email.received with the sender, recipient, subject, links, verification codes, attachments and transport details. The raw message is kept as the event's payload. Messages up to 10 MiB and 500 messages per run are accepted; anything more is refused at SMTP time so the sender sees the bounce.

Callback URLs

A callback resource is a URL such as https://hooks.rig.ironfang.uk/h/.... Any method and any path beneath it are accepted. The request is recorded as callback.received with its method, path, query, content type, byte length and SHA-256, and the sender gets a 200 with the event id at once. The exact bytes are available from the event's payload endpoint. Bodies over 64 KiB are refused with 413 and recorded as callback.rejected; a run accepts up to 1000 callbacks.

{ "received": true, "run_id": "...", "event_id": "...", "sequence": 7 }

With a connector.route, every recorded request is also queued for that route and forwarded through your connector; see Local connector.

Mock HTTP endpoints

A mock_http resource is a base URL such as https://mock.rig.ironfang.uk/m/.... Requests beneath it are answered by the first rule whose match holds; no match answers 404 with code no_mock_rule. Each request is recorded as mock.request.received and its answer as mock.response.sent with the rule that matched. Rules can be replaced while the run is active with PUT /v1/runs/{runId}/resources/{resourceId}/mock, which records mock.rules.updated.

Deterministic: the same request against the same rules gets the same answer, delay included. A run may make up to 5000 mock calls.

Connector routes

A connector_route has no public address. It exists so a connector can bind the label and so callbacks can name it. Most suites declare the route on the callback itself and never need a separate resource.

Timeline and waiting

GET /v1/runs/{runId}/events?since=0&limit=100 returns the run's events in sequence order after since, up to 500 at a time, with next_since to continue. Sequences are contiguous from 1 and never change, so the same request always returns the same events. Payloads larger than an event carries are referenced by blob_ref, never embedded.

{
  "id": "...",
  "run_id": "...",
  "resource_id": "...",
  "type": "callback.received",
  "sequence": 7,
  "occurred_at": "2026-09-19T09:14:02.118Z",
  "data": {
    "resource": "stripe_callback",
    "method": "POST",
    "path": "/",
    "content_type": "application/json",
    "byte_length": 812,
    "sha256": "..."
  }
}

POST /v1/runs/{runId}/wait blocks until an event after since matches, or the timeout passes. The wait reads the timeline first, so an event that already happened is answered at once, then wakes as new events land.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/wait \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "email.received",
    "resource": "customer_email",
    "match": { "subject_contains": "Your order" },
    "since": 0,
    "timeout": "30s"
  }'

A timeout is a 200 with matched: false, never an error: nothing went wrong, the thing has not happened yet, and next_since says where to continue. Timeouts run from 1 to 90 seconds (default 30); loop with next_since for longer. Deterministic: the same timeline and request always answer the same event. At most 16 waits per organisation may be open at once.

Payloads

GET /v1/runs/{runId}/events/{eventId}/payload returns the exact bytes a callback or message carried, as an opaque attachment whatever the sender declared, so third-party content is never rendered on the API origin. The declared media type is in X-Ironfang-Payload-Media-Type and the SHA-256 in X-Ironfang-Payload-SHA256. Payload bytes are kept for 7 days after the run ends; after that the event remains and the endpoint answers 410.

Event catalogue

Every type an expectation or a wait can name, with the data fields a match can address. All events also carry resource (the declared name) where one applies.

Local connector

A callback with a connector.route is forwarded to an application on your machine or CI runner without opening an inbound port. The ironfang-connect binary dials the gateway at wss://connect.rig.ironfang.uk/v1/connect, binds route labels, and makes each forwarded request against the local target you gave for that label. The local result travels back and is recorded as connector.request.completed.

Mint a connector on an active run. The response carries a single-use bootstrap token that expires after ten minutes, the gateway URL and the command line to complete. The token appears here and nowhere else.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/connectors \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-runner-3", "routes": ["stripe"] }'

# Then, with the token in the environment rather than an argument:
IRONFANG_CONNECT_TOKEN=ift_boot_... ironfang-connect \
  --route stripe=http://127.0.0.1:8080/webhooks/stripe

The connector exchanges the bootstrap token for a session credential bound to this organisation, this run and these routes, which lives no longer than the run. Deliveries for a route wait until a connector holds it, then arrive in order, each with a 30 second local timeout; the result the connector reports is final. A connector that drops mid-run resumes on its session credential, and deliveries it had not answered are requeued for the next session with their attempt count raised. GET /v1/runs/{runId}/connectors reports each connector's state and how many deliveries are still waiting. A run may have up to 16 connectors.

Forwarded requests carry the original method, path, query, headers and body, plus X-Ironfang-Delivery-ID, X-Ironfang-Event-ID and X-Ironfang-Route, so the application can tell a replay or duplicate from a first delivery. Frames are bounded at 256 KiB.

Faults

A fault is deterministic interference armed on one resource of an active run with POST /v1/runs/{runId}/faults. It fires on the next observation it applies to, count times (default once) or, if persistent, until removed or the run ends. Every firing is a fault.injected event beside the observation it acted on. No randomness: the same faults against the same traffic give the same timeline.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/faults \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "duplicate", "resource": "stripe_callback", "copies": 2 }'

One active fault of each type per resource, and up to 64 faults per run. When several apply to the same delivery, drop wins, then delay, then duplicate. DELETE /v1/runs/{runId}/faults/{faultId} disarms one and records fault.removed; the row is kept, because the fault history is evidence. Faults never act on a replay, which is the test's own explicit act.

Expectations and verdicts

Expectations are judged when the run is finished, against the whole timeline. Each one passes if any event of its type on its resource satisfies its match, and the first such event is recorded with the verdict. The run's outcome is derived from the verdicts: pass when every expectation passed, fail when any failed, none for a suite without expectations. Pass an outcome to override the derivation when your own test harness knows better.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/finish \
  -H "Authorization: Bearer $IRONFANG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "npm test exited 0" }'

{
  "run": { "id": "...", "status": "finished", "outcome": "pass", ... },
  "expectations": [
    { "id": "order_email", "resource": "customer_email", "event": "email.received",
      "passed": true, "event_id": "...", "sequence": 9 },
    { "id": "stripe_forwarded", "resource": "stripe_callback",
      "event": "connector.request.completed", "passed": true, "event_id": "...", "sequence": 12 }
  ]
}

Finishing records one expectation.passed or expectation.failed per expectation and then run.completed. A run that is cancelled or reaches its TTL ends with run.cancelled or run.expired and no verdicts. Send an Idempotency-Key header when starting a run so a retried CI step returns the run it already started.

Replay

POST /v1/runs/{runId}/events/{eventId}/replay forwards a callback the run received to its connector route again, exactly as recorded, to prove the application handles a repeat. The event must be a callback.received on a resource with a connector route, and the run must be active.

curl -X POST https://api.ironfang.uk/rig/v1/runs/$RUN_ID/events/$EVENT_ID/replay \
  -H "Authorization: Bearer $IRONFANG_API_KEY"

{ "event": { "type": "callback.replayed", "data": { "event_id": "...", "replay": 1, ... } },
  "delivery_id": "..." }

The replay is recorded as callback.replayed and then travels like any delivery: the timeline shows its own callback.forwarded and connector.request.completed against the original event id, and the completion names the delivery_id the response gave you. Armed faults do not act on a replay. At most 200 replays per run; a 422 not_replayable names an event that is not a forwardable callback.

Evidence bundle

POST /v1/runs/{runId}/evidence builds the run's evidence bundle from what it recorded and streams it as a ZIP. It is read-only: the bundle is what the caller can already read event by event, packaged so it can be attached to a ticket, an audit or a release.

Bounded at 10,000 events and 256 MiB of payloads; the manifest says when a bound bit, and lists payloads that retention had already taken. With Accept: application/json the manifest alone is returned, with the path that downloads the bundle.

ironfang-rig evidence $RUN_ID -o checkout-$RUN_ID.zip
# prints the bundle's SHA-256

Command line

ironfang-rig is a single static binary for Linux, macOS and Windows, published with a SHA-256 checksums file per release at the releases page. It reads the key from IRONFANG_API_KEY or --api-key-file, never from an argument, and talks to https://api.ironfang.uk/rig unless IRONFANG_API_URL says otherwise.

ironfang-rig sync     [-f ironfang.rig.yaml]
ironfang-rig run      [-f file] [--ttl 30m] [--external-id id] [--output text|env|github|json] [-- command args...]
ironfang-rig finish   <run-id> [--outcome pass|fail|none] [--reason text]
ironfang-rig status   <run-id>
ironfang-rig events   <run-id> [--since 0] [--json]
ironfang-rig wait     <run-id> --type <event type> [--resource name] [--match key=value]... [--since 0] [--timeout 30s]
ironfang-rig evidence <run-id> [-o ironfang-rig-<run-id>.zip]
ironfang-rig replay   <run-id> <event-id>
ironfang-rig version

run syncs the suite, starts a run and prints its addresses. With a command after --, it runs that command with IRONFANG_RIG_RUN_ID and one IRONFANG_RIG_<RESOURCE> variable per resource, then finishes the run. --output env prints those assignments for a shell to source; --output github writes them to the job's outputs and environment.

GitHub Actions

Two composite actions in the public ironfang-ltd/rig-action repository wrap the CLI. start syncs the suite file, starts a run and exports its addresses as step outputs and job environment variables; finish finishes the run, prints the verdicts and fails the step when the outcome is fail. Store the key as a repository secret.

jobs:
  integration:
    runs-on: ubuntu-latest
    env:
      IRONFANG_API_KEY: ${{ secrets.IRONFANG_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - id: test
        uses: ironfang-ltd/rig-action/start@v1
        with:
          suite-file: ironfang.rig.yaml
          ttl: 20m
      - run: npm test
        # IRONFANG_RIG_RUN_ID and IRONFANG_RIG_<RESOURCE> are in the environment
      - if: always()
        uses: ironfang-ltd/rig-action/finish@v1
        with:
          run-id: ${{ steps.test.outputs.run_id }}

The start step also exposes resources, a JSON object of resource name to address, for steps that prefer to read it as data.

MCP tools

The Ironfang MCP server exposes the same product to coding assistants, so an agent can start a run, read the timeline, arm a fault and export the evidence without leaving the editor. Every tool is organisation-bound to the connection and costs no credits. Tools that create or change something say so in their metadata.

Payload bytes are never returned through the connection; the tools return what the timeline recorded and point at the API for the rest.

Limits and retention

Export the evidence bundle before retention runs if a run must outlive it. Suites, their versions and projects persist.

API reference

Base URL https://api.ironfang.uk/rig. The OpenAPI 3.1 document at https://api.ironfang.uk/rig/openapi.yaml carries every schema, example and error, with stable operation ids for generated clients. Ids are UUIDs; lists page with cursor and limit (up to 100).