Environment variables

Configure variables in the env files or secret strategy for your deployment. Restart source processes or recreate containers/pods after changes; a running process does not reread credentials.

Production Compose derives DATABASE_URL and BETTER_AUTH_URL on its service definitions, overriding values in .env. Use POSTGRES_* and NEXT_PUBLIC_APP_URL there. Helm constructs the database URL from its database values. See Docker and Kubernetes secret strategies.

Required

openssl rand -hex 32 prints 64 hex characters. Encryption keys require that format. The app skips its env schema validation; individual consumers can reject invalid values when first used. Realtime validates BETTER_AUTH_SECRET and INTERNAL_API_SECRET at boot and rejects values shorter than 32 characters.

Feature prerequisites and coordination

AI providers

Knowledge bases use an embedding model independent of the chat model. See Knowledge bases for supported providers, local Ollama, and vector widths.

For provider-key rotation, configure _1, _2, and _3 keys, such as OPENAI_API_KEY_1 and OPENAI_API_KEY_2. OpenAI, Anthropic, Gemini, xAI, Kimi, Z.ai, Cohere, and Fireworks support numbered keys.

For Ollama on the Docker host, use OLLAMA_URL=http://host.docker.internal:11434 and ensure its server is reachable from the container.

Catalog visibility

AWS Bedrock

Azure OpenAI

Azure Anthropic

Document OCR

Self-hosted OpenAI-compatible endpoints

Knowledge bases

KB_EMBEDDING_MODEL and EMBEDDING_OUTPUT_DIMS apply to new knowledge bases. Existing bases retain their recorded model and width, and bases with different settings cannot be searched together.

For hosted models, Sim checks catalog-supported widths and falls back to the model's default on invalid configuration. For Ollama, leave EMBEDDING_OUTPUT_DIMS unset to infer the model's width; creation fails if Sim cannot establish a supported width. If you set it explicitly, a mismatch can fail document processing. Example pairings:

For Compose or a source checkout, run bunx sim-setup add knowledge-embeddings to choose OpenAI, Azure OpenAI, OpenRouter, Gemini, or Ollama and write its configuration. The three OpenAI-family transports share model/width choices. bunx sim-setup config reports the family selected by KB_EMBEDDING_MODEL. For Helm, set the variables through chart values or your secret strategy. Run Ollama yourself; the setup command configures a connection, not an Ollama installation.

The Embeddings block reads the same OLLAMA_URL. It lists the models on that server that report an embedding capability, with the width each one emits where Ollama reports it, so a workflow can embed locally without an API key. Ollama only began reporting capabilities in 0.5 — against an older server nothing can be filtered, so the list includes chat models and labels none of them with a width. Check what you pick there, or upgrade Ollama.

Login providers

Google, GitHub, and Microsoft sign-in, their callback URLs, and the DISABLE_*_AUTH switches are documented in Authentication.

Integration credentials

OAuth integrations require a provider application and its credentials on a self-hosted deployment. API-key integrations use the keys supplied in their blocks. The full table, redirect-URI format, and setup steps are in Integrations and OAuth.

Access control

Who may sign up and sign in — the allowlists, blocklists, DISABLE_REGISTRATION, DISABLE_INVITATIONS, DISABLE_PUBLIC_API, and DISABLE_AUTH — is documented in Authentication.

Code execution

Plain JavaScript without imports runs in isolated-vm within Node child workers in the app container. Python, Shell, imported JavaScript, sandbox/file-path execution, and Pi require the corresponding remote provider and image configuration. See Sandboxes for the base-image build and Security for the isolation comparison.

Chat and PII

Enterprise features

On standard billing-disabled self-hosted deployments, configuration enables enterprise features. Per-feature flags override the suite switch. Billing-enabled deployments also have plan/entitlement gates; see Self-hosted enterprise features.

Most enterprise features read their settings from the organization that owns a workspace, so enabling the flags alone is not enough — the deployment also needs an organization model. See the self-hosted enterprise guide for the per-feature flags, both organization patterns, and the Admin API.

File storage

By default Sim writes uploads to local disk. Neither stock production Compose nor the default Helm chart mounts the upload directory, so configure cloud storage or a persistent local layout before retaining files. See Object storage for the full setup, bucket layout, and IAM policy.

