Reference
Environment variables
The environment variables the binaries read, and the ones the node sets for its runtime.
For: Operators and developers configuring processes.
Look up environment variables by the process that reads or sets them. Values passed to a node's runtime are listed separately from operator configuration.
Read by the CLI and the server
| Variable | Used by | What |
|---|---|---|
OZ0_CONTEXT | orchestrator-zero | Path to the operator's CLI context; same as --context |
OZ0_DB | server init, server start | PostgreSQL URL of the management database, or --db-file FILE; never an argument |
OZ0_RUNTIME_BUNDLE | oz0 dev, plugin test | The runtime bundle the dev node uses |
OZ0_LLM_ANTHROPIC_URL, OZ0_LLM_OPENAI_URL | oz0 dev | Where the dev server's gateway sends Anthropic and OpenAI calls, such as a proxy or a stand-in; same as --llm-anthropic-url and --llm-openai-url |
OZ0_PAYLOAD_DB | server start --roles=edge | The edge's own PostgreSQL connection for payloads and artifacts; or --payload-db-file FILE (roles apart) |
OZ0_OTLP_HEADERS | server start | Headers of every trace export, name=value,name=value as OpenTelemetry writes them (values percent-encoded where they hold a comma); a secret header can come from --otlp-header-file NAME=FILE instead. Never an argument |
OZ0_ADVISORY_FEED | server start (the edge role) | The opt-in advisory feed for the vulnerability scan, or --advisory-feed-file FILE; the URL can carry a token, so it is never an argument |
OZ0_MCP_REGISTRY_URL | server start (the edge role) | The MCP Registry that plugin install mcp: and the web UI's MCP Registry page read; default https://registry.modelcontextprotocol.io (Claude Code plugins and Agent Plugins) |
OZ0_PLUGIN_PYPI_URL, OZ0_PLUGIN_NPM_URL | server start (the edge role) | The PyPI index and the npm registry the edge resolves and pins plugins' packages against, for your mirrors; defaults https://pypi.org and https://registry.npmjs.org. The npm one also serves imported plugins' npx servers and marketplace npm entries. Credentials in the URL never appear in errors (pinning and hashes) |
OZ0_REGISTRY_AUTH | plugin push | user:password for the OCI registry, instead of --username and --password-stdin (bundles and OCI) |
OZ0_ADMIN_KEY | The admin API's commands, such as usage export | An admin key, oz0_<id>_<secret>, which the commands send instead of the CLI context's certificate or session; the context still names the management address and the CA |
Read by the client SDKs
The Python, TypeScript and Go SDKs, and client generate, read these when they are not given the value:
| Variable | What |
|---|---|
OZ0_URL | The edge's runtime API, such as https://edge.example.com:7443 |
OZ0_API_KEY | A tenant API key, oz0_<id>_<secret> |
OZ0_TENANT | The tenant calls are made in |
OZ0_CA_FILE | The cluster's CA certificate, which signed the edge's |
Read by the node
| Variable | Used by | What |
|---|---|---|
OZ0_JOIN_TOKEN | oz0-node join | The join token, or --token-file FILE; never an argument, which every user of the machine can read |
OZ0_UPDATE_GRACE | oz0-node run | How long a new node binary has to reach an edge before the previous one comes back, as a Go duration; default 2m |
OZ0_STOP_GRACE | oz0-node run | The stop grace: how long a stopping node waits for the sessions and calls in flight on it, as a Go duration from 0s to 1h; default 10m. --stop-grace overrides it, and a value that is not such a duration stops run with an error |
OZ0_NODE_OFFLINE | oz0-node run | 1 is --offline: uv, Python, the runtime's packages and Node.js only from the edge's toolchain, never from the internet, and plugins' Python packages from it too; npm packages and harness binaries are not mirrored and still download (outbound connections) |
OZ0_BWRAP | oz0-node run, sandbox check | The bubblewrap binary for sandbox tier 1, when it is not bwrap on PATH |
Set by the node for its runtime
The node's supervisor sets these for the agent runtime, so unmodified SDKs talk to the local proxies:
| Variable | What |
|---|---|
ANTHROPIC_BASE_URL | The node's local LLM proxy, for Anthropic's API |
OPENAI_BASE_URL | The node's local LLM proxy, for OpenAI-compatible APIs |
The API key the runtime sees is a per-start token for the local proxy, not a provider key. Tool processes get a minimal environment of their own, plus what the manifest sets in env.
For development
| Variable | What |
|---|---|
OZ0_TEST_POSTGRES_URL | Runs the store and cluster tests against PostgreSQL as well as SQLite |
OZ0_TEST_SQLITE_TEMPLATE | With off, each test's SQLite file starts empty and the test migrates it, instead of being a copy of a file its process migrated once |
OZ0_TEST_REMOTE_STORE | With 1, runs the store tests through the remote driver an edge apart from management uses |
OZ0_E2E_DATA_DIR | Where the e2e scripts cache the node's uv, Python and runtimes between runs |