Skip to content

DocsRun

Security

BBM-Atlas starts locked to this machine with no keys. Before anyone else can reach it: keys, the directories it may index, the host names it answers, HTTPS and limits.

The defaults

Out of the box BBM-Atlas is for one person on one machine: it listens on 127.0.0.1 only, requires no key, and may index any directory it can read. That is safe while nobody else can reach it. Indexed code can be read back through search, so a server others can reach needs the settings below.

Before exposing the API

SettingWhy
BBM_ATLAS_ENVIRONMENT=production and BBM_ATLAS_API_KEYSEvery route and /mcp then needs a key, sent as X-API-Key or Authorization: Bearer. Production refuses to start without keys
BBM_ATLAS_ADMIN_API_KEYSKeeps changing feature flags away from ordinary keys
BBM_ATLAS_INDEX_ROOTSLimits indexing to the directories you name
BBM_ATLAS_MCP_ALLOWED_HOSTSThe host names clients use: /mcp refuses others, which defeats DNS-rebinding attacks from web pages
HTTPS, and BBM_ATLAS_FORWARDED_ALLOW_IPSKeys travel in headers, so never expose plain HTTP beyond a trusted network. Trust your reverse proxy, so logs and rate limits see real clients
BBM_ATLAS_RATE_LIMIT_ENABLEDA budget per caller (Production)
terminal
BBM_ATLAS_ENVIRONMENT=productionBBM_ATLAS_API_HOST=0.0.0.0BBM_ATLAS_API_KEYS_FILE=/run/secrets/api_keysBBM_ATLAS_ADMIN_API_KEYS_FILE=/run/secrets/admin_api_keysBBM_ATLAS_INDEX_ROOTS=/srv/reposBBM_ATLAS_MCP_ALLOWED_HOSTS=atlas.example.comBBM_ATLAS_FORWARDED_ALLOW_IPS=10.0.0.5BBM_ATLAS_RATE_LIMIT_ENABLED=true

Generate keys long and random, for example with openssl rand -hex 32, and keep them in files rather than the environment (Configuration).

What is open by design

  • /health, /health/ready and /metrics answer without a key, for load balancers and monitoring. Keep them on a network only those can reach, or block them at the proxy.
  • The console's page and scripts need no key: they hold no data, which they fetch from the API with the user's key. The page sends a strict Content-Security-Policy.
  • GET /api/v1/auth/methods lists the ways to sign in, so the console can offer them.

Keys in clients

  • The console keeps a key for the browser tab only, unless the user chooses to remember it.
  • bbm-atlas mcp install --api-key-env writes only the variable's name into .mcp.json, which is often committed, never the key.
  • The VS Code extension keeps keys in VS Code's secret storage.

Secrets in your code

BBM_ATLAS_REDACT_SECRETS_IN_CHUNKS=true replaces credential-shaped strings - private keys, recognisable API tokens, random values assigned to names like password or token - with [REDACTED] in what is indexed. It is off by default because it changes indexed content and can't catch everything: keep secrets out of repositories in the first place.

Your code stays yours

BBM-Atlas indexes and keeps your code where you run it. It sends no telemetry, and the Enterprise licence is checked offline. It connects out only where you set it up to: downloading an embedding model the first time one is used, traces to your own OpenTelemetry collector, your identity provider for single sign-on, and, with the compression proxy, your model provider.