# How to Configure OpenBB Environment Variables for Different Settings

> Learn to configure OpenBB environment variables for all your settings. Set them in .env files, shell exports, or CLI arguments for seamless control. Master your OpenBB setup today.

- Repository: [OpenBB/OpenBB](https://github.com/OpenBB-finance/OpenBB)
- Tags: how-to-guide
- Published: 2026-03-05

---

**Configure OpenBB environment variables by setting them in a `~/.openbb_platform/.env` file, exporting them in your shell, or passing them directly to the CLI, with core settings using the `OPENBB_` prefix, API server settings using `OPENBB_API_*`, and MCP service settings using `OPENBB_MCP_*`.**

The OpenBB Platform reads its runtime configuration from environment variables loaded at startup by the central `Env` singleton. According to the OpenBB-finance/OpenBB source code, these variables control everything from debug logging and extension behavior to API server binding and micro-service authentication. Understanding the specific prefixes and configuration files allows you to manage settings across local development, Docker containers, and production deployments.

## Core Environment Loader Architecture

All OpenBB environment variables are ingested by the `Env` class located in [`openbb_platform/core/openbb_core/env.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/env.py). This class implements a singleton pattern via `SingletonMeta`, ensuring that configuration is loaded exactly once and shared across the entire application lifecycle.

### The Env Singleton Implementation

When the `Env` instance is created, it automatically loads a `.env` file from the default OpenBB directory and copies the system environment:

```python
class Env(metaclass=SingletonMeta):
    def __init__(self) -> None:
        # Load .env from the default OpenBB directory

        dotenv.load_dotenv(Path(OPENBB_DIRECTORY, ".env"))
        self._environ = os.environ.copy()

```

**Source lines:** Lines 18‑19 in [`openbb_platform/core/openbb_core/env.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/env.py).

### Essential Core Variables

The `Env` class exposes typed properties that read specific `OPENBB_` prefixed variables. Key settings include:

- **`OPENBB_AUTO_BUILD`** (default: `True`): Controls whether extensions auto-compile on import. Property defined at lines 41‑45.
- **`OPENBB_DEBUG_MODE`** (default: `False`): Enables debug-level logging when set to `true`. Property defined at lines 46‑50.
- **`OPENBB_DEV_MODE`** (default: `False`): Activates development-only features and verbose error traces.
- **`OPENBB_ALLOW_MUTABLE_EXTENSIONS`** (default: `False`): Permits extensions that mutate OBBject output. Defined at lines 57‑61.
- **`OPENBB_ALLOW_ON_COMMAND_OUTPUT`** (default: `False`): Allows extensions to act on command output.

## API Server Environment Variables

The platform API server configuration resides in [`openbb_platform/extensions/platform_api/openbb_platform_api/main.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/platform_api/openbb_platform_api/main.py). The application reads host, port, and authentication settings directly from the environment during startup.

**Source lines:** Lines 286‑300.

| Variable | Default | Purpose |
|----------|---------|---------|
| `OPENBB_API_HOST` | `127.0.0.1` | Hostname or IP address the FastAPI server binds to |
| `OPENBB_API_PORT` | `6900` | TCP port for the API server |
| `OPENBB_API_AUTH` | `False` | Enables HTTP Basic authentication when set to `true` |
| `OPENBB_API_USERNAME` | — | Username for basic auth (required if auth is enabled) |
| `OPENBB_API_PASSWORD` | — | Password for basic auth (required if auth is enabled) |
| `OPENBB_API_AUTH_EXTENSION` | — | Optional name of an OpenBB auth extension to load |

```python
host = _kwargs.pop("host", os.getenv("OPENBB_API_HOST", "127.0.0.1"))
port = _kwargs.pop("port", os.getenv("OPENBB_API_PORT", "6900"))

```

## MCP Server Configuration Variables

The Micro-Control-Plane (MCP) service uses a dedicated namespace prefixed with `OPENBB_MCP_`. These settings are mapped in the MCP settings model (schema demonstrated in the test suite at [`openbb_platform/extensions/mcp_server/tests/service/test_mcp_service.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/extensions/mcp_server/tests/service/test_mcp_service.py), lines 105‑130).

Key variables include:

- **`OPENBB_MCP_NAME`**: Human-readable server identifier (e.g., `ProductionMCP`).
- **`OPENBB_MCP_VERSION`**: Version string exposed in health check endpoints.
- **`OPENBB_MCP_API_PREFIX`**: URL path prefix for MCP endpoints (e.g., `/mcp`).
- **`OPENBB_MCP_DEFAULT_TOOL_CATEGORIES`**: Comma-separated list of default tool categories.
- **`OPENBB_MCP_ALLOWED_TOOL_CATEGORIES`**: Whitelist of permitted tool categories.
- **`OPENBB_MCP_ENABLE_TOOL_DISCOVERY`**: Boolean flag to enable dynamic tool discovery.
- **`OPENBB_MCP_CACHE_EXPIRATION_SECONDS`**: Cache TTL for tool metadata (integer).
- **`OPENBB_MCP_CLIENT_AUTH`**: JSON array format for client credentials (e.g., `["user","pass"]`).
- **`OPENBB_MCP_SERVER_AUTH`**: JSON array format for server-side API credentials.

