# Engine configuration

Public server and client settings, defaults and secret handling.

Use environment variables for process configuration and the public API for workspace identities, permissions, conversations and provider connections. A process setting is not a replacement for current contact policy.

## Engine process

| Variable | Default / requirement | Purpose |
| --- | --- | --- |
| `BEEPGRID_DATABASE_URL` | Local dev PostgreSQL at localhost:5499 | PostgreSQL connection URL; use a protected runtime credential in production |
| `BEEPGRID_SCHEMA` | `beepgrid` | Isolated schema; migrate before serving without dev mode |
| `BEEPGRID_WORKSPACE` | `local` | Workspace name used in scope |
| `BEEPGRID_ENVIRONMENT` | `development` | Environment name used in scope |
| `BEEPGRID_COMPANY` | `Local workspace` | Workspace display name |
| `BEEPGRID_ADDR` | `127.0.0.1:4010` | Bind address |
| `BEEPGRID_PUBLIC_URL` | `http://localhost:4010` | Public HTTP(S) origin with no path; use HTTPS in production |
| `BEEPGRID_BOOTSTRAP_TOKEN` | Required outside dev mode | Secret owner bootstrap/current owner credential; keep out of workers |
| `BEEPGRID_SECRET_KEY` | Required outside dev mode | Exactly 64 hexadecimal characters; preserve with backups for protected provider data |
| `BEEPGRID_ATTACHMENTS_DIR` | `.local/attachments` | Durable file storage, shared consistently if running multiple processes |
| `BEEPGRID_PROFILE_ADDR` | Disabled | Optional literal loopback listener for private metrics/pprof; never expose publicly |
| `BEEPGRID_RECOVERY_TOKEN_FILE` | `.local/recovery-owner-token` | New protected owner credential path produced by restore reconciliation |

`serve --dev` is loopback-only, creates local credential/key files and enables local development provider connections. `serve --no-ui` keeps authenticated APIs/workers while disabling browser pages. Build with `-tags headless` to omit frontend source/assets entirely.

## Browser authentication

`BEEPGRID_OIDC_ISSUER`, `BEEPGRID_OIDC_CLIENT_ID` and secret `BEEPGRID_OIDC_CLIENT_SECRET` configure the OIDC provider. Use callback `/auth/oidc/callback`. Outside local development, the issuer uses HTTPS. Identity is issuer+subject, not merely matching an email address. New authenticated people do not automatically inherit organizational roles.

A same-origin browser session and a worker bearer credential are separate. The public auth-methods endpoint reports the deployment's configured choices. Managed Google/email onboarding may be supplied by the managed composition; it is not a requirement to self-host the OSS engine.

## Coordinator

All seven `BEEPGRID_AI_*` settings and legacy gateway settings are covered in the [provider reference](https://beepgrid.com/docs/self-hosting/coordinator-provider.md). Provider configuration does not automatically enable Coordinator. Enable it through the public assistance API when ready.

## Client process

`BEEPGRID_URL`, `BEEPGRID_TOKEN_FILE` and optional `BEEPGRID_TOKEN` select the engine and credential for CLI/examples. CLI chooses BEEPGRID_TOKEN when both are supplied. Worker examples deliberately validate protected files. Optional MCP `BEEPGRID_AGENT_ID`/`BEEPGRID_AGENT_NAME` trigger intentional bounded enrollment, not ordinary existing-worker authentication.

`BEEPGRID_TEST_DATABASE_URL`, test ports and example-specific fixture settings are verification inputs, not production feature configuration.

## Upgrade, backup and recovery

Use PostgreSQL 17, migrate with a separate schema-changing deployment credential and serve with a runtime role that has the required data privileges. Preserve database, attachment storage and encryption key together. Keep reverse-proxy timeouts above long-poll/SSE cycles.

After restoring a database, use `reconcile --restored` to hold effects and rotate credentials, then reconcile external operations whose results might be unknown. `reconcile --resume` resumes only after that review; it does not blindly replay unknown business actions. Retain backups before upgrades and never casually change the encryption key.

See [production operation and restore](https://beepgrid.com/docs/self-hosting/production.md) for complete procedure.