The core is configured with environment variables. The complete, current list is in the core README, and it matches the version you run. The settings that matter for security, like key management, are in its SECURITY.md. This page covers the choices behind them.
Required
NOKKU_SECRET, at least 32 characters, or a KMS instead. See Protect the keys.- A PostgreSQL connection, through the standard
PGHOST,PGUSER,PGPASSWORDand related variables. NOKKU_BASE_URL, the host name people and machines reach the core at. See Deploy the core.
Choices to make
| Topic | Options | What to consider |
|---|---|---|
| Reverse proxy | Any proxy that speaks h2c to the core | Trusted as it is on the same machine or a private network. Set NOKKU_TRUSTED_PROXIES for anything else |
| File storage | A local folder, or S3-compatible storage | Holds session recordings. They are encrypted before they are stored, either way |
| Any SMTP relay | Turns on sign-in links and mailed invitations. Without it, passkeys and SSO are the ways in | |
| Key protection | NOKKU_SECRET, or a KMS | A KMS (HashiCorp Vault or Scaleway) holds the key that unlocks everything, instead of the secret |
| Sign-in | Passkeys, email links, OIDC | Providers are set up in the web app. Google and Microsoft can also be seeded from the environment |
| Telemetry | OpenTelemetry, off by default | Traces, metrics and request logs go to your own collector. The log itself only has warnings and errors |
| Operator details | Off by default | Your company name, support address and legal links in the web app and in emails |
Protect the keys
Everything the core encrypts at rest, like the CA’s private keys and SSO client secrets, is unlocked by one key:
NOKKU_SECRETis the simple way. Keep it in your secret manager, and back it up together with the database. One is useless without the other.- A KMS keeps that key out of the environment. Set
KMS_URIinstead of the secret. The core needs the KMS to start, not to sign, so check it before you deploy.
Keys change only through nokku rotate-secrets, run while the core is stopped. It moves you to a new secret or to a KMS, and re-encrypts the secrets in the database. core/SECURITY.md has the steps, the Vault policy and how to keep a Vault token alive.
A rotation does not un-leak anything. If the old secret and a database backup both got out, also roll over the CA.
The first owner
A self-hosted core serves one workspace. It is created on the first start, together with the owner from NOKKU_ADMIN_EMAIL. The owner signs in with the link from nokku recover, see First sign-in. The same command is the way back in for an owner who lost every passkey, so keep shell access to the core for people you trust with the workspace.
Background jobs
The core cleans up after itself: it prunes expired sessions and sign-in links, ends grants and requests on time, and applies retention to audit events and recordings. Nothing to configure.