# Set up Firedrill

You are a coding agent setting up Firedrill for the user. Firedrill is a
simulation platform for AI agents: it runs the user's agent in a synthetic world
of users, tools, data and scenarios, then evaluates what the agent did. The
user's agent runs on their machine. Firedrill keeps the worlds, scenarios and
reports in the cloud.

Follow the steps in order. Stop and ask the user whenever a step needs their
sign-in or approval. Never invent a package, command or URL that is not on this
page or in the [documentation](https://docs.firedrill.run/).

## 1. Check what is already set up

- If a `firedrill` MCP server is already configured in this client, reuse it.
- If the CLI is installed globally, run `firedrill status`; otherwise run
  `npx firedrill-run status`. It shows the account, workspace and credential
  mode. If it reports a signed-in workspace, skip to
  step 4.
- If a `firedrill` skill is already installed in this client, keep it.

## 2. Connect the remote MCP server

The MCP server is `https://mcp.firedrill.run`. It manages cloud resources and
reads reports. It cannot read local files or start local processes. Add it with
the command for your client:

| Client | Command or configuration |
| --- | --- |
| Claude Code | `claude mcp add --scope project --transport http firedrill https://mcp.firedrill.run`, then open `/mcp` and authorize Firedrill |
| Codex | `codex mcp add firedrill --url https://mcp.firedrill.run`, then `codex mcp login firedrill` |
| Cursor | Add `{"mcpServers": {"firedrill": {"url": "https://mcp.firedrill.run"}}}` to `.cursor/mcp.json`, keeping existing servers |
| VS Code | Add `{"servers": {"firedrill": {"type": "http", "url": "https://mcp.firedrill.run"}}}` to `.vscode/mcp.json`, keeping existing servers |
| Other clients | Add `https://mcp.firedrill.run` as a remote Streamable HTTP server |

The user completes sign-in in their browser. You never handle a token. Some
clients need a restart or a new session before the tools appear.

## 3. Install the CLI and sign in

The CLI runs the user's agent locally during a drill. It needs Node.js 22.23.4
or a later 22.x release, 24.11.1 or a later 24.x release, or 26.13.1 or a
later 26.x release. Other versions, including 23 and 25, are not supported.

A person setting up by hand runs:

```sh
npx firedrill-run init
```

As a coding agent, start sign-in once, in JSON mode:

```sh
npx firedrill-run init --json --no-browser
```

- It prints a link and a code. Give both to the user and keep that same
  command running until they approve, deny or the code expires. Never run
  `init` a second time while the first sign-in is pending.
- `npx firedrill-run` does not install a global `firedrill` command, so every
  later command keeps the prefix: `npx firedrill-run status`, `npx firedrill-run workspace create`.
- Installing globally is optional. After `npm install -g firedrill-run` the
  shorter `firedrill` command works, and other Firedrill pages use it. With
  npx, read `firedrill` in those pages as `npx firedrill-run`. After a global
  install the agent sign-in is `firedrill init --json --no-browser`, still run
  only once.
- New accounts need no payment card and start with free monthly credits.
- If the user has no workspace yet, `firedrill workspace create` shows its name,
  terms and privacy policy, and the command to run next. Show these to the user
  and run that command only after they approve.
- Credentials are kept in the OS credential store. On a machine without one,
  add `--session-only` to that one `init`. The sign-in then lives only in that
  process, so keep it running while other commands use it. Pass
  `--session-only` on those later commands too, as `init` prints them (for
  example `npx firedrill-run status --session-only --json`).

CLI sign-in and MCP sign-in are separate. Signing in does not approve any spending
or any local command.

## 4. Offer the Firedrill skill

The Firedrill skill gives you these instructions in every future session: setup,
registering the agent, building its world, running drills and reading reports.
It is instructions only. It installs no CLI and no connection, and runs nothing.

If it is not already installed (look for a `firedrill` skill in this client's
skills folder), ask the user whether to add it. Run this only after they agree:

```sh
npx skills add firedrill-tools/firedrill-skills
```

It installs into the project by default. Add `-g` for every project, or
`-a <client>` (for example `-a claude-code` or `-a codex`) for one client. Some
clients need a new session before the skill appears.

## 5. Confirm with the user

Tell the user:

- the account and workspace you are connected to;
- whether the MCP server and the CLI are both working;
- the installed CLI version;
- whether the Firedrill skill is installed.

Then ask which agent in this repository they want to simulate, and what they want
to learn. A specific goal is optional.

## 6. Next: run a simulation

Follow [Run your agent](https://firedrill.run/run-your-agent.md). In short:
register the agent, build its world, review the plan and credit estimate, apply
it after the user approves, run the drills locally and read the report.

Ground rules for every step:

- Never upload the user's source code. Registration sends only names, hashes and
  interface details.
- Dependencies are synthetic by default. Using a real account or real recipient
  needs the user's explicit approval for that dependency.
- Run local commands only from a plan the user approved. Local runs use the
  user's own permissions and are not a sandbox.
- Show the credit estimate before anything that uses credits.
- Missing evidence is not a pass or a failure. Report what was observed.

[Run your agent](https://firedrill.run/run-your-agent.md) ·
[Sign-in and access](https://firedrill.run/auth.md) ·
[Pricing and credits](https://firedrill.run/pricing.md) ·
[Documentation](https://docs.firedrill.run/) ·
[Web app](https://app.firedrill.run/)