Environment variables

Most configuration lives in config files, but a few settings can be supplied via environment variables, handy for CI runners, ephemeral shells, and secrets you don’t want to commit.

Common

Variable	Effect
`IRONBEE_SERVICE_API_KEY`	Supplies `service.apiKey` (the shared account API key) without committing it. Takes precedence over every config layer. The credential of choice for CI and the GitHub Action.
`IRONBEE_SERVICE_OAUTH_TOKEN`	Supplies `service.oauthToken` (the personal token from `ironbee login`) without committing it. When both credentials are set, the OAuth token wins.
`IRONBEE_SERVICE_DOMAIN`	Supplies `service.domain`, the stage selector every service URL derives from.
`IRONBEE_API_KEY`	Legacy - supplies the deprecated `collector.apiKey` fallback, which is read only when `service.apiKey` is unset (a recent `ironbee login` writes `service.*`, which then wins). One exception: `ironbee verify` reads it as a deliberate high-priority override, although an OAuth token still wins.
`IRONBEE_OAUTH_TOKEN`	Legacy - supplies the deprecated `collector.oauthToken` fallback; same caveat as above.
`IRONBEE_TELEMETRY`	Set to `false` to turn off anonymous CLI telemetry for this shell/run, a per-session alternative to the `telemetry.enable` config key.
`IRONBEE_LOG_LEVEL`	Logging verbosity: `debug`, `info` (default), `warn` or `error`. Set to `debug` to see detailed output when troubleshooting.

An override set to an empty string counts as unset.

# CI: provide the API key from a secret, no file commit
export IRONBEE_SERVICE_API_KEY=sk-...
ironbee install --mode enforce --yes

Because these override the files, a merged read (ironbee config get service.apiKey) returns the env value. A layer-scoped read (--project / --global / --local) bypasses env and shows only what’s on disk.

Verification jobs

ironbee verify - the cloud verification-job runner - reads two extra overrides of its own, plus the GitHub Actions context:

Variable	Effect
`IRONBEE_ACCESS_TOKEN`	OAuth access token for the API, overriding `service.oauthToken`.
`IRONBEE_API_URL`	API base URL, overriding `api.url` (the `--api-url` flag wins over both).
`GITHUB_ACTIONS`	When exactly `"true"`, a created job is declared with the `github_actions` trigger (Console visibility only) and secret-header values are masked with `::add-mask::`.
`GITHUB_REPOSITORY` / `GITHUB_SHA` / `GITHUB_REF`	Fill the run’s repository binding: the `owner/repo`, the authoritative commit, and the pull-request number on a PR run.

Issue-tracker credentials

The issue-tracker integrations normally keep their secrets in your global config (~/.ironbee/config.json, written by ironbee integrations <provider> setup). In CI - or anywhere you’d rather source them from a vault - supply them via env instead. Like the collector credentials, these take precedence over every config layer:

Variable	Effect
`IRONBEE_JIRA_API_TOKEN`	Supplies `integrations.jira.apiToken` (Jira Cloud API token). Combine with a file-set `integrations.jira.baseUrl` + `email` for a complete config.
`IRONBEE_JIRA_PAT`	Supplies `integrations.jira.pat` (Jira Server/DC personal access token).
`IRONBEE_LINEAR_API_KEY`	Supplies `integrations.linear.apiKey` (Linear personal API key or OAuth token).

GitHub needs no credential variable - it rides the gh CLI’s own auth (GitHub Actions ships a GH_TOKEN).

Config placeholder bridges

Config placeholders let a committed config carry references that resolve from the environment - the way to override a team default per developer or per CI run without editing a file:

Variable pattern	Feeds	Notes
`IRONBEE_PARAM_<NAME>`	`${param:<name>}` references	Overrides the `params` block for that key. `<name>` maps case-insensitively - `IRONBEE_PARAM_API_URL` fills `${param:api_url}`.
`IRONBEE_ENV_<NAME>`	`${env:<name>}` references	The only environment source a `${env:}` reference can read. `IRONBEE_ENV_STAGING_URL` fills `${env:staging_url}`.

# CI: override a committed ${param:api_url} for this run
export IRONBEE_PARAM_API_URL=https://api.staging.internal

The IRONBEE_PARAM_* / IRONBEE_ENV_* prefixes are reserved for placeholder input - the implied prefix means arbitrary environment variables (secrets, tokens) are structurally unreachable from config text. An empty value counts as unset (the reference falls through to its :- default). IronBee’s own operational env vars never use these prefixes.

