Ori Configuration

Ori has one set of settings and several ways to supply them. A setting is named the same everywhere, so the same name works in your shell, in a config file, and in an MDM profile. Pick the mechanism that matches who owns the decision, then use the reference at the bottom of this page for the settings themselves.

Ways to configure Ori

Your shell. Export a variable for the current session, or put it in your shell profile or process manager. Good for one person on one machine.
~/.ori/config.json. Your own defaults, applied to every project you work on.
.ori/config.json in a project. Settings that belong to a repository and should apply to everyone working in it.
Command-line flags. Six update settings also have flags, listed below.
A machine policy file. /etc/ori/config.json, or C:\ProgramData\ori\config.json on Windows. Owned by whoever administers the machine, and it beats a flag.
macOS managed preferences. An MDM payload for the com.openrouter.ori preference domain. Beats everything, including the machine file.

If you administer a fleet, read Configuring managed machines.

Which source wins

Every setting resolves through the same list, and the first source that carries a valid value for it wins:

macOS managed preferences (com.openrouter.ori)
The machine policy file, /etc/ori/config.json
A command-line flag
The process environment, meaning whatever your shell exports
.ori/config.json in the working directory
~/.ori/config.json in your home directory
Ori’s own default

A project file beats your home file, matching how most tools treat local configuration. The two administrator sources sit above flags, so a policy set on the machine cannot be turned off from a shell, a project, or a flag. The one exception is ORI_NO_UPDATE_CHECK, which only suppresses the update check when no --auto-update flag is passed; ORI_DISABLE_AUTOUPDATER and ORI_DISABLE_UPDATES are the settings to use when a policy has to hold. Two groups of settings don’t follow this list everywhere:

Administrator-only settings. ORI_REQUIRED_ORGANIZATION_ID, ORI_REQUIRED_WORKSPACE_ID, ORI_REQUIRED_REGION, and ORI_CREDENTIAL_STORAGE are read only from macOS managed preferences and the machine policy file. Ori ignores them in your shell, a flag, or either config.json, and ori doctor names each copy it ignored. See Configuring managed machines.
Settings that choose where a credential goes. ORI_OPENROUTER_BASE_URL, ORI_OPENROUTER_ENDPOINT, ORI_RELEASE_BASE_URL, ORI_OPENROUTER_OIDC_ISSUER, and ORI_OPENROUTER_OIDC_CLIENT_ID are ignored in a project’s .ori/config.json, so a cloned repository can’t send your key or your sign-in somewhere else. Set them in your shell, ~/.ori/config.json, or an administrator source.

A missing file is fine, and a malformed one contributes nothing. A value Ori cannot make sense of is skipped per setting, so one bad entry does not discard the rest of a file, and the next source down answers instead. Where a setting below is described as a switch, Ori reads an empty value, 0, and false as off, and any other value as on. 1 is the conventional way to turn one on.

Config file shape

A config file can carry an env object of plain strings, named fields, or both. The two spellings feed the same setting:

{
  "channel": "stable",
  "autoUpdate": { "level": "patch", "intervalMs": 21600000 },
  "env": {
    "ORI_DISABLE_UPDATES": "1"
  }
}

Command-line flags

Only --auto-update, --auto-update-restart, --update-interval, --drain-timeout, --alpha, and --stable name a setting that also has a variable, so those are the only flags that take part in the list above. Every other flag is an argument to its command.

Configuring managed machines

Two mechanisms are meant for administrators, and both outrank anything a user can set. Every setting in the reference works in either one.

macOS: managed preferences

Deliver a custom-settings payload for the preference domain com.openrouter.ori from Jamf, Kandji, Intune, or any MDM that writes managed preferences. Use the setting name as the key. Booleans, numbers, and strings all work; Ori converts them:

<dict>
    <key>ORI_MODEL</key>
    <string>anthropic/claude-sonnet-4.5</string>
    <key>ORI_DISABLE_OAUTH_LOGIN</key>
    <true/>
    <key>ORI_UPDATE_INTERVAL</key>
    <integer>21600000</integer>
</dict>

Ori reads the per-user profile at /Library/Managed Preferences/<username>/com.openrouter.ori.plist and the device-wide one at /Library/Managed Preferences/com.openrouter.ori.plist. Nothing else on the machine can override what lands there. For ordinary settings, the per-user profile wins as a whole when it exists, and Ori doesn’t merge it with the device-wide one. The administrator-only settings in the next sections are different: Ori reads them from the per-user profile, the device-wide profile, and the machine policy file separately and combines them, so a device-wide restriction still applies when a per-user profile leaves it out. Ori takes the username from the operating system, not from USER or LOGNAME. Deliver the payload as forced settings; Ori doesn’t implement set-once preferences.

