# How to Configure Onyx: Environment Variables and Deployment Guide

> Learn how to configure Onyx using environment variables. Our guide covers .env files, OS environment, Docker, Chat Widget, CLI, and local web development for seamless deployment.

- Repository: [Onyx/onyx](https://github.com/onyx-dot-app/onyx)
- Tags: how-to-guide
- Published: 2026-03-28

---

**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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/widget/vite.config.ts) and [`widget/src/config/config.ts`](https://github.com/onyx-dot-app/onyx/blob/main/widget/src/config/config.ts).

```bash
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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/widget/README.md).

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

```bash
onyx-cli configure

```

Environment variables override the stored configuration at runtime. According to [`cli/README.md`](https://github.com/onyx-dot-app/onyx/blob/main/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.

```bash
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`](https://github.com/onyx-dot-app/onyx/blob/main/package.json). This file configures the Next.js dev server to proxy API calls and attach authentication cookies automatically.

```bash
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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/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`](https://github.com/onyx-dot-app/onyx/blob/main/AGENTS.md). For Docker deployments, place them in the `.env` file alongside [`deployment/docker_compose/docker-compose.yml`](https://github.com/onyx-dot-app/onyx/blob/main/deployment/docker_compose/docker-compose.yml). Never commit these files; the repository `.gitignore` excludes them by default.