Email providers

Configure at least one. Every configured provider stays active and is tried in order — Resend → AWS SES → SMTP → Azure Communication Services → Gmail — falling through only on failure. With none configured, mail is silently not sent. The variables for each provider, plus setup, verification, and troubleshooting, are in Email.

Networking and execution limits

A malformed entry in either allowlist stops the app at startup with a message naming the setting. See the SSRF boundary for the accepted syntax and for what the allowlist does and does not reach.

Most /api routes also pass through Next.js Proxy, which buffers only the first 10 MiB with the current app configuration. Raising these variables or an external proxy limit does not raise that buffer. See Request size limits for the layers to configure.

Limits

With BILLING_ENABLED disabled, hosted-plan execution rates/timeouts and table/storage quotas are not enforced unless you set their free-tier variables. Independent protocol, body-size, concurrency, and security rate limits still apply. Billing-enabled deployments enforce their plan limits. Keep BILLING_ENABLED and NEXT_PUBLIC_BILLING_ENABLED consistent so enforcement and the UI agree.

Retention cleanup is separately opt-in through DATA_RETENTION_ENABLED or the enterprise suite. A configured retention policy still applies without billing; see Data retention.

Without billing, accounts resolve to the free tier for these counters. Each explicit free-tier variable enables only its corresponding limit.

Current stock Compose and Helm configuration do not preset these free-tier caps. Charts before 1.5.0 did; inherited values can still reach upgraded pods.

Remove an inherited limit

If a limit remains after upgrading, inspect the pod's configuration for inherited values, such as FREE_TABLES_LIMIT or FREE_TABLE_ROWS_LIMIT from a chart older than 1.5.0 or your own values file. On Helm, remove the key by overriding it with null:

app:
  envDefaults:
    FREE_TABLES_LIMIT: null
    FREE_TABLE_ROWS_LIMIT: null

Setting the variable to an empty string does not remove it: the chart reads an empty value as "not specified", so the inherited value still applies.

Null the variable in every layer that sets it. If it appears in both app.env and app.envDefaults, nulling only the app.env entry lets the envDefaults value apply again and the limit stays in force. With External Secrets, also drop the key from externalSecrets.remoteRefs.app, which keeps syncing it independently. Confirm what the pod will actually receive before rolling out:

helm template sim oci://ghcr.io/simstudioai/charts/sim --version 1.11.8 -f values.yaml | grep -A1 FREE_TABLE   # expect no output

null deletion has no effect under helm upgrade --reuse-values — pass your full values with -f, or use --reset-then-reuse-values (Helm 3.14+). If you deploy with Argo CD, put the null in valueFiles or the values string rather than valuesObject, which strips nulls. On Docker Compose, delete the line from your .env file.

Observability

See Observability.

Example .env

# App/source-checkout example: replace placeholders before use.
# Production Compose derives its DSN from POSTGRES_* instead.
DATABASE_URL=postgresql://<user>:<password>@<host>:5432/simstudio?sslmode=require
NEXT_PUBLIC_APP_URL=https://sim.yourdomain.com
BETTER_AUTH_URL=https://sim.yourdomain.com

# Secrets — generate each with `openssl rand -hex 32`
BETTER_AUTH_SECRET=<openssl rand -hex 32>
ENCRYPTION_KEY=<openssl rand -hex 32>
INTERNAL_API_SECRET=<openssl rand -hex 32>
API_ENCRYPTION_KEY=<openssl rand -hex 32>
CRON_SECRET=<openssl rand -hex 32>

# Coordination (required past one replica)
REDIS_URL=redis://redis:6379

# Models — OPENAI_API_KEY also powers knowledge base embeddings
OPENAI_API_KEY=sk-...

# Email
RESEND_API_KEY=re_...
FROM_EMAIL_ADDRESS="Sim <noreply@yourdomain.com>"

# Access control
ALLOWED_LOGIN_DOMAINS=yourdomain.com

This is an app/source-checkout example, not a replacement for the Compose setup or Helm values. See apps/sim/.env.example for additional options.

Related docs

• Authentication
• Verify your install
• Security