# Run your AI agent with Firedrill Canonical guide: https://firedrill.run/run-your-agent.md You are a coding agent operating Firedrill for your user. The target is the AI agent or application in their repository. It runs on this machine as an ordinary local process. Firedrill keeps the worlds, synthetic users, scenarios, hosted tools, evaluations and evidence in the cloud, and the portal shows the same progress you see. Local execution is not an operating-system sandbox. Firedrill starts only the commands and roots the user approved, but those processes run with the user's own permissions. Every command below accepts `--json`. In JSON mode the CLI never prompts and never opens a browser on its own (unless `--open` is given). It prints one `{"type", "data"}` object per line. Trust the installed CLI's own `firedrill --help` over this page when they differ. ## 1. Set up access Four separate steps. Doing one does not do another. 1. **Skill (instructions only).** `npx skills add firedrill-tools/firedrill-skills` installs the Firedrill skill for your client. It installs no CLI and no connection. 2. **CLI.** Install it from the [CLI reference](https://docs.firedrill.run/cli/overview), then check with `firedrill status --json`. If it is missing, tell the user. Do not pick a package yourself. 3. **Sign in.** `firedrill init --json --no-browser` signs in, or starts account creation, through WorkOS device authorization, then selects a workspace and checks this machine. - It prints a verification link and code. Relay them to the user, who approves in the browser. - Keep the original attempt until it is approved, denied or expired. - Credentials stay in the OS credential store. Use `--session-only` where none exists, and keep that sign-in companion open while other commands use it. - Read [account authorization](https://firedrill.run/auth.md) first when the user has no account. - No workspace yet: `firedrill workspace create "" --json` sends nothing. It prints the name, the terms of service and privacy policy, and the exact command to run. Run that command only after the user approves the workspace and both documents. Never accept them for the user. 4. **Remote MCP (optional).** `firedrill mcp --agent codex|claude|other` shows connection guidance for `https://mcp.firedrill.run`. - The MCP client signs in through its own browser OAuth. - Remote MCP manages cloud resources but cannot run anything on this machine. - CLI sign-in does not authorize MCP clients, and MCP sign-in does not authorize the CLI. Never put passwords, provider keys or tokens in a prompt, command argument, file or report. ## 2. Understand the project Read the repository before asking questions. Find: - how the agent is invoked: an HTTP endpoint, a process speaking JSON lines, a function, or a browser flow; - what signals completion; - which model settings it uses; - which services it calls; - what state it keeps and how that state resets. An objective is optional. Propose useful scenarios from the project's behavior and ask only about real ambiguities. A successful run of the whole workflow is a useful result, not a failure to find a failure. Describe the agent in a local descriptor and register it: ```sh firedrill register --descriptor descriptor.json --name "" --json ``` - A descriptor is metadata only. It holds no source, absolute paths, commands or secret values. - Later revisions add `--agent --expected-revision `. - `firedrill descriptors --agent ` lists the history. ## 3. Reuse, then author, cloud resources ```sh firedrill library --kind scenario --search "" --json firedrill library --kind persona --json firedrill world versions --json firedrill tools definitions --json firedrill tools catalog ``` - **Reuse first.** Reuse exact versions when they fit the agent's real operations and state. - **Author only the gaps.** `firedrill library save --kind --file --json` creates a private draft; edits take `--expected-revision`. - **Missing hosted tool.** If no catalog tool covers a dependency, a private tool package (`firedrill tools init`, `validate`, `push`) is a separate approval. - **Pin versions.** Every run pins the versions it uses, so later edits never change a run in progress. - **Parameters.** Use `firedrill library bind --file ` to create a private version with explicit template values. - **Shared definitions.** After approval, `firedrill world fork --agent ` creates a private world. Remap referenced tools or library versions when this workspace cannot use them. Sharing a world does not grant its dependencies or copy credentials, configuration values or running state. - **Private tool copies.** `firedrill tools definitions copy ` copies an authorized version for fresh inspection here. Follow `tools definitions copy-status `; `copied` alone is not ready for use. Wait for `upload.state` to be `inspected` with an `upload.implementation_id`. - **Interrupted changes.** Keep the printed request key and recover the original. `register`, `library` and `world` provide `request` and `withdraw-request`; sharing and copying have their own recovery commands in CLI help. Never use a new key just because the previous answer was lost. Declare the world for the registered agent. Nothing starts yet. ```sh firedrill world save --agent --file world.json --json ``` ## 4. Plan without effects ```sh firedrill plan --world --json ``` - **Effect-free.** The plan saves a review but starts no tools or drills and makes no charge. - **What it shows:** pinned versions, how each dependency is reached, requirement gaps and a cloud-work estimate. Local target compute is never charged. - **Gaps.** An unmet requirement means that part cannot run yet. Report the returned requirement; do not swap in another tool silently. - **Two sides:** the local half of the plan (roots, commands, readiness, driver, state resets) stays on this machine. `firedrill status --plan local-plan.json --json` checks the drivers. Show the user what will run where, which services and data it can reach, what is reset between drills, what evidence is captured, and the maximum estimate. Ask for an explicit yes. ## 5. Apply after approval ```sh firedrill apply --approve --follow --json ``` - **Reservation.** Apply reserves preparation costs first. Drill work is reserved in bounded waves as it is admitted, within the approved whole-plan maximum. Once preparation is ready, apply creates its simulation (campaign). `campaign_created` prints the campaign id. No drill starts at this step. - **Interrupted apply.** It prints a request key before sending. If it is interrupted, run `firedrill apply --request --follow`; this never approves or charges twice. - **Not needed after all.** A preparation that is ready and has no campaign yet can be cancelled with `firedrill apply --request --cancel` after the user approves. It releases the unused reserved credits. - **Changes after approval.** If a draft, price or permission changes, make a new plan instead of reusing the old approval. ## 6. Run the drills on this machine Enroll this machine once, then run. The user does the enrollment; it is a device identity, not permission to execute. Local execution currently supports macOS and Linux on arm64 or x64. Windows sign-in and cloud commands do not imply local runner support. ```sh firedrill runner enroll firedrill run --plan local-plan.json --descriptor descriptor.json --campaign --approve --json ``` For session-only access, keep the sign-in companion open and use `firedrill run --session-only --enroll-device` with the same plan, descriptor, campaign and approval flags. Add `--enroll-device` only after the user agrees to enroll this session. Its device key stays in memory and ends with the run. - **Approval.** Obtain approval for that exact local plan before using `--approve`. Without JSON mode, an interactive run can ask for approval. JSON mode never prompts or supplies approval on the user's behalf. - **Driving the agent.** The cloud controller sends each drill's user turns, tasks or events to the agent through the chosen driver. Synthetic users and hosted tools answer from the cloud. - **Concurrency is bounded.** It is bounded by the simulation's approved maximum, and services shared across drills require one drill at a time. - **Resets.** Mutable state follows the approved reset contract. Missing required resets prevent a drill from starting. Explicit observation-only state remains distinct and does not promise a reset. - **Credentials.** The agent receives scoped tool access only. It never receives your Firedrill session or the coding agent's own credentials. **Disconnects and uncertain effects:** - After a disconnect, inspect the original campaign and executor status. Follow the returned recovery instructions; do not create a replacement campaign or assume a lost local process can be resumed. - A step whose outcome is unknown is reported as unknown and never invoked again. - `firedrill simulation cancel --approve-change` stops new drills and revokes running ones. Cancelling does not undo effects that already happened. ## 7. Watch and report ```sh firedrill watch --follow --json firedrill report --json firedrill report drill --json firedrill report quality --json firedrill report drill actions --json ``` - `quality` pages each criterion across drills, one compatible cohort at a time. - A drill's `results`, `conversation`, `effects`, `events`, `actions` and `evidence` views show what happened and how complete each record is. - The report links to the portal for the user. - `firedrill report drill reassess` reviews a separately priced assessment of retained evidence. It requires approval and does not run the agent again. `reassessments` lists those attempts separately. Keep these separate: - execution state; - the agent's observed outcome; - per-criterion quality; - required checks. Missing evidence stays missing; it is never a zero or a pass. Each quality cohort is reported on its own; cohorts are never merged. Follow a finding into the drill's conversation, tool calls and evidence before proposing a change. Never edit the target during a drill to produce a pass. ## Optional: hosted tools outside a drill `firedrill tools runnable` lists saved tool versions that can run in the cloud for a set time. - `firedrill tools start ... --seconds ` shows an estimate. After the user approves, run the printed `--request-key ... --usage-quote ... --approve-tool-change` command. - `firedrill tools access ` serves the running tools to an agent on this machine. Access is read-only unless `--allow-writes` is given. - `firedrill tools session renew --seconds ` extends a running session's shared-pool tools after the user approves the new estimate. The tools keep their data and nothing restarts. - `firedrill tools state ` saves or edits a shared-pool tool's data (`checkpoint`, `snapshots`, `edit`). `reset` and `fork` start a new session from that data, after the user approves their estimate. ## When something stops | Code or situation | Do this | | --- | --- | | `native_contract_pending` | That part is not available in the installed release. Tell the user; do not improvise. | | `legacy_launch_retired` | The older world commands that started work (`validate`, `simulate`, `simulation run`, `sessions open`, `runner execute`, `ci configure`, `datasets start`, `--managed`) are retired, and nothing was sent. Use plan, apply and run. Retained campaigns can still be read, watched and cancelled. | | An answer was lost (timeout, disconnect) | Re-run with the printed request key. Never resubmit with a new key. | | `tool_change_consent_required` and other consent codes | Show the user what changes and its cost, then rerun with the printed approval flag. | | A plan gap or a missing dependency binding | Report it. Never fall back to live accounts or real credentials. | | The credential expired or the user signed out | Run `firedrill init` again; the user approves in the browser. | [Agent connection guide](https://firedrill.run/agents.md) · [Account authorization](https://firedrill.run/auth.md) · [Operator handoff](https://firedrill.run/start.md) · [App](https://app.firedrill.run/)