Skip to main content
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.
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.
<your-backend> is the backend address Plurai gives you with your account. You don’t need it when you sign in with your browser.
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.
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:
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

​
Control the flow

​
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.

​
Record runs to your observability platform

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.

​
Upload limits

​
Plugin behavior

​
Next steps

Permissions

Run the flows under auto mode.

Troubleshooting

Fix a failed sign-in or a wrong backend.