Configuration

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:

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

Get started

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Examples

Core

Database and Redis

Web serving and proxy

Email

Auth and SSO connectors

Secret encryption

Skill download capabilities

Blob storage

Machine daemon and pools

API daemon configuration

Operator-provisioned default model provider

Host daemon configuration

Web tools

​Core

​Database and Redis

​Web serving and proxy

​Email

​Auth and SSO connectors

​Secret encryption

​Skill download capabilities

​Blob storage

​Machine daemon and pools

​API daemon configuration

​Operator-provisioned default model provider

​Host daemon configuration

​Web tools

Core

Database and Redis

Web serving and proxy

Email

Auth and SSO connectors

Secret encryption

Skill download capabilities

Blob storage

Machine daemon and pools

API daemon configuration

Operator-provisioned default model provider

Host daemon configuration

Web tools