## Provider-Specific API Keys

Each data provider extension defines its own API key environment variables, typically following the pattern `<PROVIDER>_API_KEY`. For example, the Alpha Vantage provider documented in [`openbb_platform/providers/alpha_vantage/README.md`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/providers/alpha_vantage/README.md) requires `ALPHAVANTAGE_API_KEY`. Similar variables exist for FRED (`FRED_API_KEY`), Tiingo, and other providers.

## Practical Configuration Methods

### Using the .env File

Create or edit `~/.openbb_platform/.env` (the `OPENBB_DIRECTORY` constant defined in [`openbb_platform/app/constants.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/app/constants.py)):

```dotenv

# Core behavior

OPENBB_DEBUG_MODE=true
OPENBB_AUTO_BUILD=false

# API server binding

OPENBB_API_HOST=0.0.0.0
OPENBB_API_PORT=8000
OPENBB_API_AUTH=true
OPENBB_API_USERNAME=admin
OPENBB_API_PASSWORD=secret

# MCP service

OPENBB_MCP_NAME="ProductionMCP"
OPENBB_MCP_API_PREFIX="/mcp"
OPENBB_MCP_ENABLE_TOOL_DISCOVERY=true

```

The `Env` singleton loads this file automatically on the first import of any OpenBB module.

### Shell Environment Variables

Export variables in your shell before launching the application. This method is ideal for CI/CD pipelines and Docker containers:

```bash
export OPENBB_DEBUG_MODE=true
export OPENBB_API_HOST=0.0.0.0
export OPENBB_API_PORT=8000
export ALPHAVANTAGE_API_KEY="your_key_here"

openbb-api

```

### Programmatic Configuration

Set variables via Python's `os.environ` before importing OpenBB modules. This ensures the `Env` singleton reads the updated values during initialization:

```python
import os
os.environ["OPENBB_API_PORT"] = "9000"
os.environ["OPENBB_MCP_CACHE_EXPIRATION_SECONDS"] = "600"

from openbb_core.env import Env
print(Env().API_PORT)  # outputs: 9000

```

### CLI Argument Overrides

When launching the API server, you can override environment variables by passing arguments directly to the underlying Uvicorn server:

```bash
openbb-api --host 0.0.0.0 --port 8000

```

These arguments take precedence over `OPENBB_API_HOST` and `OPENBB_API_PORT` as implemented in the argument parser at lines 286‑300 of [`platform_api/main.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/platform_api/main.py).

## Summary

- The `Env` class in [`openbb_platform/core/openbb_core/env.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/core/openbb_core/env.py) acts as a singleton that loads variables from `~/.openbb_platform/.env` and the process environment.
- API server settings use `OPENBB_API_HOST`, `OPENBB_API_PORT`, and `OPENBB_API_AUTH*` variables defined in [`platform_api/main.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/platform_api/main.py).
- MCP server configuration relies on variables prefixed with `OPENBB_MCP_*` for tool discovery, caching, and authentication.
- Provider-specific keys follow the `<PROVIDER>_API_KEY` convention and are documented in individual provider READMEs under `openbb_platform/providers/`.
- Configuration can be applied via `.env` files, shell exports, Python `os.environ`, or CLI flags that supersede environment values.

## Frequently Asked Questions

### What is the default location for the OpenBB .env file?

The default location is `~/.openbb_platform/.env`, determined by the `OPENBB_DIRECTORY` constant in [`openbb_platform/app/constants.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/openbb_platform/app/constants.py). The `Env` class automatically attempts to load this file during initialization, so placing your variables there ensures they are available to all OpenBB components without manual exports.

### Can I override OpenBB environment variables using command-line arguments?

Yes. When starting the API server using the `openbb-api` command, you can pass `--host` and `--port` arguments directly. These values take precedence over `OPENBB_API_HOST` and `OPENBB_API_PORT` because the main application pops these kwargs from the command line before falling back to environment variables in [`platform_api/main.py`](https://github.com/OpenBB-finance/OpenBB/blob/main/platform_api/main.py).

### How do I set API keys for data providers in OpenBB?

Provider API keys use the format `<PROVIDER>_API_KEY`, such as `ALPHAVANTAGE_API_KEY` or `FRED_API_KEY`. These are read by the respective provider extensions during initialization. Refer to the specific provider's README file under `openbb_platform/providers/<provider>/` for the exact variable name and any additional configuration requirements.

### Do I need to restart the Python process after changing environment variables?

Yes. Because the `Env` class is a singleton that reads and caches the environment during its `__init__` method, any changes to the `.env` file or shell environment require restarting the Python interpreter or the API server process to take effect. Runtime changes to `os.environ` after importing `Env` will not be reflected in the cached configuration.