Environment Variables

Environment variables are the strongest configuration source for a Roomote deployment. They are best for values that belong to infrastructure: public URLs, database and Redis connections, storage credentials, provider API keys, signing keys, and production-only overrides. Most day-to-day setup can also be managed from the Roomote UI. Use environment variables when you want configuration to be explicit, reproducible, managed by your deployment platform, or unavailable to in-app editors.

Precedence

Roomote resolves configuration in layers:

Process environment variables supplied by Docker Compose, the one-command installer, a PaaS, or the shell.
Saved deployment environment variables encrypted in Roomote during setup or from Settings pages.
Persisted runtime settings such as the selected default model, compute provider, or preview settings.
Derived defaults for local development and release-managed values.

The exact order depends on the setting. A few important cases:

Provider credentials usually resolve as process env first, then saved deployment env vars.
Model role env vars such as ROOMOTE_MODEL override the same role selected in Settings > Models.
Preview env vars such as PREVIEW_PROXY_BASE_URL override values saved from Settings > Live Previews.
Compute provider credentials resolve as process env first, then saved deployment env vars. The default compute provider is special: an explicit admin selection saved in Roomote wins over DEFAULT_COMPUTE_PROVIDER because local and Compose stacks often set a default automatically.
Local development has safe defaults for Postgres, Redis, MinIO, signing keys, and local URLs. Production does not.

UI locking

When a supported setting is provided by the process environment, Roomote treats it as operator-managed infrastructure. Settings pages may show the value as configured, masked, or env-managed, but they should not overwrite it. This is intentional. It lets production operators keep secrets and platform configuration in the deployment system while still letting admins manage non-env settings in the app. Use the UI when:

the value is safe for an admin to rotate from Roomote
the setting is expected to change without redeploying
the deployment platform does not make env management easy

Use environment variables when:

the value is required for boot, networking, or storage
the value is a production secret managed by your host or secret manager
you want changes reviewed in infrastructure config
you need to prevent in-app overrides

Production recommendations

For production and shared self-hosted deployments:

Set NODE_ENV=production and APP_ENV=production.
Set stable public URLs with ROOMOTE_APP_URL, TRPC_URL, and, when previews are enabled, PREVIEW_PROXY_BASE_URL.
Provide DATABASE_URL, REDIS_URL, and S3-compatible artifact storage.
Generate strong ENCRYPTION_KEY, ARTIFACT_SIGNING_KEY, and DASHBOARD_PASSWORD values.
Either provide both job and preview auth keypairs or set ROOMOTE_AUTO_GENERATE_KEYS=true so Roomote generates and persists them.
Keep provider credentials in environment variables or a secret manager when they are controlled by the operator.
Prefer immutable worker image tags for hosted compute providers.
Avoid SKIP_ENV_VALIDATION outside build tooling or one-off diagnostics.

Supported env vars

The table below lists operator-supported deployment configuration. It does not include task-scoped internal variables that Roomote injects into sandboxes, such as per-task auth tokens or workspace paths.

Runtime and URLs

Env var	Required	Used for
`NODE_ENV`	Production	Node runtime mode: `development`, `test`, or `production`. Production deploys should set `production`.
`APP_ENV`	Recommended	Roomote app environment: `development`, `preview`, or `production`. Also affects monitoring and local URL defaults.
`ROOMOTE_PUBLIC_URL`	Local callbacks	Stable public HTTPS origin used by local development for OAuth and webhook callbacks.
`ROOMOTE_APP_URL`	Production	Public web app origin. Workers and integrations use it for links back to Roomote.
`TRPC_URL`	Production	API/tRPC origin used by workers and services. In single-origin production, this is often the app URL plus `/_roomote-api`.
`NEXT_PUBLIC_GITHUB_APP_SLUG`	GitHub setup	GitHub App slug exposed to the browser. `GITHUB_APP_SLUG` is also accepted during source-control setup.
`SETUP_TOKEN`	Required (non-local)	One-time bootstrap token that admits the first admin at `/setup`. Required on every non-local deployment — tokenless bootstrap is allowed only when `NODE_ENV` is not `production` and `APP_ENV` is `development`, so anything running with `NODE_ENV=production` needs it. Without it, first-admin bootstrap stays closed so nobody can claim the founding-admin slot by reaching the URL first. Optional only in local development.
`DASHBOARD_PASSWORD`	Production	Local fallback/admin password value used by the deployment. Generate a strong secret.
`WEB_DEV_LOGIN_EMAIL`	Local only	Convenience email for development login flows. Do not use as production access control.
`SKIP_ENV_VALIDATION`	Avoid	Skips env validation when present. Useful for narrow tooling cases, not normal deployments.

