> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ironbee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> IronBee (ironbee.ai) is an AI QA engineer: it verifies code changes against the running app and keeps the evidence. It is not related to the IronBee open-source web application firewall.
> The console is at https://console.ironbee.ai.
> Install the CLI with `npm install -g @ironbee-ai/cli`, sign in with `ironbee login`, and set up a project with `ironbee install`.
> In GitHub workflows, use the action as `ironbee-ai/ironbee-action@v1` and pass the `IRONBEE_API_KEY` secret as the `ironbee_api_key` input.
> In GitLab pipelines, include the component `gitlab.com/ironbee-ai/ironbee-gitlab/verify@v1`; it reads the `IRONBEE_API_KEY` CI/CD variable by default.
> In Bitbucket Pipelines, run the pipe `docker://ghcr.io/ironbee-ai/ironbee-bitbucket:v1` and pass `IRONBEE_API_KEY: $IRONBEE_API_KEY` and `BITBUCKET_OAUTH_TOKEN: $BITBUCKET_OAUTH_TOKEN` under its `variables:`.
> Console scenarios (https://docs.ironbee.ai/console/scenarios) and CLI saved scenarios (https://docs.ironbee.ai/cli/guides/scenarios) are separate features.
> For plans and prices, link to https://ironbee.ai/pricing; the website is the source of truth for them.

# CLI configuration

> Tune IronBee's verification behavior with layered global, project, and local config.

IronBee works out of the box, and most projects never need to touch config. When you do want to fine-tune *which* files get verified, change retry limits, or point at a self-hosted collector, this page is the reference.

You can edit settings two ways: the `ironbee config` command (recommended, since it validates and re-applies changes for you) or by editing the JSON files directly.

***

## Config layers

Settings are read from three files and **deep-merged**. Higher layers override lower ones:

| Layer | File | Use for |
| - | - | - |
| Global | `~/.ironbee/config.json` | Defaults across all your projects (e.g. your collector credentials) |
| Project | `<project>/.ironbee/config.json` | Team settings committed to the repo |
| Local | `<project>/.ironbee/config.local.json` | Personal overrides, gitignored, never shared |

Precedence is **local > project > global**. A key set in the local layer wins over the same key in the project layer, which wins over global.

Secrets can also come from the environment: setting `IRONBEE_SERVICE_API_KEY` (or the legacy `IRONBEE_API_KEY`) supplies the account API key without committing it to any file.

Credentials can't be written inside the checkout: `ironbee config set` refuses `service.oauthToken`, `service.apiKey`, `collector.oauthToken` and `collector.apiKey` on the project and local layers. Write them with `-g` (the global config) or `--personal` (the repository's [personal file](#the-personal-file)). `ironbee review` and `ironbee credits` also read their endpoints and credential from the personal file, and never from a file inside the checkout. No other command reads the personal file, so keep the credential that `ironbee verify` and your sessions use in the global config or the environment.

The CLI never writes a config file inside the checkout through a symbolic link: `ironbee config set`, the toggle commands and the TUI refuse when `.ironbee/` or the file is a link. The global config is written readable by you only (`0600`).

***

## Editing config from the CLI

```bash theme={null}
ironbee config get <key>            # read the effective (merged) value
ironbee config set <key> <value>    # write to the project config
ironbee config unset <key>          # remove a value (idempotent)
ironbee config list                 # print the merged effective config
ironbee config path                 # print the project config file path
```

**Targeting a layer:**  `set`, `unset`, and the read commands accept `-g`/`--global` or `--local` to act on a specific layer (default is the project config). `list` and `get` also take `--project` to read one layer in isolation:

```bash theme={null}
ironbee config set service.apiKey sk-... --global
ironbee config set maxRetries 5
ironbee config set browser.verifyPatterns '["*.ts", "*.tsx", "*.css"]'
ironbee config list --global
```

**The personal file:** `set` and `unset` also take `--personal`, which writes the repository's [personal file](#the-personal-file) outside the checkout. Add `--remote <name>` to pick the remote whose repository the file is for (default: the one the branch is pushed to):

```bash theme={null}
ironbee config set --personal review.includeUntracked true
```

**Type coercion:** `set` parses values as JSON when it can (`true`, `42`, `[...]`, `{...}`) and falls back to a plain string otherwise. Pass `--json` to force strict JSON parsing.

**Automatic re-render:** when you change a key that affects installed client artifacts (anything under `verification`, `service`, `collector`, `browser`, `node`, `python`, `backend`, `android`, `terminal`, `telemetry`, `privacy`, `codex`, `runtime`, `integrations`, or the `*DevTools` overrides), the CLI automatically re-renders your hooks, MCP entries, skill, rule, and permissions. Pass `--no-rerender` to skip. After a global write on an artifact-affecting key, the CLI offers to propagate it to every registered project. `--apply-all` accepts without prompting, `--no-apply-all` declines. Nested keys that are read live, such as `verification.context`, `verification.changes`, `verification.checks` and the allow-lists, take effect without a re-render.

> [!NOTE]
>
> Restart your editor or agent session after changing an artifact-affecting key; it takes effect on the next session.

***

## Core options

| Key | Type | Default | Description |
| - | - | - | - |
| `ignoredVerifyPatterns` | `string[]` | `[]` *(plus always-on test-file defaults)* | Glob patterns excluded from **all** cycles. Checked first a match here activates no cycle, whatever else matches. Your patterns are **unioned on top of** a built-in default set that always excludes test files (`**/*.spec.*`, `**/*.test.*`, `**/__tests__/**`, `**/__mocks__/**`, `**/test_*.py`, `**/*_test.py`, `**/tests/**`, `**/conftest.py`), so a test-only edit never triggers a runtime-verification cycle even if you set nothing. |
| `maxRetries` | `number` | `3` | Failed verification attempts allowed before the agent may complete anyway (reporting unresolved issues). Caps both the gate's retry count across all active cycles and the streak of consecutive failed verdicts for one change. |
| `params` | `object` | *(unset)* | User-defined string→string map consumed by [`${param:<name>}` placeholders](#placeholders-param-env-built-ins) elsewhere in the config. Merged per key across layers (local wins). Not artifact-affecting (read live). |

```json theme={null}
{
  "ignoredVerifyPatterns": ["**/generated/**", "**/*.gen.ts"],
  "maxRetries": 5
}
```

> [!NOTE]
>
> Test files are already excluded out of the box - `ignoredVerifyPatterns` is only for *additional* paths you want to skip on top of that built-in default.

***

## Placeholders - `${param:}`, `${env:}`, built-ins

Config **string** values can interpolate placeholders that IronBee resolves at **read time**, so one committed config can carry per-developer or per-environment values without hand-editing. Three forms are supported:

| Form | Reads from | Example |
| - | - | - |
| `${param:<name>}` | The [`params`](#core-options) block, overridable per key by the `IRONBEE_PARAM_<NAME>` env var | `${param:api_url}` |
| `${env:<name>}` | The `IRONBEE_ENV_<NAME>` env var **only** | `${env:staging_url}` |
| Built-ins | Static values | `${projectDir}` `${projectName}` `${home}` `${configDir}` `${platform}` `${arch}` `${tmpdir}` |

Each `${param:}` / `${env:}` reference takes an optional bash-style default after `:-` (e.g. `${env:staging_url:-http://localhost:3000}`), and resolves in this order:

* **`${param:api_url}`** → `IRONBEE_PARAM_API_URL` env → the `params` block (local → project → global) → the `:-` default → the literal text (with a warning).
* **`${env:staging_url}`** → `IRONBEE_ENV_STAGING_URL` env → the `:-` default → the literal text.

```json theme={null}
{
  "params": { "api_url": "http://localhost:3000" },
  "verification": {
    "checks": [
      { "name": "api-test", "command": "npm",
        "args": ["run", "test:api", "--", "--base-url", "${param:api_url}"] }
    ],
    "context": { "message": "Verify against ${env:staging_url:-http://localhost:3000}." }
  }
}
```

> [!NOTE]
>
> The `env:` / `param:` prefix is **implied and never written** - `${env:staging_url}` can only read `IRONBEE_ENV_STAGING_URL`, so arbitrary environment variables (`AWS_SECRET_ACCESS_KEY`, tokens, …) are structurally unreachable from config text. Write a literal `${` as `$${`. Upper-case shell forms like `${HOME}` in check arguments are left untouched.

Placeholders resolve for **runtime consumers** (checks, context injection, the collector). Values baked into **committed client artifacts** are read raw and kept as literal references, so a resolved value never lands in a shared artifact - the supported keys are the runtime-read ones (`verification.checks[]` command/args/env/cwd and `verification.context.message`). `ironbee config get <key>` (merged) prints the **resolved** value with a provenance note on stderr; a layer-scoped read (`--project` / `--global` / `--local`) shows the raw on-disk text.

***

## Runtime

| Key | Type | Default | Description |
| - | - | - | - |
| `runtime.location` | `string` | `"external"` | Where per-session runtime data (the `sessions/` folder - `actions.jsonl`, verdicts, queue) is stored. `"external"` *(default)* keeps it **out of the project tree** at `~/.ironbee/projects/<token>/sessions/`, so a project never accumulates a growing `sessions/` folder even when it's gitignored. `"in-project"` stores it under `<project>/.ironbee/sessions/` (the legacy layout). Committed config, `scenarios/`, and `VERIFICATION.md` files always stay in-project regardless. The [`IRONBEE_RUNTIME_LOCATION`](https://docs.ironbee.ai/cli/configuration/environment-variables#advanced) env var overrides it per process. Takes effect on the next session. See [Runtime files](https://docs.ironbee.ai/cli/advanced/runtime-files.md#where-per-session-data-lives). |

> [!NOTE]
>
> Switching `runtime.location` doesn't move existing session data - it changes where *new* sessions are written. Old per-session folders under the previous location are left in place; you can delete them by hand if you don't need them.

***

## Verification

| Key | Type | Default | Description |
| - | - | - | - |
| `verification.enable` | `boolean` | `true` | Master enforcement switch. `false` = monitoring-only (telemetry still flows, no verify gate). Equivalent to [`ironbee verification disable`](https://docs.ironbee.ai/cli/guides/verification#verification-modes). |
| `verification.auto` | `boolean` | `false` | Automatic-enforcement sub-toggle (only meaningful when `verification.enable` is `true`). Default `false` = [assist mode](https://docs.ironbee.ai/cli/guides/verification.md#assist-mode-default), the safer default: the `/ironbee-verify` command, the devtools MCP server, and permissions stay installed for manual verification, but nothing is enforced: there's no verify gate, the pre-edit hooks don't block, and the skill/rule are omitted. Set `true` for full [enforce mode](https://docs.ironbee.ai/cli/guides/verification.md#enforce-mode) (blocking Stop gate + skill/rule installed). Equivalent to [`ironbee verification auto enable`/`disable`](https://docs.ironbee.ai/cli/guides/verification#enforce-mode). |
| `verification.model` | `string` \| `object` | *(unset - inherit the session model)* | Model the [delegated verifier sub-agent](https://docs.ironbee.ai/cli/guides/verification.md#picking-the-verifier-model) runs on (Claude Code and Codex). Unset means the verifier inherits the main conversation's model. Set a **string** (e.g. `"sonnet"`, `"gpt-5.5"`) to apply to every client, or a **per-client object** `{ "claude": "sonnet", "codex": "gpt-5.5" }` when a project uses both. Cursor has no verifier sub-agent, so it's a no-op there. Equivalent to [`ironbee verification model <value>`](https://docs.ironbee.ai/cli/guides/verification#picking-the-verifier-model). |
| `verification.fix` | `boolean` | `true` | [Fix enforcement](https://docs.ironbee.ai/cli/guides/verification.md#fix-enforcement-block-on-a-fail-or-just-report-it). Default `true`: in enforce mode a **fail** verdict blocks completion until the agent fixes the issues and re-verifies (counts toward `maxRetries`). Set `false` for **report-only**: the agent still must verify and submit a verdict, but a fail is reported (and recorded) rather than looped on - the turn may end with the issues stated plainly. Only meaningful in enforce mode; read live by the gate. A manual `/ironbee-verify fix` run escalates that one run to fix-until-pass regardless. Equivalent to `ironbee verification fix <enable\|disable>`. |
| `verification.strict` | `boolean` | `false` | [Strict mode](https://docs.ironbee.ai/cli/guides/verification.md#strict-mode). When `true`, the verify gate **rejects all [N/A verdicts](https://docs.ironbee.ai/cli/guides/verification.md#when-a-change-has-nothing-to-verify-na-verdicts)** - the agent must produce real tool evidence for every active cycle. Default `false` accepts N/A (recorded and observable). Only meaningful in enforce mode (no gate runs in assist/monitoring). Read live by the gate. Equivalent to [`ironbee verification strict <enable\|disable>`](https://docs.ironbee.ai/cli/guides/verification#strict-mode). |
| `verification.checks` | `array` | `[]` | [Project checks](https://docs.ironbee.ai/cli/guides/verification.md#project-checks-run-first-lint-tests-types) - deterministic commands (lint, tests, typecheck, build, format) run as the **first step** of every verification cycle, before any devtools verification. Each entry is `{ "name", "command", "args"?, "env"?, "cwd"?, "timeoutMs"?, "required"?, "kind"?, "conclusive"? }` (`kind` is an advisory `typecheck`/`lint`/`test`/`build`/`format`/`other` label). The verifier runs them via `ironbee hook run-checks`; in enforce mode a `required` check that fails (or never ran) **blocks the gate** so the agent fixes and re-runs (it counts toward `maxRetries`). `conclusive: true` (implies `required`; hand-set only, never suggested) makes a check the **arbiter** of the cycle - all conclusive checks passing auto-submits the pass verdict and **skips** devtools verification; a conclusive check failing defers to a devtools **diagnosis** before a findings-rich fail. See [Conclusive checks](https://docs.ironbee.ai/cli/guides/verification.md#conclusive-checks-let-a-check-decide-the-cycle). Trust is the recorded exit code, never the agent's claim. Can be [LLM-suggested](https://docs.ironbee.ai/cli/guides/verification.md#let-ironbee-suggest-your-checks) at install or via `ironbee checks suggest`. Read live (not artifact-affecting); results are sent to the Collector without their raw output. |
| `verification.changes.source` | `string` | `actions` | [How IronBee detects changes](https://docs.ironbee.ai/cli/guides/verification.md#how-ironbee-detects-changes) for the enforce-mode gate. `actions` uses the agent's file-editing tools; `git` fingerprints the working tree, so it also sees edits made through shell commands; `shadow` decides with `actions` and logs where `git` would differ. Read live (not artifact-affecting). |
| `verification.changes.gitTimeoutMs` | `number` | `2000` | How long the `git` source may take to fingerprint the tree before IronBee falls back to `actions`. Clamped to 200 to 60000. Read live. |

***

## Verification cycles

The six cycles: `browser`, `node`, `python`, `backend`, `android`, and `terminal`, share the same set of keys (replace `<cycle>` with `browser`, `node`, `python`, `backend`, `android`, or `terminal`):

| Key | Type | Description |
| - | - | - |
| `<cycle>.enable` | `boolean` | Explicit on/off. Written `false` by `ironbee <cycle> disable`, stripped by `ironbee <cycle> enable`. Browser is the only cycle on by default; node, python, backend, android, and terminal are opt-in. |
| `<cycle>.verifyPatterns` | `string[]` | Files that trigger the cycle. **Four states:** unset → built-in code defaults · `[]` → hard-disable · non-empty → custom patterns (replaces defaults). |
| `<cycle>.additionalVerifyPatterns` | `string[]` | Extra patterns appended to `verifyPatterns` (or to the defaults when it's unset). Ignored when `verifyPatterns` is `[]`. |
| `<cycle>.alwaysRequired` | `string[]` | Tools the agent must use before the cycle passes (all-of). Sensible per-cycle defaults apply. *Advanced.* |
| `<cycle>.evidencePaths` | `json` | Alternative tool-satisfaction paths (any-of). *Advanced.* |

**Defaults differ per cycle:**

| Cycle | Default state | Default verify patterns |
| - | - | - |
| `browser` | On | 40+ code/markup extensions (`.ts`, `.tsx`, `.js`, `.css`, `.html`, `.vue`, …) |
| `node` | Opt-in | When enabled: server/api/routes code paths |
| `python` | Opt-in | When enabled: server/api/app `.py` paths, Django (`views.py`/`urls.py`/`models.py`/`tasks.py`), Flask/FastAPI (`app.py`/`main.py`), WSGI/ASGI entry points |
| `backend` | Opt-in | When enabled: 13 multi-language code defaults (ts/js/py/go/java/rb/cs/rs/kt/scala/ex/php/clj) |
| `android` | Opt-in | When enabled: standard Android project layouts (Gradle, Kotlin/Java source trees, resources) |
| `terminal` | Opt-in | When enabled: CLI / TUI / shell paths - `cli/`, `cmd/`, `commands/`, and `bin/` trees (at any depth), CLI entrypoints, and shell scripts |

When the browser cycle is off, `node`, `python` and `backend` without their own `verifyPatterns` use a broad language glob instead of the lists above: every JS and TS file for `node` (`**/*.{ts,tsx,js,jsx,mjs,cjs}`), every `.py` file for `python`, and a multi-language code glob for `backend`.

The exact default patterns each cycle uses when `verifyPatterns` is unset:

> [accordion] Browser default verify patterns
>
> Matches code and markup files by extension (project-wide):
>
> ```
> *.ts  *.tsx  *.js  *.jsx  *.mjs  *.cjs
> *.vue  *.svelte
> *.html  *.htm
> *.css  *.scss  *.sass  *.less  *.styl
> *.py  *.rb  *.erb  *.go  *.rs
> *.java  *.kt  *.kts  *.swift
> *.c  *.cpp  *.h  *.hpp  *.cs  *.php  *.dart
> *.ex  *.exs  *.erl  *.lua  *.r  *.R
> *.scala  *.clj  *.cljs  *.zig  *.nim
> *.hbs  *.ejs  *.pug  *.jade  *.astro
> ```

> [accordion] Node default verify patterns
>
> Targets typical Node.js server entry points and API routes (applies once the cycle is enabled):
>
> ```
> server/**/*.{ts,js,mjs,cjs}
> src/server/**/*.{ts,js,mjs,cjs}
> backend/**/*.{ts,js,mjs,cjs}
> api/**/*.{ts,js,mjs,cjs}
> src/api/**/*.{ts,js,mjs,cjs}
> pages/api/**/*.{ts,js,mjs,cjs}
> app/api/**/*.{ts,js,mjs,cjs}
> routes/**/*.{ts,js,mjs,cjs}
> **/server.{ts,js,mjs,cjs}
> ```

> [accordion] Python default verify patterns
>
> Targets typical Python server entry points, web-framework modules, and WSGI/ASGI apps (applies once the cycle is enabled):
>
> ```
> server/**/*.py
> src/server/**/*.py
> backend/**/*.py
> api/**/*.py
> src/api/**/*.py
> app/**/*.py
> src/app/**/*.py
> routes/**/*.py
> services/**/*.py
> **/views.py  **/urls.py  **/models.py  **/tasks.py
> **/app.py  **/main.py  **/server.py
> **/wsgi.py  **/asgi.py
> ```

> [accordion] Backend default verify patterns
>
> Multi-language coverage of common server-side directories (applies once the cycle is enabled). The `{...}` extension set is `ts,js,mjs,cjs,py,go,java,rb,cs,rs,kt,scala,ex,exs,php,clj`:
>
> ```
> server/**/*.{…}
> src/server/**/*.{…}
> backend/**/*.{…}
> api/**/*.{…}
> src/api/**/*.{…}
> pages/api/**/*.{ts,js,mjs,cjs}
> app/api/**/*.{ts,js,mjs,cjs}
> routes/**/*.{…}
> controllers/**/*.{…}
> handlers/**/*.{…}
> services/**/*.{…}
> **/server.{…}
> **/main.{go,py,java,rb,kt,scala}
> ```

> [accordion] Android default verify patterns
>
> Covers standard Android project layouts: Gradle modules, Kotlin/Java source trees, and resources (applies once the cycle is enabled):
>
> ```
> android/**/*.{kt,java}
> app/src/**/*.{kt,java}
> mobile/**/*.{kt,java}
> src/main/kotlin/**/*.kt
> src/main/java/**/*.java
> **/*.{kt,java}
> **/res/**/*.xml
> **/AndroidManifest.xml
> ```

> [accordion] Terminal default verify patterns
>
> Covers CLI entrypoints, command trees, and shell scripts (applies once the cycle is enabled). Note these are **extension-scoped** - a `README.md` or a fixture inside `cli/` doesn't activate the cycle:
>
> ```
> cli/**/*.{ts,js,mjs,cjs,py,go,rs,rb,java,kt}
> **/cli/**/*.{ts,js,mjs,cjs,py,go,rs,rb,java,kt}
> cmd/**/*.{go,ts,js,mjs,cjs,py,rs}
> **/cmd/**/*.{go,ts,js,mjs,cjs,py,rs}
> **/commands/**/*.{ts,js,mjs,cjs,py,go,rs,rb}
> bin/**
> **/bin/**/*.{ts,js,mjs,cjs,py,go,rs,rb,sh}
> **/cli.{ts,js,mjs,cjs,py,go,rs,rb}
> **/main.{go,rs}
> **/*.{sh,bash,zsh,fish}
> ```
>
> `bin/**` is the one deliberately unscoped entry - a top-level `bin/` holds executables that often carry no extension at all.

> [!NOTE]
>
> These defaults are defined in the CLI (not written into `config.json`) and may grow with new CLI versions. Setting `verifyPatterns` replaces the list for that cycle; `additionalVerifyPatterns` appends to it. The only built-in **skip** list is the always-on test-file exclusion baked into [`ignoredVerifyPatterns`](#core-options) (`**/*.spec.*`, `**/*.test.*`, `**/__tests__/**`, `**/__mocks__/**`, `**/test_*.py`, `**/*_test.py`, `**/tests/**`, `**/conftest.py`); anything you add to `ignoredVerifyPatterns` is unioned on top. Non-code files simply don't match the patterns above.

> [!NOTE]
>
> Prefer the [`ironbee browser` / `node` / `python` / `backend` / `android` / `terminal` commands](https://docs.ironbee.ai/cli/guides/verification#enable-or-disable-a-platform) for turning cycles on and off; they write `<cycle>.enable` and re-render artifacts for you. Reach for `verifyPatterns` only when you need to change *which files* a cycle covers.

```json theme={null}
{
  "browser": {
    "additionalVerifyPatterns": ["*.mdx"]
  },
  "backend": {
    "verifyPatterns": ["api/**/*.go", "controllers/**/*.java"]
  }
}
```

***

## Verification context

Controls the [path-scoped verification guidance](https://docs.ironbee.ai/cli/guides/verification-context.md) IronBee injects from `.ironbee/VERIFICATION.md` files. On by default; these keys are **read live** at verification time, so changes take effect on the next session without re-rendering artifacts.

| Key | Type | Default | Description |
| - | - | - | - |
| `verification.context.enable` | `boolean` | `true` | Master switch. When the first verification tool call of a cycle fires, the relevant `.ironbee/VERIFICATION.md` files for the changed paths are injected into the agent's context. Advisory only, never gates. Opt out with `false`. |
| `verification.context.source` | `string` | `"git"` | Where the changed-path set comes from. `"git"` = working tree (staged + unstaged + untracked) ∪ the last `commitDepth` commits, with an `actions.jsonl` fallback when the project isn't a git repo. `"actions"` = IronBee's own `file_change` events only (no git subprocess). |
| `verification.context.commitDepth` | `number` | `1` | How many recent commits join the working tree for the `git` source. `0` = uncommitted work only. Ignored when `source` is `"actions"`. |
| `verification.context.maxBytes` | `number` | `65536` | Aggregate cap (64 KB) on the injected text. Past the cap, the least-specific (root-side) guidance is dropped first, keeping area-specific docs. |
| `verification.context.message` | `string` | *(unset)* | A custom instruction injected into **every** verification cycle, independent of which files changed - so it reaches the verifier even on a manual no-change verify (where the path-scoped `VERIFICATION.md` injection is empty). Two forms: literal inline text, or a `file:<path>` reference whose contents are read (path relative to the project dir; a leading `~` expands to your home dir). Rendered first and **never truncated** (it reserves its bytes off the `maxBytes` budget). Layered across global / project / local. |

```json theme={null}
{
  "verification": {
    "context": {
      "commitDepth": 0,
      "message": "Always confirm the health endpoint returns 200 before passing."
    }
  }
}
```

> [!NOTE]
>
> Earlier CLI versions used a top-level `verificationContext.*` namespace. These keys now live under `verification.context.*`; update any scripts or committed config that still reference the old names.

***

## Service identity

The `service` section is the CLI's **shared identity**: one credential and one stage selector that every IronBee service - the event-ingest collector, the read-side API (used by [`ironbee verify`](https://docs.ironbee.ai/cli/guides/verification-jobs) and the o11y trace tools), and the Console links - resolves from. [`ironbee login`](https://docs.ironbee.ai/cli/guides/authentication) writes it for you; you'd only set it by hand to self-host or to run in CI. See [Authentication](https://docs.ironbee.ai/cli/guides/authentication.md) for the difference between the two credentials.

| Key | Type | Default | Description |
| - | - | - | - |
| `service.domain` | `string` | `ironbee.ai` | The single **stage selector**. Every service URL derives from it when not set explicitly: the collector at `collector.service.<domain>`, the API at `api.service.<domain>`, the Console at `console.<domain>`. `ironbee login` persists the domain you authenticated against when the hosts are standard-shaped (a non-standard, self-hosted deployment keeps explicit URLs instead). Env: `IRONBEE_SERVICE_DOMAIN`. |
| `service.oauthToken` | `string` | *(unset)* | Personal OAuth access token written by `ironbee login`. The CLI's default credential, shared by the collector and the API. Env: `IRONBEE_SERVICE_OAUTH_TOKEN`. |
| `service.apiKey` | `string` | *(unset)* | Account API key, used for CI and machine-to-machine. When both credentials are set, the OAuth token is used. Env: `IRONBEE_SERVICE_API_KEY`. |
| `api.url` | `string` | derived: `https://api.service.<domain>` | Explicit override for the read-side API base URL ([`ironbee verify`](https://docs.ironbee.ai/cli/guides/verification-jobs), trace lookups). Rarely set - `service.domain` covers the normal cases. |

> [!NOTE]
>
> Older configs kept the credential under `collector.oauthToken` / `collector.apiKey`. Those keys (and their `IRONBEE_OAUTH_TOKEN` / `IRONBEE_API_KEY` env vars) still work as **read fallbacks**, so nothing breaks - but new logins write `service.*`, and the `service.*` keys win when both are present.

The credentials go only in the global config or the [personal file](#the-personal-file); the project and local layers refuse them. [`ironbee review`](https://docs.ironbee.ai/cli/guides/code-review#where-the-review-goes-and-as-whom) reads the credentials, `service.domain`, `api.url`, `collector.url` and `console.url` only from a flag, the environment, the personal file or the global config. When you set an endpoint in the project or local layer, `config set` notes that `ironbee review` won't read it there.

***

## Collector

The collector is what ships your session data to the IronBee Console. Its endpoint and credential come from the [`service` section](#service-identity) above; the keys here tune delivery (and carry the legacy credential fallbacks).

| Key | Type | Default | Description |
| - | - | - | - |
| `collector.url` | `string` | derived: `https://collector.service.<domain>` | Explicit endpoint override. Normally unset - it derives from `service.domain`. |
| `collector.oauthToken` | `string` | *(unset)* | **Deprecated read fallback** for `service.oauthToken` (configs written before the `service` section). Can come from `IRONBEE_OAUTH_TOKEN` instead. |
| `collector.apiKey` | `string` | *(unset)* | **Deprecated read fallback** for `service.apiKey`. Can come from `IRONBEE_API_KEY` instead. |
| `collector.enable` | `boolean` | implicit `true` when a credential is set | Set `false` to suspend sending while keeping credentials around. The collector activates on the **presence of a credential** (`service.*` preferred, `collector.*` fallback) - the URL always resolves via `service.domain`. |
| `collector.batchSize` | `number` | `100` | Max events per POST. |

***

## Code review

These keys tune [`ironbee review`](https://docs.ironbee.ai/cli/guides/code-review). None of them is artifact-affecting.

| Key | Type | Default | Description |
| - | - | - | - |
| `review.exclude` | `string[]` | `[]` | Paths that never leave your machine, deletions included. `*` matches within a segment and `**` across segments; a trailing `/` names a folder and everything below it, as in `.gitignore`. The union of every layer and of every tracked nested `.ironbee/config.json`, each matched under its own folder. `--exclude` adds patterns for one run. See [Exclude paths](https://docs.ironbee.ai/cli/guides/code-review.md#exclude-paths). |
| `review.includeUnstaged` | `boolean` | `false` | Also send unstaged edits to tracked files. Read only from the personal file or the global config; the project and local layers refuse it. `--include-unstaged` turns it on for one run. |
| `review.includeUntracked` | `boolean` | `false` | Also send untracked files (never ignored ones). Read only from the personal file or the global config, like `review.includeUnstaged`. `--include-untracked` turns it on for one run. |
| `review.fix.maxRounds` | `number` | `5` | The most rounds of review and fix one [`/ironbee-review fix loop`](https://docs.ironbee.ai/cli/guides/code-review#from-a-coding-agent) makes. An integer from 1 to 20: `config set` and the TUI refuse anything else, and a hand-edited value out of range is ignored, with a warning on a terminal. `rounds:<n>` on the command overrides it for one run. Set it in the global, project or local layer, not the personal file. |
| `review.settings.depth` | `string` | *(unset)* | `auto`, `quick`, `standard` or `deep`. Flag: `--depth`. |
| `review.settings.focusAreas` | `string[]` | *(unset)* | `security`, `editorial`. Flag: `--focus`. |
| `review.settings.extraChecks` | `string[]` | *(unset)* | `lint`, `style`, `defensive`, `tests`, `cleanup`, `pitfalls`. Flag: `--checks`. |
| `review.settings.language` | `string` | *(unset)* | The language the review is written in. Flag: `--language`. |
| `review.settings.summary` | `boolean` | *(unset, on)* | Whether the review writes a summary. Flag: `--no-summary`. |
| `review.settings.suggestedFixes` | `boolean` | *(unset, on)* | Whether findings come with suggested fixes. Flag: `--no-fixes`. |
| `review.settings.diagrams` | `boolean` | *(unset)* | Whether findings come with diagrams. Flag: `--no-diagrams`. |
| `review.settings.repositoryKnowledge` | `boolean` | *(unset)* | Whether the review reads the repository's knowledge. Flag: `--no-knowledge`. |

A `review.settings.*` key resolves on its own: the flag, then the personal file, then the local, project and global layers. A setting set nowhere isn't sent, so the repository's setting, the account's or the default applies.

### The personal file

The personal file holds one repository's settings outside the checkout, at `~/.ironbee/projects/<token>/personal.json`. Every linked worktree of the repository shares it. Write it with `ironbee config set --personal`, or with **`P`** in the [TUI](https://docs.ironbee.ai/cli/guides/interactive-mode.md)'s Configuration area. `P` always targets the remote the branch is pushed to; for another remote, use `--remote <name>`. With several remotes and none chosen, the write asks for `--remote`.

* It holds only what `ironbee review` reads: the two switches, the endpoints, the credentials, `review.exclude`, `review.settings.*` and `params.*`.
* Only `ironbee review` and `ironbee credits` read it. `ironbee verify`, the hooks that send your sessions to the Collector, and the devtools servers don't, so a credential stored only in the personal file doesn't reach them.
* It records the remote's `owner/repo`, a gitlab.com project's full path, or a bitbucket.org repository's `workspace/repo_slug`, and the repository it was written for. `ironbee review` checks both on every read, and refuses a file written for another repository, or one that, like a folder above it under `~/.ironbee`, isn't owned by you or is world-writable.
* It's written readable by you only (`0600`, in a `0700` folder).
* There's one per repository, for one `owner/repo`, GitLab project or Bitbucket repository. Writing it for another repository's remote, or over a file it can't use (not valid JSON, no repository recorded, or failing the ownership check), replaces the file rather than merging into it, and the CLI says so. Its other values, a stored credential included, are dropped.

***

## Telemetry

| Key | Type | Default | Description |
| - | - | - | - |
| `telemetry.enable` | `boolean` | `true` | [Anonymous PostHog product analytics](https://docs.ironbee.ai/cli/advanced/telemetry.md) for the CLI itself (separate from the collector pipeline). Opt out with `false`, also turns off telemetry in the devtools MCP servers. Equivalent to `ironbee telemetry disable`. |

***

## Privacy

| Key | Type | Default | Description |
| - | - | - | - |
| `privacy.enable` | `boolean` | `false` | [Privacy mode](https://docs.ironbee.ai/cli/advanced/privacy.md) is a single cross-cutting switch (all cycles) that redacts sensitive payloads from what the devtools MCP servers ship to the collector. **Opt-in, default off.** When `true`, injects `COLLECTOR_EVENTS_TOOL_DETAILS_ENABLE=false` (tool input/output detail) and `COLLECTOR_ARTIFACTS_ENABLE=false` (screenshots, recordings) into the devtools MCP env. Devtools-side only and orthogonal to `telemetry` and `collector`. Equivalent to `ironbee privacy enable`. |

[DevTools env overrides](#devtools-mcp-overrides) are applied *after* the privacy flags, so set `ironbeeDevTools.env.COLLECTOR_ARTIFACTS_ENABLE` / `COLLECTOR_EVENTS_TOOL_DETAILS_ENABLE` back to `"true"` to let one channel through while privacy mode is on.

***

## Issue-tracker integrations

Connect Jira, Linear, or GitHub Issues - see the [Issue Tracking guide](https://docs.ironbee.ai/cli/guides/issue-tracking.md) for the setup flows (`ironbee integrations <provider> setup`) and what the integration does. A provider activates by **configuration presence** (a configured credential turns it on; GitHub is on whenever the `gh` CLI is authenticated); its `enable` key is an opt-out kill-switch.

> [!WARNING]
>
> **Secrets belong in the global config** (`~/.ironbee/config.json`) - `setup` writes them there for you. Installed artifacts carry only a `${file:…}` reference to the global config, so no token is ever baked into a committed file. In CI, supply them via the [credential env vars](https://docs.ironbee.ai/cli/configuration/environment-variables.md#issue-tracker-credentials) instead.

### Jira

| Key | Type | Default | Description |
| - | - | - | - |
| `integrations.jira.baseUrl` | `string` | *(unset - integration off)* | Jira base URL (e.g. `https://acme.atlassian.net`). Not a secret - can be team-shared (project config) or per-user (global, where `setup` writes it). Required for the integration to be configured. |
| `integrations.jira.email` | `string` | *(unset)* | Jira **Cloud** identity, paired with `apiToken`. Per-user - keep it in the global config (Server/DC deployments leave it unset). |
| `integrations.jira.apiToken` | `string` | *(unset)* | Jira **Cloud** API token - **secret**, global config only. CI: `IRONBEE_JIRA_API_TOKEN`. |
| `integrations.jira.pat` | `string` | *(unset)* | Jira **Server/DC** personal access token - **secret**, global config only. CI: `IRONBEE_JIRA_PAT`. |
| `integrations.jira.deployment` | `string` | *(inferred)* | `cloud` or `server`. Inferred from the credential shape; set explicitly to pin. |
| `integrations.jira.defaultProject` | `string` | *(unset)* | Default Jira project key for creates and searches (e.g. `PROJ`). Committed. |
| `integrations.jira.projectKeys` | `string[]` | `[]` | Allow-list of issue-key prefixes accepted when [attributing issues](https://docs.ironbee.ai/cli/guides/issue-tracking.md#vcs-linkage-sessions-to-prs-and-issues) from branch/commit/PR text - kills `UTF-8` / `SHA-256`-style false positives. Read live. |
| `integrations.jira.writeEnabled` | `boolean` | `false` | Whether the [write tiers](https://docs.ironbee.ai/cli/guides/issue-tracking.md#read-only-by-default-write-gating) (comment, attach, transition, create/link, report) are enabled. Read-only integrations still read, search, and attribute. |
| `integrations.jira.enable` | `boolean` | `true` *(when configured)* | Opt-out kill-switch - `false` suspends the integration without deleting its config. Equivalent to `ironbee integrations jira disable`. |

### Linear

| Key | Type | Default | Description |
| - | - | - | - |
| `integrations.linear.apiKey` | `string` | *(unset - integration off)* | Linear API key (`lin_api_…`) - **secret**, global config only. CI: `IRONBEE_LINEAR_API_KEY`. |
| `integrations.linear.oauth` | `boolean` | `false` | Set `true` when `apiKey` is an **OAuth access token** rather than a personal key (changes how it's sent). |
| `integrations.linear.defaultTeam` | `string` | *(unset)* | Default Linear team key for creates and searches (e.g. `ENG`). Committed. |
| `integrations.linear.teamKeys` | `string[]` | `[]` | Allow-list of issue-key prefixes for attribution - same role as Jira's `projectKeys` (also disambiguates the two when both are configured). Read live. |
| `integrations.linear.workspace` | `string` | *(unset)* | Workspace URL slug (the `acme` in `linear.app/acme`), used to build issue browse links in the attribution data. Unset → no browse URL (graceful). |
| `integrations.linear.baseUrl` | `string` | Linear's cloud GraphQL endpoint | Rare override for a proxy endpoint. |
| `integrations.linear.writeEnabled` | `boolean` | `false` | Same write gating as Jira. |
| `integrations.linear.enable` | `boolean` | `true` *(when configured)* | Opt-out kill-switch. Equivalent to `ironbee integrations linear disable`. |

### GitHub Issues

| Key | Type | Default | Description |
| - | - | - | - |
| `integrations.github.enable` | `boolean` | `true` *(when `gh` is authenticated)* | Opt-out kill-switch. GitHub is driven through the `gh` CLI and auto-activates when `gh` is installed and authenticated - no credential is stored. `false` suspends it regardless. |
| `integrations.github.writeEnabled` | `boolean` | `false` | Whether the write operations (`gh issue comment` / `close` / `edit`, the verification report) are allowed. Self-enforced by the agent (`gh` is always shell-reachable), unlike Jira/Linear's mechanical gate. Read live. |

***

## VCS linkage

Links each agent turn to the pull request it produced, the merge request on gitlab.com, or the pull request on bitbucket.org, and the issues the turn is attributed to, such as those a GitHub PR closes - the join key that makes verification data attributable to an issue instead of an opaque session ID. It runs in every mode (enforce / assist / monitoring-only) and auto-enables whenever a collector is configured. See [Issue Tracking → VCS linkage](https://docs.ironbee.ai/cli/guides/issue-tracking.md#vcs-linkage-sessions-to-prs-and-issues).

| Key | Type | Default | Description |
| - | - | - | - |
| `vcs.enable` | `boolean` | implicit `true` when a collector is configured | Master switch for the linkage - the git-ref stamp, PR resolution, issue attribution, and the `vcs_link` events. **Note:** it sends repository and *branch names* to the Collector; branch names can carry sensitive text. Independent of [privacy mode](https://docs.ironbee.ai/cli/advanced/privacy.md). Read live. |
| `vcs.issueTtlSeconds` | `number` | `600` | Cache TTL for successful / not-found resolutions. Short - a PR can be opened or an issue transitioned at any moment. |
| `vcs.resolveTtlSeconds` | `number` | `3600` | Cache TTL for resolutions that can't improve on retry (no token, no remote, rejected credentials). |
| `vcs.stampDirty` | `boolean` | `false` | Probe the working tree for uncommitted changes during the git-ref stamp. Off by default - it's the most expensive part of the stamp and scales with repo size. |
| `vcs.timeoutMs` | `number` | `5000` | Per-request timeout for PR / issue resolution (always in a detached background worker, never a blocking hook). Clamped to `[1000, 60000]`. |

***

## Web console

| Key | Type | Default | Description |
| - | - | - | - |
| `console.url` | `string` | derived: `https://console.<domain>` | Explicit Console base URL override, used to build the `🔗 View in IronBee` timeline deep-links in [issue-tracker reports](https://docs.ironbee.ai/cli/guides/issue-tracking.md#using-it-ironbee-issue-track). Normally unset - it derives from [`service.domain`](#service-identity), which `ironbee login` persists, so self-hosted consoles link correctly. Read live. |

***

## File change capture

| Key | Type | Default | Description |
| - | - | - | - |
| `fileChange.captureChangeset` | `boolean` | `false` | When `true`, each `file_change` event carries a hunks-only unified diff. Off by default (events stay metadata-only). |
| `fileChange.maxChangesetBytes` | `number` | `65536` | Hard cap (64 KB) on the diff string, larger diffs are truncated with a footer. |

***

## Claude (Claude Code only)

Install-time behaviors for Claude Code: two keep the verifier working with Claude Code's own host-side guardrails, and one controls the in-app view. See [Claude Code](https://docs.ironbee.ai/cli/clients/claude-code.md).

| Key | Type | Default | Description |
| - | - | - | - |
| `claude.mod.enable` | `boolean` | *(unset - on when Claude Code 2.1.287+ is detected)* | Whether `ironbee install` writes the [in-app view](https://docs.ironbee.ai/cli/clients/claude-code.md#in-app-view), a Claude Code mod in `.claude/skills/ironbee/` (gitignored) that draws a line above the prompt and the `/ironbee` pane. Unset renders it only when install detects Claude Code 2.1.287 or later. `false` never renders it and removes it on the next install. `true` renders it even when the version can't be detected, as with the desktop app. The view only displays; verification never depends on it. Enforce and assist modes only. Takes effect on the next `ironbee install`. Claude-only. |
| `claude.autoModeAllowlist.enable` | `boolean` | `true` | Whether IronBee writes the [auto-mode allowlist carve-out](https://docs.ironbee.ai/cli/clients/claude-code.md#auto-mode-and-the-verifier) for the verifier into `.claude/settings.local.json`. Claude Code's auto-mode "Content Integrity" classifier can false-positive on IronBee's legitimate verdict submissions; when enabled (default), install adds one narrow rule that exempts **only** that command from the block (every other auto-mode protection stays in force). Written only when verification is active (enforce/assist) and inert when the host isn't in auto mode. Opt out with `false` - takes effect on the next `ironbee install`. Claude-only. |
| `claude.trustWorkspace.enable` | `boolean` | `true` | Whether `ironbee install` marks the project [trusted](https://docs.ironbee.ai/cli/clients/claude-code.md#workspace-trust) in Claude Code's machine-global `~/.claude.json` when it isn't already. Claude Code 2.1.x ignores a project's committed `permissions.allow` (the devtools + `Bash(ironbee *)` entries IronBee writes) until the workspace is trusted, and the trust dialog doesn't re-appear once onboarding has been seen - so without this the entries stay silently disabled and the agent gets prompted on every devtools/`ironbee` call. Best-effort and idempotent: it only ever flips a missing/false flag to `true` and never clobbers other `~/.claude.json` content. Opt out with `false`. Claude-only. |

***

## Codex (Codex CLI only)

Controls how the Codex verification cycle is driven. Manage with `ironbee codex verifier mode <sub-agent|main-agent>`. See [Codex → How verification is delivered](https://docs.ironbee.ai/cli/clients/codex.md#how-verification-is-delivered).

| Key | Type | Default | Description |
| - | - | - | - |
| `codex.verifier.mode` | `string` | `sub-agent` | How the Codex verification cycle runs. `"sub-agent"` (default) delegates to the [`ironbee-verifier`](https://docs.ironbee.ai/cli/clients/codex) custom agent (per-agent MCP, slim delegation skill/rule/command), keeping the heavy devtools output out of the main conversation. `"main-agent"` makes the **main** agent drive the devtools tools directly (session-level MCP server, no verifier sub-agent, inline skill/rule/command) - the Cursor-style fallback for when Codex's sub-agent machinery regresses. In `sub-agent` mode the devtools server is also written at session level in `.codex/config.toml`, because Codex 0.154 and later ignore the MCP servers in an agent file. Re-renders the Codex client. Codex-only. |

***

## Devtools MCP overrides

All cycles are served by a single **`ironbee-devtools`** compose MCP server, customized via the `ironbeeDevTools` keys:

| Key | Description |
| - | - |
| `ironbeeDevTools.env` | Extra env vars merged into the default MCP server entry. |
| `ironbeeDevTools.mcp` | Full replacement of the MCP server config, supply your own `command`+`args` (stdio) or `url` (HTTP), e.g. to point at a local devtools build. |

```json theme={null}
{
  "ironbeeDevTools": {
    "env": { "BROWSER_HEADLESS_ENABLE": "true" }
  }
}
```

> [!NOTE]
>
> IronBee always sets its own invariants (`PLATFORM=compose`, `COMPOSE_PLATFORMS`, metadata flags) last; these can't be overridden.

> [!NOTE]
>
> The legacy per-cycle keys (`browserDevTools`, `nodeDevTools`, `pythonDevTools`, `backendDevTools`, `androidDevTools`, `terminalDevTools`) still exist for back-compat but **no longer feed the compose server** - use `ironbeeDevTools` to customize the one server that serves every cycle.

***

## Automatic pipeline keys

These sections auto-enable when a collector is configured and rarely need manual tuning. Browse them with `ironbee config list` or the [TUI](https://docs.ironbee.ai/cli/guides/interactive-mode.md) Configuration area:

* **`recording:`** session recording for the browser and Android cycles (`recording.enable`); the node, python, backend, and terminal cycles never trigger it.
* **`jobQueue:`** the file-backed background queue that feeds the collector: `jobQueue.enable`, and the flush thresholds `jobQueue.autoFlushSizeBytes` (default `32768`) and `jobQueue.autoFlushIntervalSeconds` (default `60`).

***

## Common setups

### Ignore extra files

Test files (`**/*.spec.*`, `**/*.test.*`, `**/__tests__/**`, `**/__mocks__/**`, `**/test_*.py`, `**/*_test.py`, `**/tests/**`, `**/conftest.py`) are **excluded by default** - you don't need to list them. Add `ignoredVerifyPatterns` only to skip *more* paths (e.g. generated code, fixtures); your entries are unioned with the built-in test-file defaults:

```json theme={null}
{
  "ignoredVerifyPatterns": ["**/generated/**", "**/*.gen.ts", "fixtures/**"]
}
```

### Backend-only project (no browser cycle)

```json theme={null}
{
  "browser": { "enable": false },
  "backend": { "enable": true }
}
```

Or use the CLI: `ironbee browser disable && ironbee backend enable`. With the browser off and no `verifyPatterns` of its own, the backend cycle watches every file in its languages: `ts`, `tsx`, `js`, `jsx`, `mjs`, `cjs`, `py`, `go`, `java`, `rb`, `cs`, `rs`, `kt`, `scala`, `ex`, `exs`, `php` and `clj`.

### Monitoring only (no enforcement)

```json theme={null}
{
  "verification": { "enable": false }
}
```

### Assist mode (verify on demand, never gated)

```json theme={null}
{
  "verification": { "auto": false }
}
```

Or use the CLI: `ironbee verification auto disable`.

### Capture code diffs on file-change events

```json theme={null}
{
  "fileChange": { "captureChangeset": true }
}
```

***

## What's next?

> [card] [Environment variables](https://docs.ironbee.ai/cli/configuration/environment-variables.md)
>
> Overrides that take precedence over the config files.

> [card] [Runtime files](https://docs.ironbee.ai/cli/advanced/runtime-files.md)
>
> Where these config files live and what else IronBee writes to disk.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.