diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md
index c98cd6597..68da93210 100644
--- a/.claude/CLAUDE.md
+++ b/.claude/CLAUDE.md
@@ -14,6 +14,17 @@ This is an npm workspace monorepo:
 - **packages/server**: Backend server (Express + WebSocket API)
 - **packages/app**: Cross-platform app (Expo - iOS, Android, Web)
 
+## Environment overrides
+
+- `PASEO_HOME` – path for runtime state such as `agents.json`. Defaults to `~/.paseo`; set this to a unique directory (e.g., `~/.paseo-blue`) when running a secondary server instance.
+- `PASEO_PORT` – preferred voice server + MCP port. Overrides `PORT` and defaults to `6767`. Use distinct ports (e.g., `7777`) for blue/green testing.
+
+Example blue/green launch:
+
+```
+PASEO_HOME=~/.paseo-blue PASEO_PORT=7777 npm run dev
+```
+
 ## Running and checking logs
 
 We run the mobile app and server in the tmux session `voice-dev`:
diff --git a/packages/server/README.md b/packages/server/README.md
index a1973b5c9..a8c53464a 100644
--- a/packages/server/README.md
+++ b/packages/server/README.md
@@ -75,10 +75,18 @@ DEEPGRAM_API_KEY=...       # Streaming STT
 STT_MODEL=whisper-1        # Optional: override to gpt-4o-transcribe, etc.
 STT_CONFIDENCE_THRESHOLD=-3.0  # Optional: reject low-confidence clips
 STT_DEBUG_AUDIO_DIR=.stt-debug # Optional: persist raw dictation audio for debugging
+PASEO_HOME=~/.paseo        # Runtime state directory (agents.json, etc.)
+PASEO_PORT=6767            # Voice server + MCP port (falls back to 6767)
 PORT=3000                  # Server port
 NODE_ENV=development       # Environment
 ```
 
+`PASEO_HOME` defaults to `~/.paseo` and isolates runtime artifacts like `agents.json`. `PASEO_PORT` takes precedence over `PORT` and controls both the HTTP server and MCP endpoint. For blue/green testing you can run a parallel server without touching production state:
+
+```bash
+PASEO_HOME=~/.paseo-blue PASEO_PORT=7777 npm run dev
+```
+
 ## Tech Stack
 
 - **Server**: Express, TypeScript, ws (WebSocket)