Skip to main content
Oxy is configured primarily through environment variables. This page covers the full set of variables for production deployments.
1

Create Environment File

Create a .env file to store your environment variables:
touch .env
chmod 600 .env  # Restrict permissions to owner only
Never commit .env to version control. Add it to .gitignore.
2

Set Required Variables

The variables you need depend on your deployment mode.Single-workspace mode (oxy serve --local) — minimal setup:
OPENAI_API_KEY=sk-...
# or whichever model provider you use
Multi-workspace mode (oxy serve) — required:
# PostgreSQL connection string
OXY_DATABASE_URL=postgresql://user:password@host:5432/oxy

# Directory where workspaces are stored
OXY_STATE_DIR=/data/oxy          # defaults to ~/.local/share/oxy

# LLM provider (at least one)
OPENAI_API_KEY=sk-...

# Authentication (at least one method, or leave all unset for no-auth)
MAGIC_LINK_SECRET=any-long-random-string
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...

# Instance owner (recommended for team deployments)
OXY_OWNER=admin@example.com
3

GitHub App (multi-workspace only)

To enable importing repositories as workspaces, set up a GitHub App and configure these variables. See the GitHub App Setup guide for step-by-step instructions.
GITHUB_APP_ID=123456
GITHUB_APP_SLUG=my-oxy-app
GITHUB_APP_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"
GITHUB_CLIENT_ID=Iv23liqo62PgXXXXXX
GITHUB_CLIENT_SECRET=abc123...
GITHUB_STATE_SECRET=$(openssl rand -hex 32)  # keep stable across restarts
4

Enterprise Features (optional)

Required only when using oxy serve --enterprise or oxy start --enterprise:
OXY_CLICKHOUSE_URL=http://localhost:8123
OXY_CLICKHOUSE_USER=default        # optional
OXY_CLICKHOUSE_PASSWORD=...        # optional
OXY_CLICKHOUSE_DATABASE=otel       # optional
5

Verify and Restart

# Check that the variables are loaded
printenv | grep OXY_

# Restart the Oxy service
sudo systemctl restart oxy
sudo systemctl status oxy

​
Full Variable Reference

​
Core

VariableRequiredDefaultDescription
OXY_DATABASE_URLRequired (multi-workspace)—PostgreSQL connection string
OXY_STATE_DIRNo~/.local/share/oxyDirectory for workspaces and runtime data
OXY_OWNERNo—Email address granted Owner role on login. Owners can promote other users to Admin. When unset, all users are admin (single-user default).
OXY_API_URLNoderived from requestBase URL of the API (set when frontend and backend are on different domains)

​
Authentication

VariableRequiredDescription
MAGIC_LINK_SECRETFor magic-link authSecret used to sign magic-link tokens
GOOGLE_CLIENT_IDFor Google OAuthOAuth 2.0 client ID from Google Cloud Console
GOOGLE_CLIENT_SECRETFor Google OAuthOAuth 2.0 client secret
OKTA_CLIENT_IDFor Okta OAuthOkta application client ID
OKTA_CLIENT_SECRETFor Okta OAuthOkta application client secret
OKTA_DOMAINFor Okta OAuthYour Okta domain (e.g. company.okta.com)
See Authentication for setup instructions.

​
GitHub App

VariableRequiredDescription
GITHUB_APP_IDFor GitHub importNumeric App ID from the GitHub App settings page
GITHUB_APP_SLUGFor GitHub importApp slug (appears in the app’s GitHub URL)
GITHUB_APP_PRIVATE_KEYFor GitHub importFull RSA private key PEM block
GITHUB_CLIENT_IDFor GitHub importOAuth Client ID from the app settings
GITHUB_CLIENT_SECRETFor GitHub importOAuth Client Secret from the app settings
GITHUB_STATE_SECRETFor GitHub importRandom secret for HMAC-signing OAuth state and selection tokens
See GitHub App Setup for a full walkthrough.

​
Enterprise

VariableRequiredDescription
OXY_CLICKHOUSE_URLFor --enterpriseClickHouse connection URL
OXY_CLICKHOUSE_USERNoClickHouse username (default: default)
OXY_CLICKHOUSE_PASSWORDNoClickHouse password
OXY_CLICKHOUSE_DATABASENoClickHouse database name (default: otel)

​
Using AWS SSM Parameter Store

For cloud deployments, fetch secrets from SSM at startup: 
# Fetch a single parameter
export OXY_DATABASE_URL=$(aws ssm get-parameter \
  --name "/oxy/database-url" \
  --with-decryption \
  --query "Parameter.Value" \
  --output text)

# Fetch and source a full .env file stored in SSM
aws ssm get-parameter --name "/oxy/env" --with-decryption \
  --query "Parameter.Value" --output text > .env