Engine configuration
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
Section titled “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
Section titled “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
Section titled “Coordinator”All seven BEEPGRID_AI_* settings and legacy gateway settings are covered in the provider reference. Provider configuration does not automatically enable Coordinator. Enable it through the public assistance API when ready.
Client process
Section titled “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
Section titled “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 for complete procedure.