Database, Redis, and artifacts

Env var	Required	Used for
`DATABASE_URL`	Production	Postgres connection string. Local development defaults to the local Compose database.
`REDIS_URL`	Production	Redis connection string for queues and runtime coordination.
`S3_ENDPOINT`	Production	S3-compatible artifact storage endpoint used by services.
`S3_PRESIGN_ENDPOINT`	Recommended	Endpoint used when signing artifact URLs for workers or browsers. Set this when the public or worker-reachable URL differs from `S3_ENDPOINT`.
`S3_REGION`	Production	S3 region. MinIO deployments commonly use `us-east-1`.
`S3_ACCESS_KEY_ID`	Production	Artifact-storage access key.
`S3_SECRET_ACCESS_KEY`	Production	Artifact-storage secret key.
`S3_BUCKET_ARTIFACTS`	Production	Bucket used for Roomote artifacts.
`S3_AUTO_CREATE_BUCKET`	Optional	Set to `true` or `1` to create the artifacts bucket at API boot when it is missing.

Security and signing

Env var	Required	Used for
`ENCRYPTION_KEY`	Production	Secret used to encrypt deployment-stored secrets. Must be at least 32 characters.
`BETTER_AUTH_SECRET`	Optional	Dedicated secret for signing sign-in session cookies. At least 32 characters. Falls back to `ENCRYPTION_KEY` when unset; setting it later invalidates existing sessions.
`ARTIFACT_SIGNING_KEY`	Production	Secret used to sign artifact access. Must be at least 32 characters.
`ARTIFACT_SIGNING_KEY_PREVIOUS`	Rotation	Previous artifact signing key during rotation.
`JOB_AUTH_PRIVATE_KEY`	Production unless auto-generated	Base64-encoded P-256 private key for job auth tokens.
`JOB_AUTH_PUBLIC_KEY`	Production unless auto-generated	Base64-encoded P-256 public key for job auth token verification.
`PREVIEW_AUTH_PRIVATE_KEY`	Production unless auto-generated	Base64-encoded P-256 private key for preview auth tokens.
`PREVIEW_AUTH_PUBLIC_KEY`	Production unless auto-generated	Base64-encoded P-256 public key for preview auth token verification.
`ROOMOTE_AUTO_GENERATE_KEYS`	Optional	Set to `true` or `1` to generate missing job and preview keypairs at first startup and persist them encrypted in the database.
`SANDBOX_OIDC_PRIVATE_KEY`	Optional	Private key for sandbox OIDC token signing when using OIDC-backed sandbox auth flows.
`SANDBOX_OIDC_PUBLIC_KEY`	Optional	Primary public key for sandbox OIDC verification.
`SANDBOX_OIDC_PUBLIC_KEY_SECONDARY`	Rotation	Secondary sandbox OIDC public key during key rotation.

Models and inference providers

Env var	Required	Used for
`ROOMOTE_MODEL`	Optional	Env-level default coding model. Overrides the default selected in Settings > Models for new task starts.
`ROOMOTE_SMALL_MODEL`	Optional	Helper model for routing, titles, summaries, and lightweight model calls.
`ROOMOTE_VISION_MODEL`	Optional	Vision-capable model for visual inspection and screenshot/image work.
`ROOMOTE_CODE_REVIEW_MODEL`	Optional	Model for initial PR/MR review and review-sync tasks.
`ROOMOTE_EXPLORE_MODEL`	Optional	Exploration/helper model for investigation-oriented subtasks.
`ROOMOTE_PLANNING_MODEL`	Optional	Planning model used for longer coding-task planning.
`ROOMOTE_MODEL_REASONING_EFFORT`	Optional	Reasoning level for the coding model: `low`, `medium`, `high`, or `xhigh`.
`ROOMOTE_SMALL_MODEL_REASONING_EFFORT`	Optional	Reasoning level for the helper model.
`ROOMOTE_VISION_MODEL_REASONING_EFFORT`	Optional	Reasoning level for the vision model.
`ROOMOTE_CODE_REVIEW_MODEL_REASONING_EFFORT`	Optional	Reasoning level for the code review model.
`ROOMOTE_EXPLORE_MODEL_REASONING_EFFORT`	Optional	Reasoning level for the exploration model.
`ROOMOTE_PLANNING_MODEL_REASONING_EFFORT`	Optional	Reasoning level for the planning model.
`ROOMOTE_MODEL_ENV_KEYS`	Optional	Comma- or space-separated list of extra provider key env vars to forward to task workers.
`OPENROUTER_API_KEY`	Provider key	OpenRouter API key. Can also be saved from Settings > Models.
`AI_GATEWAY_API_KEY`	Provider key	Vercel AI Gateway API key.
`OPENAI_API_KEY`	Provider key	OpenAI API key.
`ANTHROPIC_API_KEY`	Provider key	Anthropic API key.
`MOONSHOT_API_KEY`	Provider key	Moonshot AI / Kimi API key.
`MINIMAX_API_KEY`	Provider key	MiniMax API key.
`OPENCODE_API_KEY`	Provider key	OpenCode Zen / Go API key.
`GOOGLE_GENERATIVE_AI_API_KEY`	Provider key	Google/Gemini provider key forwarded when configured or inferred.
`GEMINI_API_KEY`	Provider key	Alternate Gemini provider key.
`MISTRAL_API_KEY`	Provider key	Mistral provider key forwarded when configured.

