Skip to main content
Firedrill does not require your agent to move into a cloud sandbox. Connect the real application through a small adapter and give it only the synthetic interfaces it needs. There are two kinds of access:
  • Operator access lets your CLI, SDK, or coding agent prepare simulations and read reports.
  • Tool access lets the agent under simulation call allowed operations on its current synthetic instances.
Never pass your operator credential to the agent under simulation.

​
During a simulation

Add Tool bindings to your recipe. Each binding selects an exact build, optional dataset, unsigned decimal-string seed, allowed operations, and an alias. The runner prepares isolated instances for the case. A native SDK callback receives context.tools[alias]; it can invoke semantic operations or explicitly export a connection for the application’s MCP/HTTP client. Command and HTTP adapters receive the run’s scoped Tool connections in the target invocation envelope. Your adapter routes the real dependency seam through those URLs. It does not replace the application’s reasoning with expected results. See the exact TypeScript, Python, and command adapter examples.
A Tool’s semantic HTTP or MCP operation interface is not automatically a drop-in copy of a vendor’s complete REST API. Use the release’s declared routes and schemas. Never silently fall back to a live provider when a synthetic operation is unsupported.

​
For manual exploration

Start an instance with firedrill tools start. Its ready output shows the connection endpoints and a complete command for issuing a narrowly scoped credential. To inspect the current instance first:
Use the actual returned ID, current epoch, and one of its allowed operation IDs. For example, after setting FD_INSTANCE_ID, FD_EPOCH, and FD_OPERATION_ID from that response:
Add tool-connection.json to your ignore rules and protect it as a credential. Use the exact returned endpoint and token in the target’s test-only MCP configuration. For semantic HTTP, select --audience http instead. A connection does not start the agent. HTTP semantic calls send operationId and arguments to the issued endpoint with its derived bearer token and a saved Idempotency-Key. An HTTP 200 response alone is not proof that the semantic operation succeeded; inspect its outcome.

​
Lifetime, reset, and revocation

A Tool connection has its own expiry and cannot outlive its parent authority or instance. Extending the instance does not renew its connections. Snapshot restore advances the instance epoch and invalidates earlier grants. Obtain fresh bindings instead of editing a stale grant.
Use identities returned by your own instance’s connection list. If a one-time credential response was lost, reconcile metadata, revoke that grant explicitly, and issue a replacement only as a deliberate action.

​
Browser access

Open a current instance in the web app. If the Tool has a supported browser app, its preview and Open Tool action access the same seeded state. An ended instance retains history but no active browser connection.