SDK overview

Use an SDK when your application is a Python or TypeScript callable, or when you need programmatic control of simulations. A suitable command or HTTP entry point can use the CLI without an SDK import. Your application runs in your process or runner. The client handles coordination, private recovery journals, evidence finalization, and cleanup of run-owned Tools. It does not host your application or replace its model calls.

​

The common flow

1. Authorize a Firedrill identity and select a project/environment pair.
2. Pass a recipe and your real application callback to simulate.
3. Inspect the retained batch, runs, output, evidence, and report link.
4. Reuse the recipe for repeated trials or ordinary CI.

Tools, exact checks, semantic rubrics, and CI gates are optional. Missing assessment is not a zero score; evaluator failure is not agent failure. Semantic scores allow valid output variation, while exact checks protect precise requirements.

​

Shared operations

submit uses a saved admission key; resume uses the execution operation ID from the customer’s private journal. They are not interchangeable. A report read never needs a new execution.

​

Credentials and scope

The clients select https://api.firedrill.run automatically. They reuse protected Firedrill login when no explicit token is selected. CI uses FIREDRILL_TOKEN plus FIREDRILL_PROJECT_ID and FIREDRILL_ENVIRONMENT_ID. An invalid explicit token never falls back to another identity. Keep operator credentials out of recipes, application inputs, logs, and source. Application/model credentials and scoped synthetic Tool connections are separate from Firedrill account authorization. For browser capture, the optional Node runner package is @firedrill-run/runner-node; see web application simulations. Install it only when your execution path needs browser support. See errors and recovery before adding automatic retries.