Compute providers

Env var	Required	Used for
`DEFAULT_COMPUTE_PROVIDER`	Optional	Runtime default compute provider when no admin default is saved. Supported values are `docker`, `modal`, `e2b`, and `daytona`.
`EXCLUDED_COMPUTE_PROVIDERS`	Optional	Comma-separated provider IDs to hide or exclude from default selection.
`DOCKER_WORKER_IMAGE`	Optional	Worker image for Docker and hosted compute derivation. In production, prefer an immutable registry-qualified tag.
`ROOMOTE_WORKER_IMAGE_REPO`	Optional	Registry repository used to derive the worker image from `RELEASE_VERSION` when `DOCKER_WORKER_IMAGE` is unset.
`DOCKER_WORKER_PLATFORM`	Optional	Docker worker platform. Defaults to `linux/amd64`.
`DOCKER_WORKER_NETWORK`	Self-host Docker	Docker network for worker containers in Compose/self-host mode.
`DOCKER_WORKER_RELEASE_PATH`	Optional	Path to a packaged worker release archive used by Docker worker bootstrap.
`MODAL_TOKEN_ID`	Modal	Modal token ID. Can also be saved from Settings > Compute.
`MODAL_TOKEN_SECRET`	Modal	Modal token secret.
`MODAL_BASE_IMAGE_REF`	Modal	Modal base image reference. Usually derived from the worker image; set only to pin a custom image.
`MODAL_ENDPOINT`	Optional	Modal endpoint override.
`MODAL_ENVIRONMENT`	Optional	Modal environment name.
`MODAL_APP_NAME`	Optional	Modal app name override.
`MODAL_REGISTRY_USERNAME`	Private registry	Registry username for private non-ECR image pulls.
`MODAL_REGISTRY_PASSWORD`	Private registry	Registry password for private non-ECR image pulls.
`MODAL_ECR_OIDC_ROLE_ARN`	ECR	AWS IAM role ARN used by Modal for ECR OIDC pulls.
`MODAL_ECR_REGION`	ECR	AWS region for Modal ECR OIDC pulls.
`E2B_API_KEY`	E2B	E2B API key. Can also be saved from Settings > Compute.
`E2B_TEMPLATE_ID`	E2B	Worker template ID. Usually provisioned from the worker image by Roomote.
`E2B_DOMAIN`	Optional	E2B domain for self-hosted or custom E2B clusters.
`E2B_MAX_SANDBOX_TIMEOUT_MS`	Optional	Maximum E2B sandbox timeout Roomote will request. Defaults to one hour.
`DAYTONA_API_KEY`	Daytona	Daytona API key. Can also be saved from Settings > Compute.
`DAYTONA_API_URL`	Optional	Daytona API URL override.
`DAYTONA_TARGET`	Optional	Daytona target or region.
`DAYTONA_SNAPSHOT_NAME`	Daytona	Worker snapshot name. Usually registered from the worker image by Roomote.
`WORKER_RELEASE_CHANNEL`	Optional	Worker release channel, `stable` or `preview`, for hosted worker release selection.
`WORKER_RELEASE_VERSION`	Optional	Explicit worker release version for hosted worker bootstrap.
`LOCAL_SANDBOX_FILES_DIR`	Local development	Local override for sandbox bootstrap files. Used only by development workflows.

Source control providers