Any platform: the machine policy file

Write JSON to /etc/ori/config.json (or C:\ProgramData\ori\config.json on Windows) with your settings in the env object:

{
  "channel": "stable",
  "env": {
    "ORI_DISABLE_UPDATES": "1",
    "ORI_REQUIRE_LOGIN": "1",
    "ORI_MODEL": "anthropic/claude-sonnet-4.5"
  }
}

Ship the file with the rest of your machine configuration, the same way you ship any other policy file. A user cannot remove it without administrator rights, and no flag other than --auto-update against ORI_NO_UPDATE_CHECK can argue with it. On Windows, the path is fixed at C:\ProgramData\ori\config.json. Ori doesn’t use the ProgramData or SystemDrive environment variables to find it, because any user can change them. If you staged the file under a redirected ProgramData or on a drive other than C:, move it to C:\ProgramData\ori\config.json; until you do, Ori treats the machine as having no policy file.

Restrict which OpenRouter account Ori can use

Set ORI_REQUIRED_ORGANIZATION_ID, ORI_REQUIRED_WORKSPACE_ID, or both to require that every OpenRouter key Ori uses belongs to your organization or to one workspace in it. Before Ori uses or saves a key, it looks up the key’s owner with OpenRouter and refuses a key that doesn’t match. This covers API keys, browser sign-in, OIDC sessions, and the key Ori passes to the harnesses it launches.

ORI_REQUIRED_ORGANIZATION_ID. Your OpenRouter organization ID. A personal key is refused even when the person who created it belongs to the organization.
ORI_REQUIRED_WORKSPACE_ID. An OpenRouter workspace UUID. Browser sign-in asks OpenRouter for a key in that workspace. When you set both keys, a key must match both.

Ori looks the owner up live at least once per command, with a five-second timeout, and never saves the answer to disk. A failed lookup refuses the key; it doesn’t fall back to an earlier answer. The restriction applies to Ori’s own sign-in only. A credential that a harness gets through its own sign-in isn’t checked, and Ori interns are unaffected.

Lock Ori to one region

Set ORI_REQUIRED_REGION to global, us, or eu to send every Ori request through one OpenRouter data region. The value must be one of those three exactly, in lowercase with no spaces; a URL or an alias such as europe is invalid. While the lock applies, Ori derives every OpenRouter URL from the region and ignores ORI_OPENROUTER_REGION, ORI_OPENROUTER_BASE_URL, ORI_OPENROUTER_ENDPOINT, and the region and endpoint fields from every other source. Ori warns when one of those settings points somewhere else, naming the setting and where it came from. ori auth region refuses to change the region, ori login skips saving one, and every harness Ori launches routes through the locked region. A lock without ORI_REQUIRED_ORGANIZATION_ID or ORI_REQUIRED_WORKSPACE_ID doesn’t look up who owns the key.

Choose where credentials are stored

Set ORI_CREDENTIAL_STORAGE to choose how Ori stores saved logins, OIDC sessions, and MCP credentials on a machine:

protected. Keys held by the operating system: the macOS Keychain, the Secret Service, or systemd user credentials on Linux.
file. Keys held in files under ~/.ori/auth/plaintext/, readable only by the user. This doesn’t protect credentials from anyone who can copy the home directory.

Without this setting, Ori uses its release default, which is file while Ori releases are unsigned. Changing the value doesn’t move existing credentials, so users sign in again after a switch, and switching back finds the earlier credentials unchanged. With protected on macOS, users see a Keychain approval prompt after each update until releases are signed. On Windows, saved logins can’t use protected storage; OIDC sessions and MCP credentials can.

When administrator settings disagree or can’t be read

Ori fails closed on the administrator-only settings, so a typo never looks like it worked:

A malformed value, such as an empty organization ID, a workspace ID that isn’t a UUID, a region other than global, us, or eu, or a misspelled ORI_REQUIRED_* name, makes the policy invalid.
Two administrator sources with different values for the same setting make the policy conflicting. Equal values agree, and a workspace from one source can narrow an organization from another.
An administrator file or profile that exists but can’t be read or parsed makes the policy unreadable.

While the account or region policy is invalid, conflicting, or unreadable, every command that would use an OpenRouter key refuses until you fix the source. While ORI_CREDENTIAL_STORAGE is invalid, saved logins, OIDC sessions, and MCP credentials refuse, but OPENROUTER_API_KEY keeps working. Commands that need no key keep working in both cases. A source you remove stops applying on the next read. Each refusal has a stable code that --output json reports as its code, so scripts can act on it without parsing text:

