How to Configure Onyx: Environment Variables and Deployment Guide

Onyx is configured entirely through environment variables that are loaded at startup from .env files or the OS environment, with specific injection patterns for self-hosted Docker, the embeddable Chat Widget, the CLI client, and local web development.

Configuring the onyx-dot-app/onyx repository requires understanding its environment-driven architecture. Whether deploying the full stack via Docker, embedding the Chat Widget into your application, or using the CLI client, all settings are injected through environment variables that override default values at runtime.

Global Configuration Principles

Onyx uses a consistent configuration pattern across all deployment modes: environment variables take precedence, and .env files provide defaults.

Environment Precedence and Loading

The python-dotenv loader reads .env files first, then merges os.environ values. Values from the OS environment always override anything defined in a .env file. This pattern is used by the test suite, the CLI, and the backend services.

Configuration by Deployment Mode

• Self-hosted Widget: Build-time injection via Vite (widget/vite.config.ts replaces import.meta.env.VITE_… placeholders).
• Cloud Widget: Runtime HTML attributes (backend-url, api-key) passed to the custom element.
• CLI Client: Persistent JSON store at ~/.config/onyx-cli/config.json, overridable by env vars.
• Web Frontend: Next.js dev server reads web/.env.local for API proxy settings.

Configure the Chat Widget

The Chat Widget supports two distinct configuration patterns depending on whether you self-host the bundle or load it from the Onyx CDN.

Self-Hosted Widget Builds

For self-hosted deployments, create a .env file in the widget/ directory (copy from widget/.env.example). The Vite build process injects these values at build time via widget/vite.config.ts and widget/src/config/config.ts.

cd widget
cp .env.example .env

# Edit .env to set:

# VITE_WIDGET_BACKEND_URL=https://your-backend.com

# VITE_WIDGET_API_KEY=on_XXXXXXXXXXXXXXXX

npm install
npm run build:self-hosted

The resulting dist/onyx-widget.js contains the backend URL and API key baked into the bundle.

Cloud Widget Deployment

When loading the widget from the CDN, do not bake secrets into the bundle. Instead, pass configuration via HTML attributes on the custom element as documented in widget/README.md.

<script type="module"
        src="https://cdn.onyx.app/widget/1.0/dist/onyx-widget.js"></script>

<onyx-chat-widget
  backend-url="https://cloud.onyx.app/api"
  api-key="on_XXXXXXXXXXXXXXXX"
  agent-id="42"
  mode="launcher"
  primary-color="#FF6B35">
</onyx-chat-widget>

Required attributes include backend-url and api-key. Optional attributes such as agent-id, primary-color, and background-color customize the user interface.

Configure the CLI Client

The CLI client stores persistent configuration in ~/.config/onyx-cli/config.json. Run the interactive wizard to initialize this file.

onyx-cli configure

Environment variables override the stored configuration at runtime. According to cli/README.md, the CLI checks for:

• ONYX_SERVER_URL – The backend API endpoint.
• ONYX_API_KEY – Authentication token.
• ONYX_PERSONA_ID – Default persona for queries.

export ONYX_SERVER_URL=https://cloud.onyx.app
export ONYX_API_KEY=on_abc123
onyx-cli ask "What is the status of the Q4 roadmap?"

Configure the Web Frontend for Local Development

For local development against a cloud backend, create web/.env.local at the same level as package.json. This file configures the Next.js dev server to proxy API calls and attach authentication cookies automatically.

cd web
cat > .env.local <<EOF
INTERNAL_URL=https://st-dev.onyx.app/api
DEBUG_AUTH_COOKIE=your_fastapiusersauth_cookie
EOF

npm install
npm run dev

As detailed in web/README.md, INTERNAL_URL routes API requests to the remote backend, while DEBUG_AUTH_COOKIE simulates an authenticated session for testing.

Configure Docker and Kubernetes Deployments

Self-hosted Docker deployments use an environment template file. Copy env.template to .env in the deployment directory and edit the values as described in deployment/docker_compose/README.md.

Key variables include:

• POSTGRES_PASSWORD – Database credentials.
• ONNX_API_KEY – Model inference keys.
• OPENAI_API_KEY – LLM provider authentication.

Docker Compose automatically loads the .env file and injects values into all services.

Backend and Celery Worker Configuration

All background workers and backend services read from the same environment, typically injected via Docker or Kubernetes ConfigMap resources. As noted in AGENTS.md, the root .env file stores critical secrets like OPENAI_API_KEY that Celery workers and the FastAPI backend require to process indexing jobs and answer queries.

Summary

• Environment variables are the single source of truth for all Onyx configuration.
• OS environment overrides .env file values in all deployment modes.
• Self-hosted widgets require build-time injection via VITE_ prefixed variables in widget/.env.
• Cloud widgets use runtime HTML attributes (backend-url, api-key) and never bake secrets.
• CLI configuration persists to ~/.config/onyx-cli/config.json but yields to ONYX_SERVER_URL and ONYX_API_KEY env vars.
• Local web development uses web/.env.local to proxy to remote backends.
• Docker deployments rely on .env files in deployment/docker_compose/ for service orchestration.

Frequently Asked Questions

How does environment variable precedence work in Onyx?

The python-dotenv loader reads .env files first, then merges os.environ. Values present in the operating system environment always take precedence over file-based configuration. This allows temporary overrides without modifying committed files.

Can I use the Onyx CLI without running the interactive configure command?

Yes. While onyx-cli configure creates the persistent config file at ~/.config/onyx-cli/config.json, you can export ONYX_SERVER_URL and ONYX_API_KEY directly in your shell. The CLI checks these environment variables at runtime and uses them instead of the stored values.

What is the difference between cloud and self-hosted widget configuration?

Self-hosted widget builds bake configuration into the JavaScript bundle at build time using VITE_WIDGET_BACKEND_URL and VITE_WIDGET_API_KEY in widget/.env. Cloud widget deployments load from the CDN and receive configuration via HTML attributes on the <onyx-chat-widget> element, keeping secrets out of the build artifact.

Where should I store sensitive API keys like OPENAI_API_KEY in Onyx?

Store sensitive keys in the root .env file for backend services and Celery workers, as indicated in AGENTS.md. For Docker deployments, place them in the .env file alongside deployment/docker_compose/docker-compose.yml. Never commit these files; the repository .gitignore excludes them by default.

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