Env var	Required	Used for
`NEXT_PUBLIC_GITHUB_APP_SLUG`	GitHub	Browser-visible GitHub App slug.
`GITHUB_APP_SLUG`	GitHub	Alternate setup-time GitHub App slug accepted by source-control setup.
`GITHUB_APP_ID`	GitHub	GitHub App ID.
`GITHUB_APP_PRIVATE_KEY`	GitHub	Raw GitHub App private key PEM, usually with newlines escaped as `\\n`.
`GITHUB_CLIENT_ID`	GitHub	GitHub OAuth client ID.
`GITHUB_CLIENT_SECRET`	GitHub	GitHub OAuth client secret.
`GITHUB_WEBHOOK_SECRET`	GitHub	GitHub webhook secret.
`GITHUB_MCP_SERVER_URL`	Optional	GitHub MCP server URL override.
`GITHUB_AUTOMATED_SKIP_REPOS`	Optional	Repository skip list for automated GitHub processing.
`GITHUB_AUTOMATED_SKIP_OWNERS`	Optional	Owner skip list for automated GitHub processing.
`GITLAB_TOKEN`	GitLab	GitLab personal access token for source-control setup.
`GITLAB_BASE_URL`	Optional	GitLab base URL for self-managed GitLab.
`GITLAB_CLIENT_ID`	Optional	GitLab OAuth client ID.
`GITLAB_CLIENT_SECRET`	Optional	GitLab OAuth client secret.
`GITLAB_WEBHOOK_SIGNING_TOKEN`	Optional	GitLab webhook signing token.
`GITLAB_WEBHOOK_SECRET`	Optional	GitLab webhook secret.
`GITEA_BASE_URL`	Gitea	Gitea base URL.
`GITEA_TOKEN`	Gitea	Gitea access token.
`GITEA_USERNAME`	Optional	Gitea username.
`GITEA_CLIENT_ID`	Optional	Gitea OAuth client ID.
`GITEA_CLIENT_SECRET`	Optional	Gitea OAuth client secret.
`GITEA_WEBHOOK_SECRET`	Optional	Gitea webhook secret.
`ADO_ORGANIZATION`	Azure DevOps	Azure DevOps organization.
`ADO_TOKEN`	Azure DevOps	Azure DevOps access token.
`ADO_BASE_URL`	Optional	Azure DevOps base URL.
`ADO_USERNAME`	Optional	Azure DevOps username.
`ADO_CLIENT_ID`	Optional	Microsoft Entra client ID for Azure DevOps OAuth.
`ADO_CLIENT_SECRET`	Optional	Microsoft Entra client secret for Azure DevOps OAuth.
`ADO_TENANT_ID`	Optional	Microsoft Entra tenant ID for Azure DevOps OAuth. `ROOMOTE_AUTH_MICROSOFT_TENANT_ID` is also accepted.
`ADO_WEBHOOK_SECRET`	Optional	Azure DevOps webhook secret.

Env var	Required	Used for
`SLACK_APP_ID`	Slack app	Slack app ID for communications setup.
`SLACK_CLIENT_ID`	Slack app/auth	Slack OAuth client ID. Also accepted for Slack sign-in setup.
`SLACK_CLIENT_SECRET`	Slack app/auth	Slack OAuth client secret. Also accepted for Slack sign-in setup.
`SLACK_REDIRECT_URI`	Optional	Slack redirect URI override.
`SLACK_AUTH_URI`	Optional	Slack auth URI override.
`SLACK_SIGNING_SECRET`	Slack app/auth	Slack signing secret for webhook verification.
`SLACK_API_BASE_URL`	Optional	Slack API base URL. Defaults to `https://slack.com/api/`.
`SLACK_UNFURL_ALLOWED_DOMAINS`	Optional	Domains Slack unfurl handling may allow.
`SLACK_API_TIMEOUT_MS`	Optional	Slack API timeout. Defaults to `API_EXTERNAL_REQUEST_TIMEOUT_MS` or 10 seconds.
`SLACK_DEBUG_LOGS`	Optional	Set to `true` or `1` to enable extra Slack logs.
`ROUTER_DEBUG_CHANNEL_ID`	Optional	Slack channel ID for router debug output.
`TEAMS_BOT_APP_ID`	Teams	Microsoft Teams bot app ID.
`TEAMS_BOT_APP_PASSWORD`	Teams	Microsoft Teams bot password.
`TEAMS_BOT_TENANT_ID`	Optional	Microsoft Teams bot tenant ID.
`TEAMS_BOT_TOKEN_ENDPOINT`	Optional	Teams bot token endpoint override.
`TEAMS_BOT_OAUTH_SCOPE`	Optional	Teams bot OAuth scope override.
`TELEGRAM_BOT_TOKEN`	Telegram	Telegram bot token.
`TELEGRAM_WEBHOOK_SECRET`	Telegram	Telegram webhook secret.
`TELEGRAM_BOT_USERNAME`	Telegram	Telegram bot username.
`ROOMOTE_AUTH_SLACK_CLIENT_ID`	Slack sign-in	Slack sign-in client ID. `SLACK_CLIENT_ID` is also accepted.
`ROOMOTE_AUTH_SLACK_CLIENT_SECRET`	Slack sign-in	Slack sign-in client secret. `SLACK_CLIENT_SECRET` is also accepted.
`ROOMOTE_AUTH_MICROSOFT_CLIENT_ID`	Microsoft sign-in	Microsoft OAuth client ID.
`ROOMOTE_AUTH_MICROSOFT_CLIENT_SECRET`	Microsoft sign-in	Microsoft OAuth client secret.
`ROOMOTE_AUTH_MICROSOFT_TENANT_ID`	Microsoft sign-in	Microsoft tenant ID. Also accepted as the Azure DevOps tenant ID fallback.
`ROOMOTE_ALLOWED_EMAILS`	Optional	Comma-separated email allowlist for deployments that restrict sign-in by email.

