livediagram

Configuration and Optional Auth

The environment variables that shape a self-hosted instance, and how sign-in degrades gracefully to pure-guest mode.

A self-hosted livediagram is configured entirely through environment variables, not code edits. The most important thing to understand is that the optional features are genuinely optional: leave them unset and the editor still works perfectly, just in a simpler mode. This page covers how configuration is supplied and the main toggles you will care about.

How configuration is supplied

Secrets and settings never live in source code, since the repository is public. Instead, each Worker reads them at runtime.

  • Local development uses a gitignored .env.local file per app or Worker.
  • Workers receive secret values via wrangler secret put, and non-secret variables via the Worker's configuration.
  • Static frontends only ever bundle values explicitly marked as publishable, prefixed so it is obvious they are safe to ship to the browser. Server-only secrets stay on the Worker side and never reach client code.

Each app that needs configuration ships an example file documenting which variables it expects, so you can see at a glance what to set.

Optional sign-in

Authentication is provided by an optional integration with Clerk, and the app supports three modes depending on what you configure.

  1. Hybrid, the production setup: both the frontend publishable key and the API's verification URL are set, so guests and signed-in users coexist.
  2. Guest-only, the typical self-host: leave the auth variables unset. The app runs without an account system, sign-in routes show a friendly "not enabled" notice, and the editor is unchanged.
  3. A partial misconfiguration (frontend configured, API not) exists only for debugging and is not meant for production.

This is what lets a self-hoster run with zero outbound runtime traffic beyond their own hosting if they want to.

Guest-only fallback

The API identifies the owner of a request in one of two equivalent ways: a verified sign-in token, or a per-browser guest id sent as a header. When sign-in is not configured, every request simply uses the guest path, and the editor stays fully usable, with persistence, sharing, and real-time collaboration all working.

Other optional toggles follow the same pattern: telemetry is off unless explicitly enabled, and AI assistance only appears when an AI key is configured on the API Worker. Unset means off, every time.

For the exact variable names and where each one lives, follow the repository's docs/self-hosting.md and each app's example configuration file.

Was this article helpful?