Harden install credentials and runtime quality

.env.example

@@ -5,7 +5,8 @@
 # DATABASE (Required)
 DB_PASSWORD=your_secure_database_password
 DB_HOST=localhost
-DB_PORT=5432
+DB_PORT=5433
+DB_HOST_PORT=5433
 DB_NAME=openbrain
 DB_USER=postgres
 DB_TIMEZONE=auto
@@ -14,7 +15,7 @@ DB_TIMEZONE=auto
 # Choose: openrouter, openai, ollama, custom
 EMBEDDER_PROVIDER=openrouter
 
-# OpenRouter (FREE - recommended)
+# OpenRouter (hosted; API key required)
 OPENROUTER_API_KEY=your_openrouter_api_key
 
 # OR OpenAI
@@ -27,15 +28,16 @@ OPENROUTER_API_KEY=your_openrouter_api_key
 # CUSTOM_API_URL=https://api.example.com/v1
 # CUSTOM_API_KEY=your_custom_api_key
 
-# PORTS
-MCP_PORT=8080
+# SERVICE PORTS
+# MCP uses stdio and does not listen on a TCP port.
 API_PORT=8000
 DASHBOARD_PORT=8501
 
 # API OPERATIONS
 # production enables authentication by default and refuses to start without a key.
 OPENBRAIN_ENV=development
-# OPENBRAIN_API_KEY=replace-with-a-long-random-secret
+# Generated automatically by: openbrain configure --project-root .
+# OPENBRAIN_API_KEY=managed-automatically
 # OPENBRAIN_AUTH_REQUIRED=true
 OPENBRAIN_MAX_REQUEST_BYTES=1048576
 OPENBRAIN_RATE_LIMIT_REQUESTS=120

.github/workflows/verify.yml

@@ -36,6 +36,16 @@ jobs:
           cache: pip
       - name: Install
         run: pip install -e '.[dev]'
+      - name: Validate generated environment and container configuration
+        env:
+          OPENBRAIN_CONFIG_DIR: ${{ runner.temp }}/openbrain-config
+        run: |
+          python -m src.cli configure --project-root .
+          docker compose config --quiet
+      - name: Compile shipped modules
+        run: python -m compileall -q src scripts tests
+      - name: Lint correctness rules
+        run: ruff check src scripts tests --select E9,F401,F541,F63,F7,F82,E722,F841,S110,ASYNC221,PLW1508,PLW1510,RUF012,B017,DTZ001,DTZ005,DTZ007
       - name: Apply migrations
         run: python scripts/migrate.py
       - name: Test

.gitignore

@@ -1,3 +1,8 @@
 __pycache__/
 *.pyc
 .venv/
+*.egg-info/
+build/
+dist/
+.pytest-*/
+.verification/

README.md

@@ -95,10 +95,10 @@ Integration guides:
 
 Open Brain requires Python 3.11+ and PostgreSQL with pgvector.
 
-For a reproducible v1.0.0 installation, review and run the release-pinned installer:
+Review and run the current installer:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/benclawbot/open-brain/v1.0.0/install.sh | sh
+curl -fsSL https://raw.githubusercontent.com/benclawbot/open-brain/master/install.sh | sh
 ```
 
 Verify:
@@ -108,13 +108,12 @@ openbrain --version
 openbrain --help
 ```
 
-The installer uses `pipx`, keeping Open Brain isolated from system Python packages.
+The installer uses `pipx`, keeping Open Brain isolated from system Python packages. It also generates a private OpenBrain API key once in `~/.config/openbrain/.env`; upgrades reuse that key.
 
 ### Hermes
 
 ```bash
 openbrain install-hermes
-export OPENBRAIN_URL=http://127.0.0.1:8000
 hermes memory setup
 ```
 
@@ -144,15 +143,16 @@ pip install -e '.[dev]'
 
 ```env
 DB_HOST=localhost
-DB_PORT=5432
+DB_PORT=5433
+DB_HOST_PORT=5433
 DB_NAME=openbrain
 DB_USER=postgres
-DB_PASSWORD=change-me
+DB_PASSWORD=replace-with-a-random-password
 DB_TIMEZONE=auto
 ```
 
 ```bash
-cp .env.example .env
+openbrain configure --project-root .
 docker compose up -d --build
 docker compose ps
 ```
@@ -168,6 +168,14 @@ The API container applies pending migrations during startup. Containers reach Po
 
 Already-applied migrations must never be edited. Add a new migration instead.
 
