Configuration
OKR.ai is configured with environment variables, usually in a .env file. Most settings that a workspace admin changes day to day (database, AI model, context sources, SSO) live in the app’s side panels instead.
#A minimal .env
# Required in production: signs sessions and encrypts stored secrets.
OKRAI_SECRET_KEY="…" # openssl rand -base64 32
OKRAI_URL="https://okr.example.com"
# One AI key for every workspace (optional; admins can bring their own key in the app)
OKRAI_AI_PROVIDER="anthropic"
OKRAI_AI_KEY=""
# Sign-in emails (optional in development)
SMTP_URL="smtps://user:pass@smtp.example.com:465"
MAIL_FROM="OKR.ai <no-reply@example.com>"
#Core
| Variable | Purpose |
|---|
OKRAI_SECRET_KEY | Required in production. Signs sessions and encrypts stored secrets (database connection strings, API keys, MCP tokens). Generate with openssl rand -base64 32. Keep it safe: losing it means re-entering those secrets. |
OKRAI_URL | Public URL of the app, used for magic links and OIDC redirects. Defaults to the request host. |
OKRAI_CONTROL_DB | The deployment’s own database. Default file:./data/okrai.db; a postgres:// URL also works. It routes sign-ins and holds the Built-in data store. |
PORT | Port to listen on. Default 3000. |
| Variable | Purpose |
|---|
OKRAI_AI_PROVIDER, OKRAI_AI_KEY, OKRAI_AI_MODEL | One AI key for every workspace on this server: anthropic, openai, deepseek or openrouter (default). The model defaults to the provider’s default. Workspaces can still use their own key in the AI model panel. See AI models. |
OPENROUTER_API_KEY, OPENROUTER_MODEL | The older form of the above, for OpenRouter. Still works. |
OKRAI_MOCK_LLM=1 | A deterministic stand-in model for demos and tests. Every AI flow works without a key. |
#Email
Sign-in codes are sent with one of these. Without any, codes are printed to the server log and shown on screen in development.
| Variable | Purpose |
|---|
SMTP_URL | smtps://user:pass@smtp.example.com:465 or smtp://…:587 (STARTTLS). |
RESEND_API_KEY, POSTMARK_TOKEN, SENDGRID_API_KEY | Use an email API instead of SMTP. |
MAIL_FROM | The sender, e.g. OKR.ai <no-reply@example.com>. |
#Sign-in
| Variable | Purpose |
|---|
GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET | Enables “Continue with Google”. Redirect URI: <OKRAI_URL>/api/auth/oidc/callback. |
SSO_ISSUER, SSO_CLIENT_ID, SSO_CLIENT_SECRET, SSO_NAME, SSO_DOMAIN | Deployment-wide OIDC SSO. Admins can also configure SSO per workspace. See Sign-in & SSO. |
#Scheduler and network
| Variable | Purpose |
|---|
CRON_SECRET | Enables POST /api/cron/snapshots for an external scheduler. |
OKRAI_ALLOW_PRIVATE_URLS=1 | Lets context sources point at private-network hosts. Blocked by default to prevent SSRF. |
#OKR.ai Cloud (optional)
Self-hosting needs none of these. Leave them empty and the Database and AI model panels show OKR.ai Cloud as Private preview, with a Request access button.
| Variable | Purpose |
|---|
OKRAI_PREVIEW_URL | Where Request access sends the person’s email and form answers. Default https://okr-ai.pages.dev/api/cloud-request. Set off to keep requests on this server only (they’re always saved in the control database). |
OKRAI_FEEDBACK_URL | Where the in-app bug button sends reports: what the person typed, the app path, their browser and the version, plus their email only if they tick the box. Default https://okr-ai.pages.dev/api/feedback. Set off to hide the button. |
OKRAI_CLOUD_URL_<REGION>, OKRAI_CLOUD_KEY | Turns on the cloud database in each AWS region you deployed infra/aws to, e.g. OKRAI_CLOUD_URL_EU_CENTRAL_1. OKRAI_CLOUD_KEY_<REGION> overrides the key for one region. See OKR.ai Cloud on AWS. |
OKRAI_CLOUD_URL, OKRAI_CLOUD_REGION | The older single-region form. Counts as OKRAI_CLOUD_REGION (default us-east-1). |