Code	Meaning
`ORI_CLI_MANAGED_AUTH_POLICY_INVALID`	An administrator setting is malformed, or a source can’t be read.
`ORI_CLI_MANAGED_AUTH_POLICY_CONFLICTING`	Two administrator sources disagree.
`ORI_CLI_MANAGED_AUTH_ORGANIZATION_MISMATCH`	The key belongs to a different organization, or to a personal account.
`ORI_CLI_MANAGED_AUTH_WORKSPACE_MISMATCH`	The key belongs to a different workspace.
`ORI_CLI_MANAGED_AUTH_IDENTITY_UNAVAILABLE`	Ori couldn’t confirm who owns the key.
`ORI_CLI_MANAGED_AUTH_REGION_LOCKED`	`ori auth region` tried to change a locked region.
`ORI_CLI_MANAGED_AUTH_METHOD_DISABLED`	An administrator turned off the sign-in method a saved session uses.
`ORI_CLI_MANAGED_CREDENTIAL_STORAGE_INVALID`	`ORI_CREDENTIAL_STORAGE` is malformed, conflicting, or unreadable.

Check what applies on a machine

Run ori auth to see the account and region policy, which administrator sources set it, the required organization and workspace, whether the current key matches, the locked region and any settings that conflict with it, and the credential storage and who chose it. ori auth reports the policy without failing on it. Run ori doctor to see administrator-only settings that Ori ignored because a user, a project, or the shell set them, and any setting that conflicts with a region lock.

Roll out a new administrator setting

Deploy an Ori release that understands a setting before you deploy the setting:

ORI_REQUIRED_ORGANIZATION_ID and ORI_REQUIRED_WORKSPACE_ID need Ori 0.15.1 or later. Earlier releases ignore them.
ORI_REQUIRED_REGION, ORI_CREDENTIAL_STORAGE, ORI_DISABLE_OIDC_LOGIN, and the fixed Windows path need a release later than 0.15.5. A release that doesn’t know ORI_REQUIRED_REGION reads it as a misspelled restriction and refuses every key, and one that doesn’t know ORI_CREDENTIAL_STORAGE ignores it.

Keep API keys and management credentials out of every profile and policy file.

Two recipes

Ship Ori through your own tooling. Set ORI_DISABLE_UPDATES to 1. Ori stops checking for releases, never prints an update notice, and answers ori update with a message saying the installation is managed by your organization. Use ORI_DISABLE_AUTOUPDATER instead to keep the background updater quiet while users can still update by hand, and add "channel": "stable" to hold the fleet on one channel even against an --alpha flag. Force browser sign-in. Set ORI_DISABLE_API_KEY_LOGIN and ORI_DISABLE_ENV_KEY_LOGIN to 1 so the only way in is browser sign-in, and ORI_REQUIRE_LOGIN to 1 so an OPENROUTER_API_KEY a developer happens to have exported is refused rather than spent. These settings decide how a credential may be obtained, not which OpenRouter account or organization it belongs to, and a key saved before you turned a method off still works. To control which account Ori can use, add ORI_REQUIRED_ORGANIZATION_ID, as the next recipe shows. Keep the fleet on your organization. Combine the sign-in switches with an account restriction and, if you need it, a region lock. In a com.openrouter.ori payload:

<dict>
    <key>ORI_REQUIRED_ORGANIZATION_ID</key>
    <string>YOUR_OPENROUTER_ORGANIZATION_ID</string>
    <key>ORI_REQUIRED_WORKSPACE_ID</key>
    <string>YOUR_OPENROUTER_WORKSPACE_UUID</string>
    <key>ORI_REQUIRED_REGION</key>
    <string>eu</string>
    <key>ORI_CREDENTIAL_STORAGE</key>
    <string>protected</string>
    <key>ORI_DISABLE_API_KEY_LOGIN</key>
    <true/>
    <key>ORI_DISABLE_ENV_KEY_LOGIN</key>
    <true/>
</dict>

Or in the machine policy file:

{
  "env": {
    "ORI_REQUIRED_ORGANIZATION_ID": "YOUR_OPENROUTER_ORGANIZATION_ID",
    "ORI_REQUIRED_WORKSPACE_ID": "YOUR_OPENROUTER_WORKSPACE_UUID",
    "ORI_REQUIRED_REGION": "eu",
    "ORI_CREDENTIAL_STORAGE": "protected",
    "ORI_DISABLE_API_KEY_LOGIN": "1",
    "ORI_DISABLE_ENV_KEY_LOGIN": "1"
  }
}

