serene-pub/docs/environment-variables.md

Environment Variables

Serene Pub is configured almost entirely through environment variables rather than a settings file — there's no single config file to hand-edit before first launch. If you're just running Serene Pub on your own computer, you can skip this entire page — every variable below has a sensible default, and a normal local install needs none of them. This page exists for the cases where you do need to change something: a portable install, running behind a reverse proxy, Docker, or tweaking a specific feature's behavior.

Variables can be set however your platform normally sets them (shell export, a process manager, a Docker environment: block, etc.), or by placing a .env file in the directory you launch Serene Pub from — Serene Pub loads .env automatically on startup if one is present. Copying .env.example (in the project root) to .env and editing it is the easiest starting point.

For deployment-specific walkthroughs (reverse proxies, tunnels, Docker), see Hosting Serene Pub and DOCKER.md in the repository. This page focuses on what each variable does; those cover the surrounding setup.

Portable / Self-Contained Setup

The most common reason to open this page: keeping Serene Pub's data in one folder you control (a USB drive, a synced folder, something you back up as a unit) instead of the OS-specific hidden location it uses by default (e.g. under your user profile on Windows, ~/.local/share on Linux, ~/Library/Application Support on macOS).

1. Pick (or create) a folder for the whole portable install, containing the built app (or the platform executable from a release) plus a subfolder for data, e.g.:

   serene-pub-portable/
     Serene Pub.exe        (or the Linux/macOS equivalent)
     data/
   

2. In that same folder, create a .env file:

   SERENE_PUB_DATA_DIR=./data
   

   A relative path resolves against the directory you launch Serene Pub from — so always launch it from inside serene-pub-portable/, not by referencing the executable from elsewhere.
3. Launch normally. On first run, Serene Pub creates the database and meta.json inside data/. From then on, copying the entire serene-pub-portable/ folder anywhere — a different computer, a USB drive — brings your characters, chats, connections, and settings with it.

If you're launching a built app directly with node rather than a packaged executable, prefer Node's own --env-file flag over relying on Serene Pub's automatic .env loading:

node --env-file=.env build/index.js

This guarantees every variable in .env — including SERENE_PUB_DATA_DIR — is set before any code runs at all, rather than depending on module load order. A few variables further down this page (PORT, HOST, PROTOCOL_HEADER, HOST_HEADER, ORIGIN) are read by the underlying server framework itself, before Serene Pub's own .env loading gets a chance to run, so --env-file is the safest choice generally, not just for a portable setup specifically.

Data & Storage

Variable	Default	Description
SERENE_PUB_DATA_DIR	OS-appropriate user data directory	Where the database, meta.json (the secret key backing sessions and stored passphrases), the embedding model cache, and downloaded KoboldCPP binaries/models all live. Set this to keep everything in one folder you control — see Portable / Self-Contained Setup above.

Feature Toggles

Small, self-contained switches for specific features — each is safe to try in isolation.

Variable	Default	Description
SERENE_AUTO_OPEN	unset (a browser tab opens automatically)	Set to 1 or true to disable automatically opening a browser tab when Serene Pub starts.
USER_TOKEN_EXPIRATION_HOURS	168 (7 days)	How long a login session lasts before it expires.
ENABLE_UNSAFE_CHARACTER_BROWSING	unset (hidden)	Set to true to allow the Character Library's "include NSFW" toggle to appear when browsing external card sources (e.g. CharaVault). Still off by default even once enabled — this only unlocks the toggle, it doesn't turn NSFW results on by itself.
PUBLIC_DOCUMENT_VIEW_DEFAULT	false	Set to true to make Document View (the simplified, high-contrast, keyboard- and screen-reader-friendly interface) the default for anyone who hasn't visited yet. Only applies before a given browser has its own stored preference — once someone toggles Document View themselves, that choice always wins, even if this changes later. Useful for an install primarily used by vision-impaired users.

KoboldCPP Managed Mode

Only relevant if you're running KoboldCPP in Managed mode — where Serene Pub downloads and runs the KoboldCPP binary for you rather than you pointing it at a server you run yourself.

Variable	Default	Description
KOBOLDCPP_BINARY_DIR	unset	Directory containing (or where an in-app download should place) the KoboldCPP binary. Only applied on first boot, or if managed mode isn't already configured — an already-working setup is never silently overridden. Useful for a Docker deployment mounting a pre-downloaded binary.
KOBOLDCPP_BINARY_NAME	unset	Filename of a pre-existing binary inside KOBOLDCPP_BINARY_DIR, for pointing at a binary you provided yourself rather than letting Serene Pub download one.

