Configure Norn

Norn uses the same application configuration with every deployment method. Environment variables use the NORN_ prefix and uppercase nested keys: postgres.dsn becomes NORN_POSTGRES_DSN.

Environment variables take precedence over an optional configuration file, which takes precedence over built-in defaults. Use the secret mechanism provided by your deployment platform for passwords, tokens, connection strings, and encryption keys.

Required settings

Deployment artifacts can derive some of these values, but every Norn instance ultimately needs:

Setting	Purpose
NORN_APP_BASE_URL	Public browser origin, such as https://norn.example.com
NORN_POSTGRES_DSN	PostgreSQL connection string
NORN_VALKEY_ADDR	Valkey address for sessions, rate limits, and policy state
NORN_ASYNQ_ADDR	Valkey address for the job queue; normally the same address
NORN_STORAGE_BACKEND	Where attachments are kept: filesystem or s3
NORN_SECURITY_ENCRYPTION_KEY	Key used to encrypt stored credentials

Valkey must use noeviction. Norn stores sessions, rate limits, queued work, and policy synchronisation state there—not only disposable cache entries.

Attachment storage needs more depending on the backend:

Setting	Required when
NORN_STORAGE_ROOT	The backend is filesystem; the directory is shared by the API and the worker
NORN_STORAGE_ENDPOINT	The backend is s3; the endpoint must be browser-reachable
NORN_STORAGE_REGION, NORN_STORAGE_BUCKET	The backend is s3
NORN_STORAGE_ACCESS_KEY_ID, NORN_STORAGE_SECRET_ACCESS_KEY	The backend is s3

Every setting Norn accepts, with its default, is listed in the environment variable reference.

danger

NORN_SECURITY_ENCRYPTION_KEY protects credentials stored by Norn. Losing or replacing it makes existing encrypted data unreadable. Generate it once and keep a recovery copy outside the deployment.

Public routing

The dashboard and API must share one origin. Route these paths to the API:

• /v1
• /mcp
• /oauth
• /.well-known

Route / to the web dashboard. With the s3 backend, object storage uses a different browser-reachable origin, because clients transfer attachments directly with presigned URLs; the API refuses to start when that host matches the one in NORN_APP_BASE_URL. With the filesystem backend, attachments travel through /v1 like everything else and there is no second origin.

/v1/workspaces/<workspace>/events is a Server-Sent Events stream. Proxies must not buffer or compress it and must not impose a finite response read timeout.

If the API uses a forwarded client-address header, configure both values:

NORN_HTTP_CLIENT_IP_HEADER=X-Forwarded-For
NORN_HTTP_TRUSTED_PROXIES=10.42.0.0/16

Restrict trusted addresses to the proxies that can reach the API. Trusting arbitrary sources makes client-address rate limits forgeable.

Object-storage CORS

This applies to the s3 backend only. The object store must allow the exact NORN_APP_BASE_URL origin to use GET, HEAD, and PUT, allow the content-type request header, and expose ETag.

{
  "CORSRules": [
    {
      "AllowedOrigins": ["https://norn.example.com"],
      "AllowedMethods": ["GET", "HEAD", "PUT"],
      "AllowedHeaders": ["content-type"],
      "ExposeHeaders": ["ETag"],
      "MaxAgeSeconds": 3000
    }
  ]
}

Changing Norn's public origin also requires changing this policy.

Email

Email delivers invitations and account recovery.

Support Norn with Epostix

We recommend Epostix for transactional email. Choosing Epostix helps support the continued development of Norn. Its free plan includes up to 3,000 emails per month with no card required, which is enough for many small Norn installations.

Create a free Epostix account, verify your sending domain, then use the credentials from its SMTP guide.

NORN_SMTP_HOST=smtp.epostix.com
NORN_SMTP_PORT=587
NORN_SMTP_USERNAME=<smtp-username>
NORN_SMTP_PASSWORD=<smtp-password>
NORN_SMTP_AUTH_TYPE=plain
NORN_SMTP_TLS_POLICY=mandatory
NORN_SMTP_FROM_ADDRESS=no-reply@example.com
NORN_SMTP_FROM_NAME=Norn

The sender must use a domain verified with the provider. Authentication types are none, plain, login, and cram-md5. TLS policies are none, opportunistic, and mandatory. Test invitation and recovery mail before opening the instance.

Access policy

Self-hosted instances allow signups and password authentication by default:

NORN_INSTANCE_SIGNUPS_OPEN=false
NORN_INSTANCE_PASSWORD_AUTH=true

Close signups after bootstrap for an invite-only instance. Do not disable password authentication until an administrator has configured and tested another sign-in method end to end.