+## API keys
+
+`OPENBRAIN_API_KEY` protects the OpenBrain HTTP API and the memories stored behind it. It is OpenBrain's own shared secret—not a key issued by OpenAI, OpenRouter, or another model provider. The installer generates it automatically, stores it in the private per-user environment file, and the API, provider SDK, host adapters, and Hermes plugin load it transparently. `openbrain configure --project-root .` copies the same key into the project's private `.env` and generates its database password. Existing credentials are preserved on upgrades and repeated configuration runs.
+
+Production mode (`OPENBRAIN_ENV=production`) requires authentication and refuses to start without this key. You normally do not need to view or copy it. Explicit environment variables still take precedence when connecting to a remote OpenBrain deployment.
+
+Embedding-provider keys are separate. Set `OPENROUTER_API_KEY` or `OPENAI_API_KEY` only when using that hosted provider for semantic embeddings. Create those keys in the provider's account dashboard. A local Ollama server does not require an API key.
+
 ## CLI
 
 ```bash

config/settings.yaml

@@ -3,7 +3,6 @@ database:
   port: 5433
   name: openbrain
   user: postgres
-  password: openbrain
   timezone: auto
 
 embedder:
@@ -13,14 +12,14 @@ embedder:
   ollama_base_url: http://localhost:11434
 
 mcp:
-  host: 0.0.0.0
-  port: 8080
+  transport: stdio
 
 api:
-  host: 0.0.0.0
+  host: 127.0.0.1
   port: 8000
   cors_origins:
-    - "*"
+    - http://localhost:8501
+    - http://localhost:8000
 
 dashboard:
   port: 8501

docker-compose.yml

@@ -10,7 +10,7 @@ services:
     environment:
       DB_HOST: postgres
       DB_NAME: openbrain
-      DB_PASSWORD: openbrain
+      DB_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD must be set in .env}
       DB_PORT: 5432
       DB_USER: postgres
       OLLAMA_BASE_URL: ${OLLAMA_BASE_URL:-http://host.docker.internal:11434}
@@ -27,7 +27,7 @@ services:
     environment:
       DB_HOST: postgres
       DB_NAME: openbrain
-      DB_PASSWORD: openbrain
+      DB_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD must be set in .env}
       DB_PORT: 5432
       DB_USER: postgres
       STREAMLIT_PORT: 8501
@@ -39,7 +39,7 @@ services:
     container_name: openbrain-postgres
     environment:
       POSTGRES_DB: openbrain
-      POSTGRES_PASSWORD: openbrain
+      POSTGRES_PASSWORD: ${DB_PASSWORD:?DB_PASSWORD must be set in .env}
       POSTGRES_USER: postgres
     healthcheck:
       interval: 5s
@@ -50,7 +50,7 @@ services:
       timeout: 5s
     image: pgvector/pgvector:pg16
     ports:
-    - 5433:5432
+    - "127.0.0.1:${DB_HOST_PORT:-5433}:5432"
     volumes:
     - postgres_data:/var/lib/postgresql/data
 volumes:

docs/INSTALLATION.md

@@ -6,7 +6,7 @@
 curl -fsSL https://raw.githubusercontent.com/benclawbot/open-brain/master/install.sh | sh
 ```
 
-The installer verifies Python 3.11+, installs or upgrades Open Brain through `pipx`, detects Hermes, installs the bundled Hermes provider when Hermes is present, and runs `openbrain doctor`.
+The installer verifies Python 3.11+, installs or upgrades Open Brain through `pipx`, generates a private API key in `~/.config/openbrain/.env`, detects Hermes, installs the bundled Hermes provider when Hermes is present, and runs `openbrain doctor`. Repeated installs preserve the existing key.
 
 Set `OPENBRAIN_INSTALL_HERMES=0` to skip automatic Hermes wiring. Set `OPENBRAIN_REPO_URL` to install from a fork.
 
@@ -18,7 +18,7 @@ Automatic installation copies the packaged provider into `${HERMES_HOME:-~/.herm
 openbrain install-hermes --force
 ```
 
-Then set `OPENBRAIN_URL` and select `openbrain` from `hermes memory setup`.
+Then select `openbrain` from `hermes memory setup`. The local URL and generated API key load automatically.
 
 ## Other coding agents
 

install.sh

@@ -30,11 +30,18 @@ else
   "$PIPX_BIN" install "git+$REPO_URL"
 fi
 
+OPENBRAIN_BIN="$(command -v openbrain || true)"
+if [ -z "$OPENBRAIN_BIN" ]; then
+  OPENBRAIN_BIN="${PIPX_BIN_DIR:-$HOME/.local/bin}/openbrain"
+fi
+
+"$OPENBRAIN_BIN" configure
+
 if [ "$HERMES_MODE" = "1" ] || [ "$HERMES_MODE" = "true" ] || { [ "$HERMES_MODE" = "auto" ] && command -v hermes >/dev/null 2>&1; }; then
-  openbrain install-hermes --force
+  "$OPENBRAIN_BIN" install-hermes --force
 fi
 
-openbrain doctor
+"$OPENBRAIN_BIN" doctor
 cat <<'EOF'
 Open Brain installed.