> ## Documentation Index > Fetch the complete documentation index at: https://docs.omnara.com/llms.txt > Use this file to discover all available pages before exploring further. # Configuration > Environment-variable reference for every control-plane process All configuration is via environment variables. Use `.env.example` in the repo as a starting point. **Required** refers to production. Setting `OMNARA_ALLOW_INSECURE_DEV_DEFAULTS=1` fills the fallbacks marked *dev* below (local Compose services, console email, an insecure secret-encryption key). Never set it in production. ## Core | Variable | Purpose | Default | Required | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | -------- | | `OMNARA_PUBLIC_URL` | Public app origin used in emails, browser links, and OAuth callbacks. Origin only, no path; HTTPS outside localhost. Set identically on API, worker, and maintenance. | — | Yes | | `OMNARA_PUBLIC_API_URL` | Public base URL of the versioned API as daemons and machines reach it, including the version path. Its origin also serves `/install/omnarad.sh`. Set it identically on API, worker, and maintenance when the API is served from a different host than `OMNARA_PUBLIC_URL`. HTTPS outside localhost. | `OMNARA_PUBLIC_URL` + `/api/v1` | No | | `OMNARA_BILLING_URL` | External billing page linked from the dashboard; the UI appends `?org={org-id}`. HTTPS outside localhost, no query parameters. Leave unset to hide billing in the dashboard. | — | No | | `OMNARA_API_ADDR` | Public listen address of `api` | `:8080` | No | | `OMNARA_API_METRICS_ADDR` | `api` health/metrics listener | `:8081` | No | | `OMNARA_WORKER_METRICS_ADDR` | `worker` health/metrics listener | `:8082` | No | | `OMNARA_MAINTENANCE_METRICS_ADDR` | `maintenance` health/metrics listener | `:8083` | No | | `OMNARA_LOG_LEVEL` | `debug`, `info`, `warn`, or `error` | `info` | No | | `OMNARA_ALLOW_INSECURE_DEV_DEFAULTS` | `1` enables local-development fallbacks | unset | No | | `OMNARA_WORKER_CAPACITY` | Maximum agent turns executed concurrently by each worker process | `4` | No | | `OMNARA_WORKER_ASYNC_TOOL_CAPACITY` | Maximum runtime-owned asynchronous tool calls in flight per worker process | `32` | No | | `OMNARA_WORKER_BACKGROUND_TOOL_CAPACITY` | Background tool concurrency and in-memory queue capacity per worker process | `8` | No | | `OMNARA_MAINTENANCE_INTERVAL` | Maintenance loop interval (Go duration) | `1s` | No | ## Database and Redis | Variable | Purpose | Default | Required | | -------------------------- | ---------------------------------------------------------------------------------------------- | --------------------------------- | -------- | | `OMNARA_DATABASE_URL` | Postgres connection string used by `migrate` and the three long-running control-plane services | *dev:* local Compose Postgres | Yes | | `OMNARA_REDIS_URL` | Redis or Valkey URL | *dev:* `redis://127.0.0.1:6379/0` | Yes | | `OMNARA_MIGRATIONS_DIR` | Directory containing schema migrations; used only by `cmd/migrate` | `migrations` | No | | `OMNARA_MIGRATION_TIMEOUT` | Overall deadline for the one-shot migration process (Go duration) | `30m` | No | PostgreSQL 18 or newer is required. The API, worker, and maintenance services default to a pool of 1–10 connections, a 30-minute idle timeout, a 30-minute connection lifetime, and five minutes of lifetime jitter. Override these with `pool_*` settings in `OMNARA_DATABASE_URL`, and budget connections across all service replicas. Direct PostgreSQL, RDS Proxy, and PgBouncer session pooling work with these settings. PgBouncer transaction pooling requires `max_prepared_statements > 0`; statement pooling is not supported. The migrator defaults to a 30-second lock timeout and a 15-minute statement timeout. Explicit values in `OMNARA_DATABASE_URL` take precedence. ## Web serving and proxy | Variable | Purpose | Default | Required | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------- | | `OMNARA_WEB_SERVING` | `embedded` serves a SPA compiled into `cmd/api`; `disabled` leaves web assets to a separate service. The official cluster API image contains no frontend assets and sets this to `disabled`; the cluster web image serves only static assets and does not proxy API traffic. | `disabled` | No | | `OMNARA_TRUSTED_PROXY_CIDRS` | Comma-separated proxy/load-balancer hop CIDRs whose `X-Forwarded-For`/`X-Real-IP` are trusted for auth rate limiting. Only hops you control. | — | No | ## Email Signup and password reset send email through `OMNARA_EMAIL_DRIVER`. In production, use `smtp` or `sendgrid` — or disable both flows with `OMNARA_AUTH_SIGNUP_ENABLED=0` and `OMNARA_AUTH_PASSWORD_RESET_ENABLED=0`. | Variable | Purpose | Default | Required | | ----------------------------------------------- | --------------------------------------------------- | ------------------------- | ------------------------------- | | `OMNARA_EMAIL_DRIVER` | `none`, `console` (dev only), `smtp`, or `sendgrid` | `none` (*dev:* `console`) | When signup or reset is enabled | | `OMNARA_EMAIL_FROM` | Sender address | — | With `smtp` or `sendgrid` | | `OMNARA_SMTP_ADDR` | SMTP server `host:port` | — | With `smtp` | | `OMNARA_SMTP_USERNAME` / `OMNARA_SMTP_PASSWORD` | SMTP credentials; set both or neither | — | No | | `OMNARA_SMTP_REQUIRE_TLS` | Require STARTTLS; disabling is dev-only | `1` | No | | `SENDGRID_API_KEY` | SendGrid API key | — | With `sendgrid` | ## Auth and SSO connectors | Variable | Purpose | Default | Required | | ------------------------------------ | ----------------------------------------- | ------- | -------- | | `OMNARA_AUTH_SIGNUP_ENABLED` | First-party password signup | `1` | No | | `OMNARA_AUTH_PASSWORD_RESET_ENABLED` | Password reset flow | `1` | No | | `OMNARA_AUTH_CONNECTORS_JSON` | JSON array of social/SSO login connectors | — | No | GitHub uses `kind:"github"` (endpoints default to github.com; GitHub-compatible providers must supply `issuer`, `authorization_url`, `token_url`, and `userinfo_url`). Google and generic SSO providers — Keycloak, Okta, Auth0, Azure, ZITADEL — use `kind:"oidc"` with issuer discovery. An example is shown below: ```sh theme={null} OMNARA_AUTH_CONNECTORS_JSON='[ {"slug":"github","kind":"github","display_name":"GitHub","client_id":"{id}","client_secret":"{secret}"}, {"slug":"google","kind":"oidc","display_name":"Google","issuer":"https://accounts.google.com","client_id":"{id}","client_secret":"{secret}","email_trust_policy":"verified_email"} ]' ``` ## Secret encryption Secret values are envelope-encrypted with keys from this ring. | Variable | Purpose | Default | Required | | ---------------------------------------- | ---------------------------------------------------------- | ------------------------------- | -------- | | `OMNARA_SECRET_ENCRYPTION_KEYS` | JSON object of key ID to base64 32-byte key (the key ring) | *dev:* insecure `dev-local` key | Yes | | `OMNARA_SECRET_ENCRYPTION_ACTIVE_KEY_ID` | Key ID used to wrap new writes; must exist in the ring | *dev:* `dev-local` | Yes | Generate each key with `openssl rand -base64 32`. To rotate: add the new key to the ring, set it active, rewrap stored versions, then remove the old key once nothing references it. ## Skill download capabilities Skill archive offers use a short-lived capability bound to one machine, skill, and revision. | Variable | Purpose | Default | Required | | ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | -------- | | `OMNARA_SKILL_DOWNLOAD_SIGNING_KEY` | Base64-encoded 32-byte HMAC key for machine-bound skill download capabilities; generate with `openssl rand -base64 32` and set the same value on API and worker | *dev:* insecure local key | Yes | ## Blob storage Artifact content lives in S3-compatible object storage; a bucket is required. | Variable | Purpose | Default | Required | | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------ | -------- | | `OMNARA_BLOB_S3_BUCKET` | Bucket for artifact content | *dev:* Compose MinIO bucket `omnara` | Yes | | `OMNARA_BLOB_S3_REGION` | Bucket region | — | No | | `OMNARA_BLOB_S3_ENDPOINT` | Custom endpoint for MinIO or other S3-compatible stores; HTTPS outside localhost | — | No | | `OMNARA_BLOB_S3_ACCESS_KEY_ID` / `OMNARA_BLOB_S3_SECRET_ACCESS_KEY` | Static credentials; set both or neither. Leave empty to use the AWS default credential chain. | — | No | | `OMNARA_BLOB_S3_USE_PATH_STYLE` | `1` for path-style addressing (MinIO) | `0` | No | ## Machine daemon and pools ### API daemon configuration | Variable | Purpose | Default | Required | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------- | -------------------------------------------- | -------- | | `OMNARA_DAEMON_SOCKET_FALLBACK_DRAIN_INTERVAL` | API-side fallback drain floor for connected daemon sockets when Redis wakeups are missed | `30s` | No | | `OMNARA_DAEMON_SOCKET_FALLBACK_DRAIN_JITTER` | Jitter added to the fallback drain; must not exceed the interval | `10s` | No | | `OMNARA_DAEMON_RELEASE_URL` | Platform-manifest directory embedded in the hosted `omnarad.sh` installer | `https://releases.omnara.com/omnarad/latest` | No | | `OMNARA_DEFAULT_MACHINE_POOL_TEMPLATES` | Path to a YAML file of default pool templates; when set, new orgs get cluster-managed machine pools | — | No | | `OMNARA_UNIKRAFT_DEFAULT_POOL_TOKEN` | Provider token read by the example default-pool template; default-pool provider tokens stay in env | — | No | Machine pool templates automatically create a base machine pool for any new organization. The supported providers are listed below: | Provider | CPU fields | `provider_config` | `default_machine_provider_options` | | ---------- | ----------------------------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `unikraft` | Default and maximums required; minimum optional | Optional `api_base_url`, `allowed_images`, and `allowed_metros` | `image`, `metro`, and optional `startup_script` and `sleep_after_ms` | | `blaxel` | Omit all CPU fields | Required `workspace`; optional `allowed_images` and `allowed_regions` | Blaxel sandbox `image`, `region`, and optional `startup_script` and `sleep_after_ms` | | `daytona` | Maximums required; default and minimum optional | Optional `api_base_url`, `allowed_snapshots`, and `allowed_targets` | Daytona snapshot name, `target`, and optional `startup_script` | Provider notes: * Custom pool images must provide a writable `HOME` or `OMNARA_HOME`, plus a POSIX shell, standard Unix utilities, `curl`, and `sha256sum` or `shasum` for the Omnara launcher (`startup_script` additionally requires `base64`). * Blaxel images must be sandbox images built or pushed through Blaxel (custom images must include `sandbox-api`), and unlimited persistence requires quota Tier 2 or higher — Tier 0 and Tier 1 cap sandbox lifetimes at 7 and 30 days. * Daytona snapshots are allowed by name, must be active in the selected target, must allow sandboxes to reach `OMNARA_PUBLIC_URL`, and their API-resolved CPU and memory count against the pool caps. * For Unikraft and Blaxel, `sleep_after_ms` enables scale-to-zero after that many milliseconds of daemon inactivity; omit or `0` disables it, and enabled values must be at least `30000`. ### Operator-provisioned default model provider An installation can give each new organization a model provider without storing the upstream credential in configuration. Leave these variables unset to let organization owners configure providers themselves. | Variable | Purpose | Default | Required | | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ------- | -------------------------------- | | `OMNARA_DEFAULT_MODEL_PROVIDER_TEMPLATE` | Path to the provider and model template on the API and maintenance. See `default-model-provider-example.yaml`. | — | No | | `OMNARA_HOSTED_API_URL` | Base URL of the operator credential service. Used by the API and maintenance. | — | With a default provider template | | `OMNARA_HOSTED_API_TOKEN` | Bearer token shared with the operator credential service; at least 32 bytes. Used by the API and maintenance. | — | With a default provider template | The credential service contract has these invariants: * `POST /model-provider-credentials` receives the organization ID, creator user ID, and provider template. A successful response is `201` with `{"credential_value":"..."}`; `202` and `5xx` are retryable, while `409` represents a durable identity or provisioner conflict. * The organization ID is the stable issuance identity. The same request may be repeated until Omnara commits the credential, provider, models, grants, and job completion together. The credential service must recover ambiguous issuance without returning an unusable credential. * Organization creation never depends on credential issuance. The API attempts provisioning after commit, and maintenance retries failures. * Apply migrations before deploying both binaries. The API and maintenance must use the same template, credential-service configuration, and secret-encryption key ring. ### Host daemon configuration | Variable | Purpose | Default | | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | `OMNARA_HOME` | Binary, configuration, logs, locks, and runtime state | `$HOME/.omnarad` | | `OMNARA_API_URL` | API root URL, including the `/api/v1` mount for self-hosted deployments; HTTP is accepted only for loopback or `host.docker.internal` during local development | Existing `daemon.json` value, otherwise `https://api.omnara.com/v1` | | `OMNARA_MACHINE_TOKEN` | Machine token; prompted for by the installer when omitted | Existing `daemon.json` value | | `OMNARA_NO_UPDATE` | Set to `1` or `0` to temporarily disable or enable managed updates | Existing `daemon.json` value, otherwise `0` | | `OMNARA_RUNNER_PATH` | Temporary `PATH` override for agent commands | Existing `daemon.json` value, otherwise the installation `PATH` | | `OMNARA_DAEMON_SEED_PATH` | Existing `omnarad` binary used only to seed a fresh installer-owned home | — | ## Web tools Web tools work out of the box: `web_fetch` has no vendor dependency, and `web_search` defaults to Exa's keyless endpoint. | Variable | Purpose | Default | Required | | ------------- | ----------------------------------------------------------------------------------------------- | ------- | -------- | | `EXA_API_KEY` | Upgrades `web_search` to the direct Exa API; recommended for hosted or multi-tenant deployments | — | No |