How to Configure OpenBB Environment Variables for Different Settings

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

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.

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

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, 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 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):

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

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:

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:

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.

Summary

• The Env class in 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.
• 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. 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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}