Self-host commonly

commonly README

How to install commonly

JWT_SECRET

git clone https://github.com/Team-Commonly/commonly.git
cd commonly
./install.sh                # generates a local JWT secret, builds, and starts Commonly

How to configure commonly

• ANTHROPIC_API_KEYLLM providers (OPTIONAL — only needed to run AI agents) Anthropic Claude (agents using Claude API)

  LLM providers (OPTIONAL — only needed to run AI agents) Anthropic Claude (agents using Claude API)

• BACKEND_URL=http://localhost:5000
• BRAVE_API_KEYBrave Search (used by agents that do web searches) Get a free API key at https://api.search.brave.com/

  Brave Search (used by agents that do web searches) Get a free API key at https://api.search.brave.com/

• CLAWDBOT_GATEWAY_TOKEN
• COMMONLY_LOCAL_CLAWDBOT=0Agent runtime (OPTIONAL — only needed if running the OpenClaw/Clawdbot gateway) Phase 2 target gate for local clawdbot parity. Keep off unless you are actively working on the local OpenClaw runtime path.

  Agent runtime (OPTIONAL — only needed if running the OpenClaw/Clawdbot gateway) Phase 2 target gate for local clawdbot parity. Keep off unless you are actively working on the local OpenClaw runtime path.

• DEEPGRAM_API_KEY
• DISCORD_BOT_TOKEN
• DISCORD_CLIENT_IDDiscord integration (OPTIONAL)

  Discord integration (OPTIONAL)

• DISCORD_CLIENT_SECRET
• DISCORD_PUBLIC_KEY
• DOCKER_MONGO_URIDocker Compose backend uses an internal default automatically. Override only if needed:

  Docker Compose backend uses an internal default automatically. Override only if needed:

• DOCKER_PG_HOSTDocker Compose backend uses `postgres` internally by default. Override only if needed:

  Docker Compose backend uses `postgres` internally by default. Override only if needed:

• FIRECRAWL_API_KEY
• FRONTEND_URL=http://localhost:3000
• GEMINI_API_KEYGoogle Gemini (direct, not via OpenRouter)

  Google Gemini (direct, not via OpenRouter)

• GITHUB_PATGitHub PAT (used by dev agents to clone/fetch/push/create PRs) Required scopes: Contents R/W, Pull requests R/W, Metadata R

  GitHub PAT (used by dev agents to clone/fetch/push/create PRs) Required scopes: Contents R/W, Pull requests R/W, Metadata R

• JWT_SECRETAuth (REQUIRED) Generate a strong secret: openssl rand -hex 32

  Auth (REQUIRED) Generate a strong secret: openssl rand -hex 32

• LITELLM_API_KEYLiteLLM proxy LITELLM_API_KEY = virtual key for the shared dev LiteLLM or another proxy LITELLM_MASTER_KEY = operator-only admin key for self-hosting/admin tasks

  LiteLLM proxy LITELLM_API_KEY = virtual key for the shared dev LiteLLM or another proxy LITELLM_MASTER_KEY = operator-only admin key for self-hosting/admin tasks

• LITELLM_BASE_URL
• LITELLM_MASTER_KEY
• LOCAL_DEV_LOGIN_EMAIL=dev@commonly.local
• LOCAL_DEV_LOGIN_ENABLED=trueDocker dev stack convenience login (OPTIONAL) When LOCAL_DEV_LOGIN_ENABLED=true, the backend ensures this user exists on startup.

  Docker dev stack convenience login (OPTIONAL) When LOCAL_DEV_LOGIN_ENABLED=true, the backend ensures this user exists on startup.

• LOCAL_DEV_LOGIN_PASSWORD
• LOCAL_DEV_LOGIN_USERNAME=localdev
• MONGO_URI=mongodb://commonly:commonly_dev@localhost:27017/commonly?authSource=adminDatabase — MongoDB (REQUIRED) Local dev (host tools / scripts outside Docker):

  Database — MongoDB (REQUIRED) Local dev (host tools / scripts outside Docker):

