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

# Environment variables

> Every variable the SDK, CLI and MCP read, and what each one overrides.

> [!WARNING]
>
> **Environment credentials outrank the config file.** Signing out in the wizard clears the file, but an exported token still authenticates — no command can unset a variable in your parent shell.

## Connection

| Variable | Purpose |
| - | - |
| `PROBE_BASE_URL` | The API endpoint |
| `PROBE_TOKEN` | User token — the `/v1` surface |
| `PROBE_MCP_TOKEN` | Read-only token the MCP server prefers |
| `PROBE_INGEST_TOKEN` | Ingest token — the `/ingest` surface, and session capture |
| `PROBE_SERVICE_TOKEN` | Read-only service token (`probe_svc_...`) for machine callers |
| `PROBE_HMAC_SECRET` | Optional body-signature secret for passive push |
| `PROBE_AUTO_LOGIN` | `0` disables the inline browser approval on first use |
| `PROBE_CONFIG` / `PROBE_CONFIG_PATH` | Override the config file location |
| `PROBE_DASHBOARD_URL` | Where links in CLI output point |

## Scope

| Variable | Purpose |
| - | - |
| `PROBE_PROJECT` | Default project for commands that take one |
| `PROBE_WORKSPACE` | The workspace new projects go to (a slug or an id), overriding this computer's workspace (`probe workspace use`) |
| `PROBE_RUN_ID` | The run a child process should join. Set by `probe exec` |
| `PROBE_RUN_EPOCH` | Guards against joining a stale run. Set by `probe exec` |
| `PROBE_PARENT_RUN` | Parent run for a child run |
| `PROBE_PARENT_RELATION` | How the child relates to the parent |

## Delivery

| Variable | Purpose |
| - | - |
| `PROBE_MODE` | What `probe.init()` does: `online` (default), `offline` (record with no network; deliver later with `probe sync`) or `disabled` (a run that records nothing) |
| `PROBE_ASYNC` | `0` turns off queueing for `log`, `span add` and run-anchored `artifact add` |
| `PROBE_ASYNC_UPLOADS` | Whether artifact bytes upload in the background |
| `PROBE_SPOOL_DIR` / `PROBE_OUTBOX_DIR` | Where the durable write queue lives. See [the outbox](/cli/outbox.md) |
| `PROBE_OUTBOX_MAX_PENDING` | Cap on queued operations |
| `PROBE_OUTBOX_MIN_FREE_BYTES` | Refuse to queue below this free-space floor |
| `PROBE_OUTBOX_PRODUCER_ID` | Distinguishes producers sharing one queue |
| `PROBE_OUTBOX_TRANSIENT_BUDGET_SEC` | How long a write that keeps failing with a temporary error is retried before it is dead-lettered. A day by default |
| `PROBE_HEARTBEAT_SECONDS` | Run heartbeat interval. `<=0` disables |
| `PROBE_FINISH_TIMEOUT_SEC` | How long `finish()` waits for the flush |

> [!WARNING]
>
> On rented or preemptible compute, set `PROBE_SPOOL_DIR` to durable storage. A node that disappears takes an ephemeral queue — and every unsent write in it — with it.

## Capture

| Variable | Purpose |
| - | - |
| `PROBE_CODE_STORAGE` | `artifacts` (default, per-file rows) or `archive` (one tarball per run) |
| `PROBE_AUTO_SNAPSHOT` | `0` disables automatic code capture at run start |
| `PROBE_HW` | `0` disables hardware metrics |
| `PROBE_ENV_ALLOWLIST` | Environment variables allowed into the snapshot's environment record |
| `PROBE_SANDBOX_SNAPSHOT_BIN` | Path to the sandbox snapshot helper |
| `PROBE_EXPORT_INTERVAL_SEC` | `probe trial watch` polling interval |

> [!WARNING]
>
> `PROBE_ENV_ALLOWLIST` is an allowlist for a reason. Never widen it to something that would sweep credentials into a snapshot a whole team can read.

## Sessions and agents

| Variable | Purpose |
| - | - |
| `PROBE_AGENT` | Which coding agent this process is running under |
| `PROBE_SESSION_TRACKING` | Override the tracking default for this process |
| `PROBE_SESSION_STATE` | Override the switch state for this process |
| `PROBE_ATTRIBUTION` | How work is attributed — for example `backfill` |
| `PROBE_TAP_SOURCE` | Which agent's transcripts the tap reads |
| `PROBE_DEVICE_ID_PATH` | Where the device identity is stored |
| `PROBE_PLUGIN_ROOT` | Plugin installation root |
| `PROBE_PI_PACKAGE_ROOT` / `PROBE_PI_SESSION_ROOTS` / `PROBE_PI_TAP_TOKEN` | pi-specific paths and credential |
| `PROBE_KIMI_SESSIONS_DIR` / `PROBE_KIMI_TAP_TOKEN` | Kimi Code-specific path and credential |

## Capy

Capy runs in the cloud, so its variables live in two places: `PROBE_CAPY` on the Capy machine, the rest on the computer that captures your threads. See [Capy](/agents/capy.md).

| Variable | Purpose |
| - | - |
| `PROBE_CAPY` | Set to `1` in Capy's environment variables. Marks the CLI's calls and telemetry as coming from Capy, and `probe doctor` there reports Capy's own checks. It does not label runs on the server |
| `CAPY_API_KEY` | Your Capy API key, read by `probe capy connect`. `connect` stores it owner-only for the timer, and sends it to Capy's API only |
| `PROBE_CAPY_THREADS_DIR` | Where the local copies of your Capy threads go. Default `~/.local/state/probe/capy/threads` |
| `PROBE_CAPY_TAP_PLUGIN_DIR` | Capy's capture folder: the stored key, the capture credential and the sync record. Default `~/.local/state/probe/capy/probe-research-tap` |
| `PROBE_CAPY_TAP_TOKEN` | A capture credential for Capy, from the environment. The timer cannot see it, so when the credential comes only from here, `connect` installs no timer |

## MCP

| Variable | Purpose |
| - | - |
| `PROBE_MCP_TOKEN` | The read-only credential |
| `PROBE_MCP_WEB_CAPACITY` | Share of the worker pool the web tools may hold. A quarter by default |
| `PROBE_MCP_ANALYTICS` | MCP usage analytics |

## Diagnostics

| Variable | Purpose |
| - | - |
| `PROBE_DIAGNOSTICS` | Extra diagnostic output |
| `PROBE_TELEMETRY` / `PROBE_TELEMETRY_HOST` | Client telemetry, and where it goes |
| `PROBE_VERSION_CACHE` / `PROBE_VERSION_TTL` / `PROBE_VERSION_TIMEOUT` | Version-manifest caching for update checks |

## Also read

| Variable | Effect |
| - | - |
| `NO_COLOR` | Turns colour off everywhere, including `probe metrics plot` |
| `COLUMNS` | Terminal width for help output and plots |

## A CI baseline

```bash theme={null}
export PROBE_BASE_URL=https://api.research.prbe.ai
export PROBE_TOKEN=<a read+write credential>
export PROBE_AUTO_LOGIN=0
export PROBE_SPOOL_DIR="$CI_WORKSPACE/.probe-spool"
```


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