Leave out ORI_REQUIRED_WORKSPACE_ID to allow any workspace in the organization, and leave out ORI_REQUIRED_REGION to let users choose their region. Copying this block into a user or project config.json creates no policy.

Settings reference

Every name below works as an environment variable, as an env entry in any config file, as a managed-preferences key, and in the machine policy file. The exceptions are the administrator-only settings, which work only in managed preferences and the machine policy file, and the settings that choose where a credential goes, which Ori ignores in a project’s .ori/config.json.

Ori 0.14 and earlier read less than that. Config files and the machine policy file carry the update and installation settings plus the sign-in method Ori remembers, every other name comes from the environment only, and macOS managed preferences are not read at all, so a profile you deploy to those versions has no effect. Export the setting in the environment until the fleet is on a newer build.

Updates and installation

Setting	Accepts	What it does
`ORI_DISABLE_UPDATES`	switch	Turns off automatic updates, hides the update notice, and makes `ori update` refuse to replace the install. Set this when your builds arrive through your own tooling.
`ORI_DISABLE_AUTOUPDATER`	switch	Turns off automatic updates and hides the update notice. An explicit `ori update` still runs.
`ORI_AUTO_UPDATE`	`off`, `patch`, `minor`, `major`	Largest version jump `ori start` and the TUI may install on their own. Defaults to `off`.
`ORI_CHANNEL`	`stable`, `alpha`	Release channel `ori update` and the background updater follow. With no channel set anywhere, an alpha build stays on alpha and everything else takes stable.
`ORI_NO_UPDATE_CHECK`	switch	Skips the background update check for this run. An explicit `--auto-update` flag overrides it wherever it came from, machine policy included, so use `ORI_DISABLE_AUTOUPDATER` for a fleet you want quiet.
`ORI_UPDATE_INTERVAL`	milliseconds	How long Ori waits between background update checks.
`ORI_UPDATE_RESTART`	`reexec`, `exit`	Whether a long-running Ori re-executes itself after an update or exits for your supervisor to restart.
`ORI_DRAIN_TIMEOUT`	milliseconds	How long an update waits for in-flight work to finish before restarting.
`ORI_INSTALL_DIR`	directory path	Where the installer writes the `ori` binary. By default it reinstalls over the `ori` already on your `PATH`, and only falls back to `~/.local/bin` for a first install.
`ORI_RELEASE_BASE_URL`	URL	Host that serves Ori release binaries and the `SHA256SUMS` file that verifies them. Ignored in a project’s `.ori/config.json`.

Setting	Accepts	What it does
`ORI_DISABLE_OAUTH_LOGIN`	switch	Removes browser sign-in from `ori login`.
`ORI_DISABLE_API_KEY_LOGIN`	switch	Removes pasting an API key from `ori login`.
`ORI_DISABLE_OIDC_LOGIN`	switch	Removes OpenRouter OIDC sign-in, including `ori login --oidc`, and refuses a saved OIDC session instead of using it. An administrator source that sets it to `0` keeps OIDC on. `ORI_DISABLE_CONNECT_LOGIN`, the earlier name, still turns OIDC off.
`ORI_DISABLE_ENV_KEY_LOGIN`	switch	Stops Ori accepting an `OPENROUTER_API_KEY` it finds in the environment.
`ORI_REQUIRE_LOGIN`	switch	Refuses to run on any credential that `ori login` did not establish, including an inherited `OPENROUTER_API_KEY` or one in a project dotenv file.
`ORI_FORCE_OPENROUTER_API_KEY`	switch	Always uses the `OPENROUTER_API_KEY` from the environment instead of a stored credential.
`ORI_OPENROUTER_OIDC_ISSUER`	URL	OpenID Connect issuer that `ori login --oidc` uses for new sessions. Ignored in a project’s `.ori/config.json`.
`ORI_OPENROUTER_OIDC_CLIENT_ID`	client ID	OpenID Connect public client that `ori login --oidc` uses for new sessions. Ignored in a project’s `.ori/config.json`.

Administrator-only

These settings work only in macOS managed preferences and the machine policy file. See Configuring managed machines.

Setting	Accepts	What it does
`ORI_REQUIRED_ORGANIZATION_ID`	organization ID	Refuses any OpenRouter key that this organization doesn’t own, including personal keys.
`ORI_REQUIRED_WORKSPACE_ID`	workspace UUID	Refuses any OpenRouter key outside this workspace, and asks browser sign-in for a key in it.
`ORI_REQUIRED_REGION`	`global`, `us`, `eu`	Sends every Ori request through this OpenRouter data region and ignores other region and endpoint settings.
`ORI_CREDENTIAL_STORAGE`	`protected`, `file`	Chooses OS-protected or file-backed storage for saved logins, OIDC sessions, and MCP credentials. On Windows, `protected` doesn’t cover saved logins: Ori reports that encrypted storage is unsupported for them, while OIDC sessions and MCP credentials keep working. Defaults to `file` while Ori releases are unsigned.