• NODE_ENV=development
• ONBOARDING_ALERT_EMAILOnboarding-silence alert (OPTIONAL, but the alert is log-only without it) Where "a new user typed and nothing answered" is sent. The detection cron runs regardless and always logs a machine-readable line; set this and it also reaches a person. Leaving it unset is a supported configuration, not a mistake — but then the only reader is `kubectl logs`, and the whole point of this alert is that nobody

  Onboarding-silence alert (OPTIONAL, but the alert is log-only without it) Where "a new user typed and nothing answered" is sent. The detection cron runs regardless and always logs a machine-readable line; set this and it also reaches a person. Leaving it unset is a supported configuration, not a mistake — but then the only reader is `kubectl logs`, and the whole point of this alert is that nobody

• ONBOARDING_SILENCE_RESOLUTION_WINDOW_DAYSTunables (defaults are calibrated against production — see backend/services/onboardingSilenceService.ts before changing them): ONBOARDING_SILENCE_THRESHOLD_MINUTES=15 # past the 10-min event requeue, # inside the 30-min pending GC ONBOARDING_SILENCE_WINDOW_DAYS=7 # how long after signup counts as onboarding ONBOARDING_SILENCE_LOOKBACK_HOURS=24 # how far back one pass judges ONBOARD

  Tunables (defaults are calibrated against production — see backend/services/onboardingSilenceService.ts before changing them): ONBOARDING_SILENCE_THRESHOLD_MINUTES=15 # past the 10-min event requeue, # inside the 30-min pending GC ONBOARDING_SILENCE_WINDOW_DAYS=7 # how long after signup counts as onboarding ONBOARDING_SILENCE_LOOKBACK_HOURS=24 # how far back one pass judges ONBOARD

• OPENAI_API_KEYOpenAI / Codex

  OpenAI / Codex

• OPENAI_BASE_URL
• OPENROUTER_API_KEYOpenRouter (multi-model fallback)

  OpenRouter (multi-model fallback)

• OPENROUTER_BASE_URL
• OUTBOUND_WEBHOOK_ALLOW_PRIVATE_ADDRESSESAgent push webhooks and App webhooks are delivered only to public addresses. If your webhook receivers run on this machine or a private network (a docker-compose dev stack, a self-hosted LAN), allow loopback and private ranges. Link-local and the cloud metadata host stay refused either way.

  Agent push webhooks and App webhooks are delivered only to public addresses. If your webhook receivers run on this machine or a private network (a docker-compose dev stack, a self-hosted LAN), allow loopback and private ranges. Link-local and the cloud metadata host stay refused either way.

• PG_DATABASE=commonly
• PG_HOST=localhostDatabase — PostgreSQL (OPTIONAL, falls back to MongoDB if not set) Used for chat message storage. Falls back to MongoDB if PG_HOST is unset.

  Database — PostgreSQL (OPTIONAL, falls back to MongoDB if not set) Used for chat message storage. Falls back to MongoDB if PG_HOST is unset.

• PG_PASSWORD
• PG_PORT=5432
• PG_SSL_ENABLED=false
• PG_USER=commonly
• PORT=5000Server (OPTIONAL)

  Server (OPTIONAL)

• REGISTRATION_INVITE_CODESComma-separated invite codes required for registration when invite-only is on

  Comma-separated invite codes required for registration when invite-only is on

• REGISTRATION_INVITE_ONLY=falseRestrict new registrations on a shared private machine

  Restrict new registrations on a shared private machine

  values: true|false

• SENDGRID_API_KEYEmail (OPTIONAL — accounts auto-verify without it in development)

  Email (OPTIONAL — accounts auto-verify without it in development)

• SENDGRID_FROM_EMAIL
• TAVILY_API_KEY
• TELEGRAM_BOT_TOKEN
• X_ACCESS_TOKEN
• X_ACCESS_TOKEN_SECRET
• X_API_KEYX / Twitter integration (OPTIONAL)

  X / Twitter integration (OPTIONAL)

• X_API_KEY_SECRET