Integrations

Env var	Required	Used for
`LINEAR_CLIENT_ID`	Linear	Linear OAuth client ID.
`LINEAR_CLIENT_SECRET`	Linear	Linear OAuth client secret.
`LINEAR_WEBHOOK_SECRET`	Linear	Linear webhook secret.
`LINEAR_REDIRECT_URI`	Optional	Linear redirect URI override.

Live previews

Env var	Required	Used for
`PREVIEW_PROXY_BASE_URL`	Preview support	Public preview-proxy origin. Overrides Settings > Live Previews when set.
`PREVIEW_DOMAINS`	Optional	Comma-separated preview domains allowed by the preview proxy. Usually derived from `PREVIEW_PROXY_BASE_URL`.
`ROOMOTE_PREVIEW_DOMAIN`	Optional	Roomote preview domain override used by preview runtime analysis.
`PREVIEW_TOKEN_TTL_SECONDS`	Optional	Preview auth token lifetime. Defaults to 3600 seconds.

Observability and request timing

Env var	Required	Used for
`SENTRY_DSN`	Optional	Shared Sentry DSN fallback for Node services that do not have a service-specific DSN.
`NEXT_PUBLIC_SENTRY_DSN`	Optional	Browser and Next.js web Sentry DSN.
`API_SENTRY_DSN`	Optional	API service Sentry DSN. Falls back to `SENTRY_DSN`.
`CONTROLLER_SENTRY_DSN`	Optional	Controller service Sentry DSN. Falls back to `SENTRY_DSN`.
`BULLMQ_SENTRY_DSN`	Optional	BullMQ service Sentry DSN. Falls back to `SENTRY_DSN`.
`WORKER_SENTRY_DSN`	Optional	Worker service Sentry DSN. Falls back to `SENTRY_DSN`.
`API_DEBUG_LOGS`	Optional	Set to `true` or `1` to enable extra API logs.
`API_EXTERNAL_REQUEST_TIMEOUT_MS`	Optional	Default external request timeout. Defaults to 10 seconds.
`API_SLOW_REQUEST_THRESHOLD_MS`	Optional	Threshold for slow API request logging. Defaults to 5 seconds.
`API_SLOW_EXTERNAL_REQUEST_THRESHOLD_MS`	Optional	Threshold for slow external request logging. Defaults to 2 seconds.
`RELEASE_VERSION`	Release images	Baked release version used for release tagging and worker image derivation.
`GITHUB_SHA`	Release metadata	Commit SHA fallback for monitoring release metadata.
`VERCEL_GIT_COMMIT_SHA`	Release metadata	Vercel commit SHA fallback for monitoring release metadata.

Local development and deploy helpers

Env var	Required	Used for
`NGROK_AUTH_TOKEN`	Local callbacks	Lets `pnpm dev` configure ngrok automatically for local public callbacks.
`ROOMOTE_ENV_FILE`	Self-host scripts	Alternate dotenv file for local self-host Compose scripts.
`ROOMOTE_DOCKER_LOAD_ENV_FILE`	Self-host scripts	Compose wrapper flag controlling image-baked dotenv loading. Normally managed by scripts.
`ROOMOTE_APP_DOMAIN`	Production example	Domain helper used by production dotenv examples and Caddy deployment files.
`ROOMOTE_PREVIEW_DOMAIN`	Production example/previews	Preview domain helper used by production dotenv examples and preview runtime config.
`SKILLS_API_URL`	Optional	Skill marketplace/API URL override for skill-related tooling.