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:[email protected]:465"
MAIL_FROM="OKR.ai <[email protected]>"
#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 | This copy’s own database. Default file:./data/okrai.db. It routes sign-ins and holds the Built-in data store. A postgres:// URL makes it one server-wide database for a single shared server; teams where everyone runs their own copy use a join code instead. |
OKRAI_AUTH_MODE=team | For a server everyone opens in their browser: sign-in is required from the start, and the first person to sign in sets up the team. Without it, a new install is solo (no sign-in, this computer only) until someone turns on team sign-in in Collaborate. |
PORT | Port to listen on. Default 3000. With npx okr-ai, --port does the same. |
| 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. Admins can also pick a mail service in Collaborate → Sign-in methods; these variables win. Without any, email sign-in is off. Solo installs don’t need email at all.
| Variable | Purpose |
|---|
SMTP_URL | smtps://user:[email protected]: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 <[email protected]>. |
#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 add identity providers in Collaborate → Sign-in methods. See Sign-in & SSO. |
OKRAI_TERMINAL_CODES=1 | Set by npx okr-ai when there’s no mail service: sign-in codes are printed in the server’s terminal only, never on screen. Ignored once this copy uses a shared team database. |
OKRAI_DEV_LOGIN=1 | Local development only: shows sign-in codes on screen and in the server log, so anyone who can reach the server can sign in as anyone. Ignored when NODE_ENV=production. |
#Scheduler and network
| Variable | Purpose |
|---|
CRON_SECRET | Enables POST /api/cron/snapshots for an external scheduler. |
OKRAI_MCP=off | Turns off the MCP server that AI assistants connect to. It’s on by default and accepts local connections only. See AI assistants (MCP). |
OKRAI_MCP_ALLOW_REMOTE=1 | Lets the MCP server accept requests addressed to host names other than localhost. Tokens are still required. Only use it behind your own network controls. |
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). |