---

Everything below this point is deployment-level configuration — reverse proxies, Docker, hosting Serene Pub for more than just yourself. If that's not what you're doing, you're done reading.

Server & Network

These are read by @sveltejs/adapter-node itself, before Serene Pub's own code runs — see the portable setup note above if changes to them don't seem to take effect.

Variable	Default	Description
PORT	3000	Port the main web server listens on.
HOST	0.0.0.0	Network interface the main web server and the socket server both bind to.
ORIGIN	inferred from the request	Explicit public origin (e.g. https://serene.example.com). Set this if form submissions start failing behind a reverse proxy — SvelteKit uses it for CSRF checks.
NODE_ENV	—	Set to production for a production build (session cookies become Secure-only, among other production-mode behaviors).

Sockets (real-time updates)

Serene Pub runs a second server for real-time updates (chat messages, generation progress, model status) separate from the main web server. If you're putting a reverse proxy or tunnel in front of Serene Pub, it needs to know about this second server too, or real-time features will silently fail even though the page loads fine — see Hosting Serene Pub for worked examples.

Variable	Default	Description
SOCKETS_PORT	3001	Port the real-time server listens on.
SOCKETS_HTTPS_HOSTS	unset	Comma-separated hostnames that should always get an https:// real-time connection, even if the request otherwise looks like plain HTTP (common when a proxy terminates TLS). A host listed here is automatically an allowed origin too.
SOCKETS_ALLOWED_ORIGINS	not needed for most setups	Comma-separated hostnames (no scheme/port) explicitly allowed to open a real-time connection, beyond the automatic default (any origin matching the hostname the request itself arrived on — this already covers localhost, LAN IPs, and any custom domain with zero configuration). Set to the literal value * to disable the allowlist entirely.
SOCKETS_HTTP_MODE	auto-detected	Global protocol override (http or https) applied to every hostname not covered by SOCKETS_HTTPS_HOSTS. Prefer SOCKETS_HTTPS_HOSTS when the app is reachable both directly and through a proxy, since this setting applies everywhere regardless of how a request arrived.
PUBLIC_SOCKETS_ENDPOINT	unset	Full override for the URL the browser connects to for real-time updates (protocol + host + port). Takes priority over everything else above — only needed if none of the other options cover your setup.

Reverse Proxy Trust

Unset by default, meaning Serene Pub does not trust forwarded headers — every request looks like plain HTTP from the proxy's own address, since that's genuinely what the proxy sends. Only set these if you're actually running behind a reverse proxy or tunnel that sets the corresponding header itself.

Variable	Default	Description
HOST_HEADER	unset	Header holding the real client-facing hostname, e.g. x-forwarded-host.
PROTOCOL_HEADER	unset	Header holding the real client-facing protocol, e.g. x-forwarded-proto.
ADDRESS_HEADER	unset	Header holding the real client IP, e.g. x-forwarded-for. Login rate limiting depends on this being set correctly when behind a proxy — without it, every user's failed logins share one bucket (the proxy's own address), so one person locking themselves out can lock everyone out. Only set this when a trusted proxy is actually in front of the app; setting it with no proxy present lets any client bypass rate limiting by sending a spoofed header directly. Serene Pub prints a one-time startup warning if it ever sees a forwarded-for header arrive while this is unset.

Content Security Policy

Serene Pub ships a strict Content-Security-Policy by default; it isn't a header you can disable via an env var. These add extra allowed sources for content your hosting layer injects into the page that isn't part of the app itself — most commonly Cloudflare's "Browser Insights" beacon when a zone is proxied through Cloudflare with that feature on. Prefer disabling such features at the CDN/proxy level over widening these, since it's third-party content the app has no control over.

Variable	Default	Description
CSP_EXTRA_SCRIPT_SRC	unset	Comma-separated extra allowed script sources.
CSP_EXTRA_STYLE_SRC	unset	Comma-separated extra allowed stylesheet sources.
CSP_EXTRA_CONNECT_SRC	unset	Comma-separated extra allowed fetch/XHR/WebSocket targets.

Development Only

These only matter if you're running Serene Pub from source against an external PostgreSQL database for development. A normal install — including every production deployment — uses an embedded database automatically and never needs these.

Variable	Default	Description
DATABASE_URL	localhost	External PostgreSQL host.
DATABASE_PORT	3002	External PostgreSQL port.
POSTGRES_USER	postgres	External PostgreSQL username.
POSTGRES_PASSWORD	password	External PostgreSQL password.