Models and output

Setting	Accepts	What it does
`ORI_MODEL`	model slug	Default model for `ori harness` and `ori code`.
`ORI_OPENROUTER_REGION`	`global`, `us`, `eu`	OpenRouter data region to route requests through. Overrides the `region` that `ori login` and `ori auth region` save. Defaults to `global`.
`ORI_OPENROUTER_BASE_URL`	URL	OpenRouter API base URL to send inference to, for a gateway, a proxy, or a regional host such as `https://us.openrouter.ai/api/v1`. Takes precedence over the region. Ignored in a project’s `.ori/config.json`.
`ORI_OPENROUTER_ENDPOINT`	URL	Same as `ORI_OPENROUTER_BASE_URL`, used when that setting is empty. Ignored in a project’s `.ori/config.json`.
`ORI_FALLBACK_MODELS`	comma-separated model slugs	Models the native harness tries in order when the run’s model keeps failing. Defaults to `~google/gemini-flash-latest,~anthropic/claude-sonnet-latest`. An empty value turns fallback off.
`ORI_MAX_TURNS`	count	Tool-turn limit for each native harness run. No limit by default.
`ORI_OUTPUT`	`human`, `json`	Output mode for commands that support both. Ori otherwise picks `human` for a terminal.
`ORI_TELEMETRY`	`0` or `false` to disable	Turns off Ori’s usage telemetry.

Terminal appearance

Setting	Accepts	What it does
`ORI_TUI_THEME`	palette name	Built-in palette for the chat TUI.
`ORI_TUI_THEME_FILE`	file path	Palette file to load instead of a built-in one.
`ORI_TUI_DENSITY`	`compact`, `cozy`, `verbose`	How much vertical space the transcript uses. Defaults to `cozy`.
`ORI_TUI_WORKING_INDICATOR`	`verb`, `tokens`, `minimal`, `wave`, `bar`, `shimmer`, `glider`, `quadrant`, `meter`	Animation shown while the agent works. Defaults to `glider`.
`ORI_TUI_WORKING_VERB_MODE`	`rotating`, `gliding-only`	Whether the working line rotates through verbs.
`ORI_TUI_WORKING_CADENCE`	`calm`, `steady`, `fast`	Animation speed of the working indicator.
`ORI_TUI_WORKSPACE_ROW`	`top`, `bottom`, `off`	Where the workspace row sits, or `off` to hide it.

Files

Setting	Accepts	What it does
`ORI_STATE_DIR`	directory path	Where Ori keeps its local state database. See where Ori writes files.
`ORI_LOG_MAX_RUNS`	count	How many run logs Ori keeps before pruning the oldest.

Overview

Models & Routing

Tool Calling

Features

Observability

Authentication

Ori

Developer Tools

Privacy

Best Practices

Community

Ori Configuration

Ways to configure Ori

Which source wins

Config file shape

Command-line flags

Configuring managed machines

macOS: managed preferences

Any platform: the machine policy file

Restrict which OpenRouter account Ori can use

Lock Ori to one region

Choose where credentials are stored

When administrator settings disagree or can’t be read

Check what applies on a machine

Roll out a new administrator setting

Two recipes

Settings reference

Updates and installation

Administrator-only

Models and output

Terminal appearance

Files

​Ways to configure Ori

​Which source wins

​Config file shape

​Command-line flags

​Configuring managed machines

​macOS: managed preferences

​Any platform: the machine policy file

​Restrict which OpenRouter account Ori can use

​Lock Ori to one region

​Choose where credentials are stored

​When administrator settings disagree or can’t be read

​Check what applies on a machine

​Roll out a new administrator setting

​Two recipes

​Settings reference

​Updates and installation

​Sign-in

​Administrator-only

​Models and output

​Terminal appearance

​Files

Ways to configure Ori

Which source wins

Config file shape

Command-line flags

Configuring managed machines

macOS: managed preferences

Any platform: the machine policy file

Restrict which OpenRouter account Ori can use

Lock Ori to one region

Choose where credentials are stored

When administrator settings disagree or can’t be read

Check what applies on a machine

Roll out a new administrator setting

Two recipes

Settings reference

Updates and installation

Sign-in

Administrator-only

Models and output

Terminal appearance

Files