Self-host the community edition

Build an artifact, configure secrets, and operate a single server with PostgreSQL.

Production prerequisites

Use a dedicated hostname, HTTPS termination, a backed-up PostgreSQL database, and a secret manager. Restrict network access during first-account bootstrap. Use the Helm guide for Kubernetes; the Compose file is a loopback-bound local development setup, not a hardened public deployment.

Build-time editions

bun install --frozen-lockfile
(cd frontend && bun install --frozen-lockfile)
EDITION=community bun scripts/build.ts

The build produces dist/server.js, dist/migrate.js, and dist/web/. Migrations are included by the bundled migration entrypoint; production does not invoke source files or rely on a source checkout.

# Supply production environment securely before these commands.
bun dist/migrate.js
bun dist/server.js

Run migrations successfully before exposing the new server version. Never run multiple independent migration processes intentionally.

Container build

docker build --build-arg EDITION=community -t browser-mcp:local-community .

Bun and dependencies are installed in a build stage, with root and frontend lockfiles installed separately. The runtime contains only the generated distribution, runs as the unprivileged bun user, listens on port 3000, and starts bun dist/server.js. To run migrations, override the command to bun dist/migrate.js using the same image and database settings.

Do not supply auth secrets as Docker build arguments. EDITION is not a runtime switch. Prefer versioned release tags and pin a verified digest for production; no latest tag is required by the chart.

Required environment

Variable	Meaning
DATABASE_URL	PostgreSQL connection string. Use a dedicated database, restricted credentials, and verified TLS for remote databases.
PUBLIC_URL	Canonical public origin, such as https://browser.example.com, with no trailing slash or path.
AUTH_SECRET	Independently generated, strong random authentication secret.
SETTINGS_ENCRYPTION_KEY	Independently generated encryption key for stored OIDC secrets and pending device credentials; retain securely with backups.

Generate the two keys independently with openssl rand -hex 32. Never use documented placeholders in production. See configuration for all build and runtime settings.

Reverse proxy

Forward HTTP and WebSocket upgrades to port 3000, preserving the public host and scheme. Permit /ws/browser, /b/*/mcp, /api/*, and dashboard assets. Do not cache authenticated API or MCP responses. Allow long-lived WebSockets; extension heartbeats occur every 20 seconds. Do not log Authorization, cookies, device proofs, or request/response bodies.

Expose only the proxy publicly. Restrict PostgreSQL to the app and administrative backup paths. Health checks are /healthz (process) and /readyz (database connectivity); readiness is not a substitute for migration success.

Bootstrap and OIDC

The first community registration becomes administrator atomically. Protect the installation until you have registered. Afterward, public password signup is disabled. Configure your organization’s provider in the OIDC admin settings to admit later users.

Backups and upgrades

Back up PostgreSQL and preserve SETTINGS_ENCRYPTION_KEY and auth secrets in a separate secret store. Test restores. A database backup without the encryption key cannot restore encrypted settings. Keep the previous image digest, but remember that rolling back an image does not undo schema changes.

The single-server design has planned downtime on every restart or upgrade. Reconnect browsers afterward and verify a harmless MCP command before reopening access. See operations.