Configuration#

Sugar loads deployment settings from the process environment and stores runtime state under SUGAR_DATA_DIR.

Before you start#

Choose the final public HTTPS APP_URL before enrolling passkeys.
Generate independent values for authentication and credential encryption.
Restrict environment and data-directory permissions to the service account.

Required production settings include:

Variable	Purpose
`APP_URL`	Final public origin.
`ACCESS_CODE`	One-time owner bootstrap secret.
`AUTH_SECRET`	Browser session and authentication secret.
`SUGAR_CREDENTIAL_KEY`	Stable 64-hex-character provider credential key.
`SUGAR_DATA_DIR`	Persistent database and application state directory.
`PORT`	Optional listening port; defaults to 3211.

Keep the credential key stable across upgrades; losing it makes stored provider credentials unreadable.

Proxy and request settings#

Variable	Default	Effect
`SUGAR_TRUSTED_CLIENT_IP_HEADER`	unset	Names the single header your reverse proxy overwrites with the caller's address, for example `x-real-ip`. Set it in every proxied deployment.
`SUGAR_REQUEST_TIMEOUT_MS`	`115000`	How long one uncommitted request may spend trying candidate lanes, clamped to 10,000–280,000. The value is honoured by the upstream request itself, so raising it lets a slow lane finish. It stops applying once a provider answers 200, after which the stream idle watchdog takes over.

Without a trusted client-IP header, Sugar cannot name the caller's address, and sign-in throttling keeps only the per-identifier bucket. The service prints a start-up warning in production when the variable is unset.

Secrets and diagnostics#

Variable	Default	Effect
`SUGAR_CONDUIT_DIGEST_SECRET`	unset	Independent HMAC key for Conduit's one-way correlation digests. Unset falls back to `AUTH_SECRET`, then `ACCESS_CODE`; one of the three must be set. Set an independent secret before production — rotating it invalidates every digest already written.
`SUGAR_METRICS_MEMBER_SERIES`	`25`	Per-member quota series exported by the metrics endpoint, clamped 0–200. `0` exports the workspace roll-up only.
`SUGAR_RELEASE_SHA`	unset	Labels the deployed commit in the metrics build information. Set it to the release commit the service unit is serving.
`SUGAR_ROUTE_SURFACE_MANIFEST`	unset	Absolute path to a route-surface manifest for the health check to read instead of the one beside the running build. Setting it also skips the build-identifier comparison that catches a stale manifest. Leave it unset in production.

Sugar warns on standard error when a write it expected to succeed did not. Each warning carries identifiers, a code and a status, never prompt or completion content. Set a variable to off to silence one.

Variable	Default	Warns about
`SUGAR_SERVER_WARN`	on in production, off elsewhere	A 5xx response, as its error code, HTTP status, route path and request id. Set `on` to narrate a local run.
`SUGAR_REQUEST_LEDGER_WARN`	on	A gateway request ledger write that failed.
`SUGAR_CONDUIT_DECISION_WARN`	on	A Conduit decision row that could not be recorded.
`SUGAR_RECEIPT_WARN`	on	Receipt signing or verification problems.
`SUGAR_CONDUIT_DIGEST_WARN`	on	Conduit digests keyed from `ACCESS_CODE` because no stronger secret is configured.

A permanently failing ledger otherwise looks exactly like no traffic at all, which is why the write warnings are on everywhere.

Provider credentials#

Managed provider keys may be supplied through their documented environment variables or entered through the encrypted Providers page. Self-hosted providers such as Local Ollama read no environment variable at all: their base URL and credential are configured in the portal and stored encrypted, so there is nothing to export for them.

Verify#

Build and start Sugar, then request /api/health. After owner and provider setup it should return HTTP 200 with ready: true. Confirm routes.source reports build and routes.missing is empty.