Setup

Configuration

Server settings, environment variables, and the admin console.

Settings registry

Most runtime knobs live in the database-backed settings registry and are edited in the admin console (/admin) — branding, registration, legal documents, retention, SMTP, rate limits, upload limits, bots.

Environment

The required environment is two values, TYTO_VERSION and SERVER_DOMAIN, plus CORS_ALLOW_ORIGIN when you run a web client. Everything else has a working default:

  • CORS_ALLOW_ORIGIN — origins of your web clients (space- or comma-separated; several web clients are fine). With no web client, leave it out of .env altogether. The desktop app is allowed separately and needs no entry here.
  • Secrets (database passwords, Meilisearch master key, LiveKit key/secret, JWT/Mercure/media/VAPID app keys) are auto-generated into the shared secrets volume on first boot by the secrets-init service. Any of them set in .env overrides the generated value — that’s the path for a managed database or an external LiveKit.
  • Public URLs (DEFAULT_URI, SERVER_API_URL, LIVEKIT_PUBLIC_URL, Mercure) derive from SERVER_DOMAIN, the API’s public hostname. Behind a reverse proxy (BEHIND_PROXY=true) SERVER_DOMAIN stays that real public hostname; set the URLs explicitly only if they differ from it.
  • MAILER_DSN is an optional fallback — real SMTP lives in the admin panel.

The full variable-by-variable reference — proxy and port overrides, voice, external services, the auto-generated secrets — is in Advanced configuration; the same list ships annotated as .env.prod.example in the core repo.

Email

Configure SMTP in Admin → Settings → Email, including the From address used for registration and digest mail. A test-email button verifies the configuration end to end.

Desktop clients

The desktop app talks to your server from the origin app://tyto. Core allows that origin by default, on top of whatever CORS_ALLOW_ORIGIN contains — a server works with the desktop app out of the box, and an API-only server with no web client works too. Only the desktop app can produce that origin; a browser can’t.

  • Refusing desktop clients — set CORS_ALLOW_DESKTOP_APP=0.
  • Core older than 1.0.0-beta.5 — add app://tyto to CORS_ALLOW_ORIGIN by hand. Without it the app’s wizard reports the server as unreachable.
  • A narrowed MERCURE_CORS_ORIGINS — add app://tyto there as well, or the app connects but gets no live updates. The default allows every origin.