Project directory resolution

When a hook or command needs to know which project it’s acting on, IronBee resolves the directory in this order:

The client’s own variable - CLAUDE_PROJECT_DIR (Claude Code), CURSOR_PROJECT_DIR (Cursor), or CODEX_PROJECT_DIR (Codex) - set automatically by the host
IRONBEE_PROJECT_DIR, an explicit override you can set
The current working directory

You normally don’t set these yourself; the AI client provides them. IRONBEE_PROJECT_DIR is the escape hatch for scripted or non-standard setups.

Advanced

Rarely needed, mostly for internal wiring and test harnesses:

Variable	Effect
`IRONBEE_CLIENT`	Tells a hook runner which client it’s acting as, when the hook command doesn’t pass `--client`. The installed hooks pass `--client`, so this is only a fallback.
`IRONBEE_RUNTIME_LOCATION`	Overrides `runtime.location` for this process - `external` (default, per-session data under `~/.ironbee/projects/<token>/`) or `in-project` (`<project>/.ironbee/sessions/`). Takes precedence over the config layers; mainly used by the test suite.
`IRONBEE_BIN`	Overrides the path to the `ironbee` binary used when spawning background workers.
`IRONBEE_COLLECTOR`	Set to `false` to disable Collector sends entirely (used by the test harness).
`IRONBEE_UPDATE_CHECK`	Set to `false` to skip the npm-registry version check (and its update banner) that runs after a command. Worth setting for scripts that spawn `ironbee` in a loop - each check keeps the event loop alive for up to a 3 s round trip.
`IRONBEE_DEVTOOLS_MCP`	Points the `ironbee-devtools` MCP server at your own entry without writing an `ironbeeDevTools.mcp` block. A full JSON object: `{"command": "...", "args": [...], "env": {...}}`. Read at install / re-render time, so the resolved command is baked into the artifact - export it when you run `ironbee install`. Wins over the config block; IronBee’s invariant env is still layered on top. Mainly for editor extensions that bundle DevTools.
`IRONBEE_DEVTOOLS_ENTRY`	Simpler form of the above: a path, rendered as `node <path>`. Used only when `IRONBEE_DEVTOOLS_MCP` is unset or malformed.
`IRONBEE_VCS_STAMP_BUDGET_MS`	Total budget (ms, default `3000`) for the git-ref stamp taken at the start of each agent turn. An ops escape hatch - raise it on a heavily loaded machine where the stamp would otherwise go partial and drop `repo`/`host` from the VCS linkage.
`IRONBEE_CURSOR_USER_DIR`	Overrides where IronBee looks for Cursor’s local user data (the read-only `state.vscdb` store it reads the signed-in user’s email from, for event attribution). Defaults to Cursor’s standard per-OS location; mainly for non-standard installs and tests.
`IRONBEE_NO_AUTO_RERENDER`	Disables the auto re-render of registered projects after a structure-changing upgrade. A kill switch for CI and locked-down machines.
`IRONBEE_NO_PREFETCH`	Global kill-switch for the devtools prefetch - any value other than empty/`0`/`false` skips the npx cache warm on `install`, upgrade re-renders, `ironbee browser enable`, and `ironbee devtools prefetch`.
`IRONBEE_GH_AUTHENTICATED`	Forces the GitHub issue-tracker activation probe deterministically - `1`/`true` = active, `0`/`false` = inactive - bypassing the `gh auth status` check. For CI/test environments where a deterministic result is wanted. `integrations.github.enable: false` still suspends it regardless.
`CI`	When truthy (`true` / `1`), also short-circuits the upgrade auto re-render - belt-and-suspenders so a CI that allocates a pseudo-TTY can’t hang on the confirmation prompt.

Get started

Concepts

Guides

Configuration

Advanced

AI clients

Environment variables

Common

Verification jobs

Issue-tracker credentials

Config placeholder bridges

Project directory resolution

Advanced

What’s next?

Configuration

Runtime files

​Common

​Verification jobs

​Issue-tracker credentials

​Config placeholder bridges

​Project directory resolution

​Advanced

​What’s next?

Configuration

Runtime files

Common

Verification jobs

Issue-tracker credentials

Config placeholder bridges

Project directory resolution

Advanced

What’s next?