diff --git a/.env.example b/.env.example
index d465ad2f..a261302d 100644
--- a/.env.example
+++ b/.env.example
@@ -12,6 +12,9 @@ POSTGRES_PASSWORD=postgres
 POSTGRES_PORT=5432
 
 # --- backend settings (see backend/.env.example for full list) ---
+# REQUIRED: Public URL the backend should advertise in generated instructions/webhook flows.
+# Update this when the backend is served behind a reverse proxy, custom host, or non-default port.
+BASE_URL=http://localhost:8000
 # For remote access, set this to your UI origin (e.g. http://<server-ip>:3000 or https://mc.example.com).
 CORS_ORIGINS=http://localhost:3000
 DB_AUTO_MIGRATE=true
diff --git a/README.md b/README.md
index b08e041e..9c2b66be 100644
--- a/README.md
+++ b/README.md
@@ -91,6 +91,7 @@ cp .env.example .env
 Before startup:
 
 - Set `LOCAL_AUTH_TOKEN` to a non-placeholder value (minimum 50 characters) when `AUTH_MODE=local`.
+- Ensure `BASE_URL` matches the public backend origin if you are not using `http://localhost:8000`.
 - `NEXT_PUBLIC_API_URL=auto` (default) resolves to `http(s)://<current-host>:8000`.
   - Set an explicit URL when your API is behind a reverse proxy or non-default port.
 
diff --git a/compose.yml b/compose.yml
index 16c9a505..b22ca203 100644
--- a/compose.yml
+++ b/compose.yml
@@ -34,7 +34,8 @@ services:
       context: .
       dockerfile: backend/Dockerfile
     env_file:
-      - ./backend/.env
+      - path: ./backend/.env
+        required: false
     environment:
       # Override localhost defaults for container networking
       DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@db:5432/${POSTGRES_DB:-mission_control}
@@ -42,6 +43,7 @@ services:
       DB_AUTO_MIGRATE: ${DB_AUTO_MIGRATE:-true}
       AUTH_MODE: ${AUTH_MODE}
       LOCAL_AUTH_TOKEN: ${LOCAL_AUTH_TOKEN}
+      BASE_URL: ${BASE_URL:-http://localhost:8000}
       RQ_REDIS_URL: redis://redis:6379/0
     depends_on:
       db:
@@ -94,7 +96,8 @@ services:
       dockerfile: backend/Dockerfile
     command: ["python", "scripts/rq-docker", "worker"]
     env_file:
-      - ./backend/.env
+      - path: ./backend/.env
+        required: false
     depends_on:
       redis:
         condition: service_healthy
@@ -104,6 +107,7 @@ services:
       DATABASE_URL: postgresql+psycopg://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@db:5432/${POSTGRES_DB:-mission_control}
       AUTH_MODE: ${AUTH_MODE}
       LOCAL_AUTH_TOKEN: ${LOCAL_AUTH_TOKEN}
+      BASE_URL: ${BASE_URL:-http://localhost:8000}
       RQ_REDIS_URL: redis://redis:6379/0
       RQ_QUEUE_NAME: ${RQ_QUEUE_NAME:-default}
       RQ_DISPATCH_THROTTLE_SECONDS: ${RQ_DISPATCH_THROTTLE_SECONDS:-2.0}
diff --git a/docs/deployment/README.md b/docs/deployment/README.md
index d6e1f372..7f4a0d2d 100644
--- a/docs/deployment/README.md
+++ b/docs/deployment/README.md
@@ -24,6 +24,7 @@ Edit `.env`:
 
 - `AUTH_MODE=local` (default)
 - **Set** `LOCAL_AUTH_TOKEN` to a non-placeholder value (≥ 50 chars)
+- Ensure `BASE_URL` matches the public backend origin if it is not `http://localhost:8000`
 - Ensure `NEXT_PUBLIC_API_URL` is reachable from the browser (not a Docker-internal hostname)
 
 Key variables (from `.env.example` / `compose.yml`):
diff --git a/install.sh b/install.sh
index 0f5cf913..e5b5c88b 100755
--- a/install.sh
+++ b/install.sh
@@ -856,6 +856,7 @@ main() {
   upsert_env_value "$REPO_ROOT/.env" "AUTH_MODE" "local"
   upsert_env_value "$REPO_ROOT/.env" "LOCAL_AUTH_TOKEN" "$local_auth_token"
   upsert_env_value "$REPO_ROOT/.env" "NEXT_PUBLIC_API_URL" "$next_public_api_url"
+  upsert_env_value "$REPO_ROOT/.env" "BASE_URL" "http://$public_host:$backend_port"
   upsert_env_value "$REPO_ROOT/.env" "CORS_ORIGINS" "http://$public_host:$frontend_port"
 
   if [[ "$deployment_mode" == "docker" ]]; then