Skip to main content
A simulation executes your application under declared conditions and saves what happened. Use it to explore behavior, demonstrate a workflow, compare configurations, or check a requirement. Tools and checks are optional. Your coding agent prepares and runs the recipe in your repository. Your application stays on your machine or in CI; Firedrill coordinates simulations and retains their state and evidence.

​
1. Select a project

With Node.js 22 or later, initialize without a global installation:
Skip or select the optional CLI, MCP, skills, and SDK additions, then review any changes. Complete browser sign-in, then select or create a project. Use init --skip-install to omit the optional wizard. init writes the selected projectId and environmentId to firedrill.config.json, not credentials. Commands use that selection and connect to Firedrill automatically. The commands below use firedrill for readability. Run them with the same npx firedrill-run prefix, or optionally install npm install --global firedrill-run to use the shorter command directly.
Save the creation key and reuse it after an uncertain response. To select an existing project, use firedrill init --project ID with an exact ID from firedrill projects list. Use one initialization path; a different existing configuration is not overwritten.

​
2. Save a command adapter

Save this as stock-adapter.mjs in your current directory:
This is a small deterministic application, not an AI agent. It proves the invocation and evidence path. To investigate your real agent, replace the decision logic with a call to your application’s actual entry point and return its real output. The command receives one JSON envelope on stdin and emits one JSON value on stdout. Write diagnostics to stderr. The envelope contains task input, configuration, run/attempt IDs, scoped Tool connections, and scenario ID—not checks, rubrics, or future sequence steps. Ordinary command execution is not a filesystem or network sandbox.

​
3. Save the recipe

Save stock.recipe.json beside the adapter:
Each scenario supplies one situation. This recipe requests two runs with no Tools, grading, or CI gate. Relative command paths resolve from the directory where you run the CLI, not from the recipe file’s directory.

​
4. Preview and execute

The explicit filename selects this example even if your repository has other recipes. For terminal selection instead, use firedrill simulate with no filename. Optional preflight: firedrill doctor stock.recipe.json checks local prerequisites; firedrill preview stock.recipe.json shows expansion and admission blockers without invoking the target or reserving capacity. Neither proves the application works. simulate executes the command and saves a batch with individual runs. Open its returned report link, or use Results and evidence to inspect saved inputs, outputs, execution, and activity. The example is designed to return approve for the first input and review for the second; inspect the actual report rather than treating that expectation as evidence. For coding-agent-friendly output:
This starts another batch. Do not use it merely to read the batch you already ran.

​
5. Add only the evaluation you need

To make the shortage requirement exact, add this checks field to that scenario:
For natural-language behavior, add a task-specific semantic rubric that accepts different valid answers. Add an optional CI gate only when you want a release decision. Execution, observed outcome, assessment, and gate remain separate.

​
Continue with your application

Use a TypeScript callback or Python callback when your entry point is already a function. An existing HTTP application can use an HTTP target. Add Tools only for synthetic dependencies your workflow needs. Then repeat scenarios, vary inputs, or capture a real browser. Keep the reviewed recipe and adapter in your repository for reuse in CI. If interrupted, preserve the private journal and use the exact recovery command printed by the CLI. A fresh simulation is new work, not recovery.