---
title: "Environment variables"
description: "The environment variables the binaries read, and the ones the node sets for its runtime."
canonical_url: "https://docs.oz0.ai/reference/environment"
---
# 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

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Used by
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        OZ0_CONTEXT
      </code>
    </td>
    
    <td>
      <code>
        orchestrator-zero
      </code>
    </td>
    
    <td>
      Path to the operator's CLI context; same as <code>
        --context
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_DB
      </code>
    </td>
    
    <td>
      <code>
        server init
      </code>
      
      , <code>
        server start
      </code>
    </td>
    
    <td>
      PostgreSQL URL of the management database, or <code>
        --db-file FILE
      </code>
      
      ; never an argument
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_RUNTIME_BUNDLE
      </code>
    </td>
    
    <td>
      <code>
        oz0 dev
      </code>
      
      , <code>
        plugin test
      </code>
    </td>
    
    <td>
      The runtime bundle the dev node uses
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_LLM_ANTHROPIC_URL
      </code>
      
      , <code>
        OZ0_LLM_OPENAI_URL
      </code>
    </td>
    
    <td>
      <code>
        oz0 dev
      </code>
    </td>
    
    <td>
      Where the dev server's gateway sends Anthropic and OpenAI calls, such as a proxy or a stand-in; same as <code>
        --llm-anthropic-url
      </code>
      
       and <code>
        --llm-openai-url
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_PAYLOAD_DB
      </code>
    </td>
    
    <td>
      <code>
        server start --roles=edge
      </code>
    </td>
    
    <td>
      The edge's own PostgreSQL connection for payloads and artifacts; or <code>
        --payload-db-file FILE
      </code>
      
       (<a href="https://docs.oz0.ai/fleet/separate-roles">
        roles apart
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_OTLP_HEADERS
      </code>
    </td>
    
    <td>
      <code>
        server start
      </code>
    </td>
    
    <td>
      Headers of every trace export, <code>
        name=value,name=value
      </code>
      
       as OpenTelemetry writes them (values percent-encoded where they hold a comma); a secret header can come from <code>
        --otlp-header-file NAME=FILE
      </code>
      
       instead. Never an argument
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_ADVISORY_FEED
      </code>
    </td>
    
    <td>
      <code>
        server start
      </code>
      
       (the edge role)
    </td>
    
    <td>
      The opt-in <a href="https://docs.oz0.ai/build/plugins/vulnerabilities#the-opt-in-feed">
        advisory feed
      </a>
      
       for the vulnerability scan, or <code>
        --advisory-feed-file FILE
      </code>
      
      ; the URL can carry a token, so it is never an argument
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_MCP_REGISTRY_URL
      </code>
    </td>
    
    <td>
      <code>
        server start
      </code>
      
       (the edge role)
    </td>
    
    <td>
      The MCP Registry that <code>
        plugin install mcp:
      </code>
      
       and the web UI's MCP Registry page read; default <code>
        https://registry.modelcontextprotocol.io
      </code>
      
       (<a href="https://docs.oz0.ai/build/plugins/claude-code-and-agent-plugins/marketplaces#from-the-mcp-registry">
        Claude Code plugins and Agent Plugins
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_PLUGIN_PYPI_URL
      </code>
      
      , <code>
        OZ0_PLUGIN_NPM_URL
      </code>
    </td>
    
    <td>
      <code>
        server start
      </code>
      
       (the edge role)
    </td>
    
    <td>
      The PyPI index and the npm registry the edge resolves and pins plugins' packages against, for your mirrors; defaults <code>
        https://pypi.org
      </code>
      
       and <code>
        https://registry.npmjs.org
      </code>
      
      . The npm one also serves imported plugins' <code>
        npx
      </code>
      
       servers and marketplace npm entries. Credentials in the URL never appear in errors (<a href="https://docs.oz0.ai/build/plugins/packages#pinning-and-hashes">
        pinning and hashes
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_REGISTRY_AUTH
      </code>
    </td>
    
    <td>
      <code>
        plugin push
      </code>
    </td>
    
    <td>
      <code>
        user:password
      </code>
      
       for the OCI registry, instead of <code>
        --username
      </code>
      
       and <code>
        --password-stdin
      </code>
      
       (<a href="https://docs.oz0.ai/build/plugins/sources">
        bundles and OCI
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_ADMIN_KEY
      </code>
    </td>
    
    <td>
      The admin API's commands, such as <code>
        usage export
      </code>
    </td>
    
    <td>
      An <a href="https://docs.oz0.ai/build/apps/runtime-api/authentication#admin-keys">
        admin key
      </a>
      
      , <code>
        oz0_&lt;id>_&lt;secret>
      </code>
      
      , which the commands send instead of the CLI context's certificate or session; the context still names the management address and the CA
    </td>
  </tr>
</tbody>
</table>

## Read by the client SDKs

The [Python](https://docs.oz0.ai/build/apps/sdk-python), [TypeScript](https://docs.oz0.ai/build/apps/sdk-typescript) and [Go](https://docs.oz0.ai/build/apps/sdk-go) SDKs, and `client generate`, read these when they are not given the value:

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        OZ0_URL
      </code>
    </td>
    
    <td>
      The edge's runtime API, such as <code>
        https://edge.example.com:7443
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_API_KEY
      </code>
    </td>
    
    <td>
      A tenant API key, <code>
        oz0_&lt;id>_&lt;secret>
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_TENANT
      </code>
    </td>
    
    <td>
      The tenant calls are made in
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_CA_FILE
      </code>
    </td>
    
    <td>
      The cluster's CA certificate, which signed the edge's
    </td>
  </tr>
</tbody>
</table>

## Read by the node

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      Used by
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        OZ0_JOIN_TOKEN
      </code>
    </td>
    
    <td>
      <code>
        oz0-node join
      </code>
    </td>
    
    <td>
      The join token, or <code>
        --token-file FILE
      </code>
      
      ; never an argument, which every user of the machine can read
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_UPDATE_GRACE
      </code>
    </td>
    
    <td>
      <code>
        oz0-node run
      </code>
    </td>
    
    <td>
      How long a <a href="https://docs.oz0.ai/fleet/upgrades/nodes#upgrade-the-node-binary">
        new node binary
      </a>
      
       has to reach an edge before the previous one comes back, as a Go duration; default <code>
        2m
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_STOP_GRACE
      </code>
    </td>
    
    <td>
      <code>
        oz0-node run
      </code>
    </td>
    
    <td>
      The <a href="https://docs.oz0.ai/fleet/manage-nodes#stops-drain-first">
        stop grace
      </a>
      
      : how long a stopping node waits for the sessions and calls in flight on it, as a Go duration from <code>
        0s
      </code>
      
       to <code>
        1h
      </code>
      
      ; default <code>
        10m
      </code>
      
      . <code>
        --stop-grace
      </code>
      
       overrides it, and a value that is not such a duration stops <code>
        run
      </code>
      
       with an error
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_NODE_OFFLINE
      </code>
    </td>
    
    <td>
      <code>
        oz0-node run
      </code>
    </td>
    
    <td>
      <code>
        1
      </code>
      
       is <code>
        --offline
      </code>
      
      : 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 <code>
        binaries
      </code>
      
       are not mirrored and still download (<a href="https://docs.oz0.ai/concepts/outbound-connections">
        outbound connections
      </a>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_BWRAP
      </code>
    </td>
    
    <td>
      <code>
        oz0-node run
      </code>
      
      , <code>
        sandbox check
      </code>
    </td>
    
    <td>
      The bubblewrap binary for <a href="https://docs.oz0.ai/concepts/security/sandbox-tiers#sandboxes">
        sandbox tier 1
      </a>
      
      , when it is not <code>
        bwrap
      </code>
      
       on <code>
        PATH
      </code>
    </td>
  </tr>
</tbody>
</table>

## 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:

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ANTHROPIC_BASE_URL
      </code>
    </td>
    
    <td>
      The node's local LLM proxy, for Anthropic's API
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OPENAI_BASE_URL
      </code>
    </td>
    
    <td>
      The node's local LLM proxy, for OpenAI-compatible APIs
    </td>
  </tr>
</tbody>
</table>

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

<table>
<thead>
  <tr>
    <th>
      Variable
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        OZ0_TEST_POSTGRES_URL
      </code>
    </td>
    
    <td>
      Runs the store and cluster tests against PostgreSQL as well as SQLite
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_TEST_SQLITE_TEMPLATE
      </code>
    </td>
    
    <td>
      With <code>
        off
      </code>
      
      , each test's SQLite file starts empty and the test migrates it, instead of being a copy of a file its process migrated once
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_TEST_REMOTE_STORE
      </code>
    </td>
    
    <td>
      With <code>
        1
      </code>
      
      , runs the store tests through the remote driver an edge apart from management uses
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        OZ0_E2E_DATA_DIR
      </code>
    </td>
    
    <td>
      Where the e2e scripts cache the node's uv, Python and runtimes between runs
    </td>
  </tr>
</tbody>
</table>


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
