Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(security): loopback bind + generated secrets for local stacks (CHOO-1251, M1) (#122)

Louis Amaudruz53e2da9bf810
diff --git a/.env.example b/.env.example
index 0d0ae7a81..482cbbe10 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,14 @@
# Switch local development configuration
-# Copy to .env: cp .env.example .env
+#
+# Do NOT copy this file to .env by hand: the secret fields below ship BLANK on
+# purpose so no known default credential ever reaches a running stack. Generate
+# a .env with strong random secrets instead:
+#
+# just init-env
+#
+# That fills every blank secret (admin passwords, DB password, JWT key, Matrix
+# registration secret, agent token) with a freshly generated value and prints
+# the resulting gateway admin login.
# ── Standalone images (GHCR) ─────────────────────────────────────────────────
# Coordinates for the published switch-core / gateway / setup images that the
@@ -16,32 +25,33 @@ GATEWAY_HOST_PORT=3000
API_HOST_PORT=8000
MATTERMOST_HOST_PORT=8065
POSTGRES_HOST_PORT=5432
-# Host interface the published ports bind to. Defaults to all interfaces; set to
-# 127.0.0.1 to keep the stack reachable only from this machine.
-SWITCH_BIND_ADDR=0.0.0.0
+# Host interface the published ports bind to. Defaults to loopback so the stack
+# is reachable only from this machine; set to 0.0.0.0 to expose it on the
+# network — do that only behind a reverse proxy / firewall.
+SWITCH_BIND_ADDR=127.0.0.1
# ── Switch database (docker compose) ──────────────────────────────────────────
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
-DB_PASSWORD=switch-dev
+DB_PASSWORD=
DB_NAME=switch
# ── Matrix homeserver (Tuwunel) ──────────────────────────────────────────────
MATRIX_SERVER=http://localhost:8008
MATRIX_SERVER_NAME=localhost
MATRIX_ADMIN_USER=admin
-MATRIX_ADMIN_PASSWORD=admin
+MATRIX_ADMIN_PASSWORD=
# Must match the homeserver's registration_shared_secret (TUWUNEL_REGISTRATION_SHARED_SECRET).
-MATRIX_REGISTRATION_SHARED_SECRET=dev-secret
+MATRIX_REGISTRATION_SHARED_SECRET=
# ── Agent registration ───────────────────────────────────────────────────────
-AGENT_REGISTRATION_TOKEN=dev-placeholder-token
+AGENT_REGISTRATION_TOKEN=
# ── Gateway auth ─────────────────────────────────────────────────────────────
-JWT_SECRET_KEY=dev-jwt-secret-change-in-production
+JWT_SECRET_KEY=
-GATEWAY_ADMIN_PASSWORD=admin
+GATEWAY_ADMIN_PASSWORD=
# ── Frontend ─────────────────────────────────────────────────────────────────
FRONTEND_BASE_URL=http://localhost:5173
@@ -53,10 +63,10 @@ FRONTEND_BASE_URL=http://localhost:5173
# ── Mattermost (local dev) ───────────────────────────────────────────────────
MATTERMOST_ADMIN_USER=admin
-MATTERMOST_ADMIN_PASSWORD=admin1234
+MATTERMOST_ADMIN_PASSWORD=
MATTERMOST_TEAM_NAME=switch
MATTERMOST_USER=user
-MATTERMOST_USER_PASSWORD=user1234
+MATTERMOST_USER_PASSWORD=
# Teams has no local-dev env vars: a Teams workspace is connected per-bridge
# through the gateway (all Azure app credentials live in the bridge's stored
diff --git a/CLAUDE.md b/CLAUDE.md
index 3a70098ed..4a45f310c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -28,7 +28,7 @@ own `dash/CLAUDE.md` (→ `AGENTS.md`); read that before working in the app.
uv sync # install/update Python dependencies
# Local dev infrastructure (Docker Compose)
-cp .env.example .env # first-time setup
+just init-env # first-time setup — generate .env with random secrets
just up # start Switch locally
just down # stop Switch
diff --git a/README.md b/README.md
index cef62a98b..cd0104809 100644
--- a/README.md
+++ b/README.md
@@ -70,16 +70,22 @@ agent.
[just](https://github.com/casey/just) (`brew install just`).
```bash
-cp .env.example .env # defaults work as-is
+just init-env # generate .env with strong random secrets
just standalone-up # build & start the full stack
```
+`just init-env` writes a `.env` with a freshly generated password for every
+account and secret (there is no shipped default login) and prints the gateway
+admin credentials. The stack binds to `127.0.0.1` only — set `SWITCH_BIND_ADDR`
+in `.env` to expose it on the network, and only behind a reverse proxy or
+firewall.
+
Once it's up, open:
-| Service | URL | Default login |
+| Service | URL | Login |
|---|---|---|
-| Gateway (operator dashboard) | <http://localhost:3000> | `[email protected]` / `admin` |
-| Mattermost (chat with agents) | <http://localhost:8065> | `user` / `user1234` |
+| Gateway (operator dashboard) | <http://localhost:3000> | `[email protected]` / generated password (`GATEWAY_ADMIN_PASSWORD` in `.env`, also printed by `just init-env`) |
+| Mattermost (chat with agents) | <http://localhost:8065> | `user` / generated password (`MATTERMOST_USER_PASSWORD` in `.env`) |
**First run — connect your own agent.** Switch ships no bundled agents; the
point is to plug in yours. The quickest path is a bundled connector — the
@@ -111,7 +117,7 @@ wipe the data volumes.
(`brew install just`).
```bash
-cp .env.example .env # first-time setup — fill in the values
+just init-env # first-time setup — generate .env with random secrets
uv sync # install Python dependencies
just gateway-install # install gateway frontend deps (first time only)
just up # start the supporting stack (Docker Compose)
@@ -132,6 +138,7 @@ Run `just` with no arguments to list every recipe. The most-used ones:
| Command | What it does |
|---|---|
+| `just init-env` | Generate `.env` with freshly generated secrets (no default login) |
| `just up` / `just down` | Start / stop the local dev stack |
| `just reset` | Stop the stack and wipe volumes (incl. the Tuwunel database) |
| `just standalone-up` / `just standalone-down` | Start / stop the full standalone stack (no dev tooling) |
diff --git a/deploy/local/docker-compose.yml b/deploy/local/docker-compose.yml
index 7099d51b1..5a21f30bd 100644
--- a/deploy/local/docker-compose.yml
+++ b/deploy/local/docker-compose.yml
@@ -2,7 +2,7 @@ services:
postgres:
image: postgres:16-alpine
ports:
- - "5432:5432"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:5432:5432"
environment:
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
@@ -32,7 +32,7 @@ services:
tuwunel:
image: jevolk/tuwunel:v1.7.1
ports:
- - "8008:8008"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:8008:8008"
volumes:
- tuwuneldata:/var/lib/tuwunel
environment:
@@ -49,7 +49,7 @@ services:
image: mattermost/mattermost-team-edition:latest
platform: linux/amd64
ports:
- - "8065:8065"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:8065:8065"
volumes:
- mmdata:/mattermost/data
environment:
diff --git a/deploy/local/standalone-docker-compose.yml b/deploy/local/standalone-docker-compose.yml
index 8b1291271..4914e9cda 100644
--- a/deploy/local/standalone-docker-compose.yml
+++ b/deploy/local/standalone-docker-compose.yml
@@ -25,7 +25,7 @@ services:
postgres:
image: postgres:16-alpine
ports:
- - "${SWITCH_BIND_ADDR:-0.0.0.0}:${POSTGRES_HOST_PORT:-5432}:5432"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:${POSTGRES_HOST_PORT:-5432}:5432"
environment:
POSTGRES_USER: ${DB_USER}
POSTGRES_PASSWORD: ${DB_PASSWORD}
@@ -89,7 +89,7 @@ services:
platform: linux/amd64
profiles: ["collab"]
ports:
- - "${SWITCH_BIND_ADDR:-0.0.0.0}:${MATTERMOST_HOST_PORT:-8065}:8065"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:${MATTERMOST_HOST_PORT:-8065}:8065"
volumes:
- mmdata:/mattermost/data
environment:
@@ -124,7 +124,7 @@ services:
switch:
image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/switch-core:${SWITCH_VERSION:-latest}
ports:
- - "${SWITCH_BIND_ADDR:-0.0.0.0}:${API_HOST_PORT:-8000}:8000"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:${API_HOST_PORT:-8000}:8000"
environment:
DB_HOST: postgres
DB_PORT: "5432"
@@ -152,7 +152,7 @@ services:
image: ${SWITCH_REGISTRY:-ghcr.io}/${SWITCH_IMAGE_NAMESPACE:-sandbox-quantum}/gateway:${SWITCH_VERSION:-latest}
profiles: ["gateway"]
ports:
- - "${SWITCH_BIND_ADDR:-0.0.0.0}:${GATEWAY_HOST_PORT:-3000}:3000"
+ - "${SWITCH_BIND_ADDR:-127.0.0.1}:${GATEWAY_HOST_PORT:-3000}:3000"
depends_on:
- switch
diff --git a/justfile b/justfile
index f930e47ea..908f60854 100644
--- a/justfile
+++ b/justfile
@@ -12,6 +12,35 @@ import? 'internal/justfile'
default:
@just --list
+# ── Environment setup ──────────────────────────────────────────────────────────
+# Generate a .env from .env.example with freshly generated secrets. The example
+# ships every secret field BLANK on purpose so no known default credential (the
+# old admin/admin) can reach a running stack; this recipe fills them with random
+# values. Refuses to clobber an existing .env so it never rotates live secrets.
+init-env:
+ #!/usr/bin/env bash
+ set -euo pipefail
+ if [ -e .env ]; then
+ echo "✋ .env already exists — refusing to overwrite it." >&2
+ echo " Delete it first if you really want to regenerate every secret." >&2
+ exit 1
+ fi
+ if ! command -v openssl >/dev/null 2>&1; then
+ echo "openssl is required to generate secrets but was not found on PATH." >&2
+ exit 1
+ fi
+ cp .env.example .env
+ for key in DB_PASSWORD MATRIX_ADMIN_PASSWORD MATRIX_REGISTRATION_SHARED_SECRET \
+ AGENT_REGISTRATION_TOKEN JWT_SECRET_KEY GATEWAY_ADMIN_PASSWORD \
+ MATTERMOST_ADMIN_PASSWORD MATTERMOST_USER_PASSWORD; do
+ secret="$(openssl rand -hex 24)"
+ sed -i.bak "s|^${key}=.*|${key}=${secret}|" .env
+ done
+ rm -f .env.bak
+ echo "✅ Wrote .env with freshly generated secrets."
+ echo " Gateway admin login: $(grep '^GATEWAY_ADMIN_EMAIL=' .env | cut -d= -f2-) / $(grep '^GATEWAY_ADMIN_PASSWORD=' .env | cut -d= -f2-)"
+ echo " The stack binds to 127.0.0.1 only (set SWITCH_BIND_ADDR to expose it)."
+
# ── Dev infrastructure ─────────────────────────────────────────────────────────
# Tuwunel self-initializes its signing key + database in its data volume on
# first boot, so no pre-start key generation is needed.