> ## Documentation Index > Fetch the complete documentation index at: https://docs.plurai.ai/llms.txt > Use this file to discover all available pages before exploring further. # Environment variables > The environment variables that connect the plugin to the Plurai backend without a browser login, and that control its behavior. This page lists every variable you may set. You need none of them to get started: the first Plurai command signs you in through your browser and saves the login for you. The connection variables are for CI, a machine without a browser, or a backend other than the hosted one. > [!WARNING] > > Export variables in the shell that launches your coding agent. A project `.env` file is not read for the backend connection. Your coding agent reads these variables once, at session start, so **restart it after you change any of them**. ## Connect to the backend The plugin and the SDK find your backend and key in this order, and take the pair whole from one source: 1. `PLURAI_URL` and `PLURAI_TOKEN`, exported together. 2. The login saved in `~/.plurai/credentials.json` by `plurai login`, the browser sign-in the first Plurai command runs. | Variable | Default | Purpose | | - | - | - | | `PLURAI_URL` | unset, so the saved login is used | The backend's API root. With it set and no token, the browser login signs in to that backend. | | `PLURAI_TOKEN` | unset, so the saved login is used | An API key created in the Plurai dashboard. Set it only together with `PLURAI_URL`. | `` is the backend address Plurai gives you with your account. You don't need it when you sign in with your browser. ```bash theme={null} export PLURAI_URL=https:// PLURAI_TOKEN= claude ``` The two variables are one pair. Setting only one of them is an error that names the other, not a fallback to the saved login. A URL from one source with a token from the other is refused, because a key must only reach the backend it was issued for. When both the pair and a saved login exist, the exported pair wins. The URL must use `https`. Plain `http` is accepted only for a backend on your own machine (a loopback address), which needs no token. Plurai does not follow redirects. ### The saved login `plurai login` opens your browser, where you sign in or sign up, pick your organization and approve. The SDK then creates its own key and saves it in `~/.plurai/credentials.json` with mode `600`. The key is never shown, typed or copied. A key that has expired counts as no login: the next Plurai command signs you in again. ```bash theme={null} plurai login --status # the backend, organization, user, and the key's name and expiry; never the key plurai logout # revokes the key at the backend and removes the file ``` In your coding agent, `/harness-setup` signs you in again or shows the status. **No browser on this machine.** Create a key in the Plurai dashboard, then save it once in a terminal of your own: ```bash theme={null} python3 /scripts/plurai_login.py --url https:// ``` It asks for the key with echo off and writes the same file. The `--url` must be `https` under `*.plurai.ai`, or a loopback address. Reach any other backend with `PLURAI_URL` and `PLURAI_TOKEN` instead. Never paste a key into the chat: it would land in the transcript. ## What the plugin does with your key These rules hold whatever command the plugin runs: * **The key goes only to the backend it was issued for.** The plugin and the SDK send it only to the resolved backend's origin (scheme, host and port). A mock URL on another host, or on another local port, never receives it. * **A saved key goes only to the backend the saved login names.** Pointing the plugin at another backend does not hand it that key. * **The key is handed only to the installed SDK.** The plugin never runs a `plurai` program with your key unless an installed `plurai-simulation-sdk` package provides that exact file. A hand-built wrapper does not get the key. * **Files the scripts write stay in your project.** Output goes under the project directory, its `plurai_sim/` folder or the temp directory, never into places that run code on their own such as `.git`, `.claude`, `.vscode` or `site-packages`. Anything that runs as you, including the commands your coding agent runs, can read the saved login. The key is as safe as the commands you approve, so run `plurai logout` and sign in again if a session went wrong. ## Install the SDK | Variable | Purpose | | - | - | | `PLURAI_CHILD_PYTHON` | The Python interpreter that runs your agent during a Run, when your agent needs a different virtual environment from the runner, for example because its dependencies conflict. That environment needs your agent's dependencies and the `plurai` SDK. | ## Control the flow | Variable | Default | Purpose | | - | - | - | | `PLURAI_FLOW_HEARTBEAT` | unset | Set to `force` to keep the dropped-turn heartbeat under Claude Code's auto mode. Also add `CronCreate` to `permissions.allow`. See [Permissions](https://docs.plurai.ai/reference/permissions.md). | | `PLURAI_SIM_NONINTERACTIVE` | unset | Set to `1` when nobody is at the terminal, for example in CI. Every question takes its declared default, and anything only a person can supply stops the flow with a finding. Same as `workspace.run_driver: headless` in [`plurai.config.yaml`](https://docs.plurai.ai/reference/config#workspace). | ## Sandbox for Claude-based agents When your agent is built on the Claude Agent SDK, each scenario runs in a sandbox: your harness, expected answers, other scenarios and credentials can't be read or reached from the agent's shell. | Variable | Default | Purpose | | - | - | - | | `PLURAI_SANDBOX` | unset, which means the permissive profile | Set to `strict` for the tightest isolation: no network, no extra system services, nothing writable outside the scenario's own folders, and no toolchain reads under your home directory. Use it when your agent doesn't need the network. Any other value selects the permissive profile. | ## Record runs to your observability platform | Variable | Default | Purpose | | - | - | - | | `PLURAI_OBSERVABILITY` | unset, which means nothing is recorded | Set to `recording` to send Runs to your configured platform. `/simulation-run` sets it for you when you choose to record. | | `PLURAI_DISABLE_DOTENV` | unset | Set to `1` to stop the SDK from loading a `.env` file it finds above the current directory. | | `PLURAI_ENV_FILE` | the nearest `.env` above the current directory | The `.env` file the SDK loads. | Each platform is enabled with its own variables, such as `LANGSMITH__ENABLED` and `LANGSMITH__API_KEY`. Only one platform can be enabled at a time. See [Trace sources](https://docs.plurai.ai/integrations/trace-sources.md). ## Upload limits | Variable | Purpose | | - | - | | `PLURAI_INGEST_MAX_UNCOMPRESSED_BYTES` | The largest upload, uncompressed, the SDK lets leave your machine. Set it only when your backend uses a cap other than the default. The SDK checks it before uploading and names the largest files when an upload is too big. | ## Plugin behavior | Variable | Default | Purpose | | - | - | - | | `PLURAI_NO_UPDATE_NOTICE` | unset | Set to `1` to stop the once-a-day check for a newer plugin release. | | `PLURAI_NO_SUPPORT_REFS` | unset | Set to `1` to stop keeping the local log of install failures (`~/.plurai/support_refs.jsonl`). It is never sent anywhere. | | `PLURAI_STATE_HOME` | `~/.plurai` | Moves the plugin's local state folders. Your login, flow state and session pins stay in `~/.plurai`. | | `CLAUDE_CODE_GIT_BASH_PATH` | unset | Windows only: the path to Git Bash, if Claude Code can't find it. | ## Next steps > [card] [Permissions](https://docs.plurai.ai/reference/permissions.md) > > Run the flows under auto mode. > [card] [Troubleshooting](https://docs.plurai.ai/troubleshooting.md) > > Fix a failed sign-in or a wrong backend. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.