Configuration

The handful of variables that have to be in the environment, and why everything else is not.

Almost nothing is configured through the environment. The rule is: if you need it to open the database, it is a variable. Everything else is a setting inside the app.

That is deliberate. A Slack callback URL is per-domain and can never be ours, so it has to be editable by whoever runs the install, which means a screen. Two sources of truth for the same value is how a hosted build and a self-hosted build silently drift apart, so there is only one.

The bootstrap floor

Variable	Default	What it does
CRAFTSPACE_URL	http://localhost:8080 in development, https://craftspace.app otherwise	The address people reach this install on. Everything else derives from it, so a container that leaves it unset builds its sign-in and MCP URLs for craftspace.app, and a binary builds them for localhost. Set it either way.
PORT	8080	Listen port.
HOST	0.0.0.0	Listen address.
CRAFTSPACE_HOME	/data in production	Where the database, secrets and assets live.
TRUSTED_HOSTS	localhost:5173,localhost:8080	Extra hosts allowed to mint their own auth base URL.
LOG_LEVEL	info

The derived origins (PUBLIC_URL, APP_URL, BETTER_AUTH_URL, MCP_RESOURCE_URL) can each be set explicitly if the install is spread across more than one hostname. On a single domain, leave them alone.

Optional

Variable	What it does
RESEND_API_KEY	Sends sign-in codes and invites. Without it they print to the server log.
SIGN_IN_FROM_EMAIL	The from address on those emails.
BROKER_URL	The install that lends OAuth clients to this one. Empty means you register your own.
FILE_STORAGE	postgres (default) or s3 for attachments and artifacts.
S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY	Used when FILE_STORAGE=s3.
OPENROUTER_API_KEY	Fallback for local development. The real key is a server setting.
DISCORD_EVENTS_WEBHOOK_URL	Reports signups and sign-ins to a Discord channel. Empty by default, and nothing is reported anywhere unless you set it.

Secrets you do not set

The session secret, the sealed-box keypair that connection credentials are encrypted under, and the bearer on the loopback call into the connection gateway are all generated on first boot and kept in the database.

They are in the database on purpose. On a platform with an ephemeral filesystem, a keypair in a file would be regenerated on every deploy, and a rotated sealing key makes every connection credential already stored permanently unopenable. Sessions dropping is the loud half of that. Unreadable connections is the silent, unrecoverable half.

Rotation

Changing a vendor credential in the environment after first boot does nothing. Environment seeded the credential table once, and nothing reads it again. Rotate in server settings.