From a7d66c52891465dc4d3ad2003749d99bab543f01 Mon Sep 17 00:00:00 2001
From: BigBodyCobain <43977454+BigBodyCobain@users.noreply.github.com>
Date: Tue, 30 Jun 2026 21:51:40 -0600
Subject: [PATCH] Document Docker OpenClaw HMAC setup in README and compose.

Covers host-side agent auth, data/openclaw.env persistence, verify_hmac.py, and backend vs frontend port guidance (#424).

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 README.md            | 11 +++++++++++
 backend/.env.example |  6 +++++-
 docker-compose.yml   |  3 +++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 8627f89..e453c75 100644
--- a/README.md
+++ b/README.md
@@ -460,6 +460,16 @@ v0.9.7 turns ShadowBroker from a dashboard a human watches into an intelligence
 
 **Connect an agent:** Open the AI Intel panel in the left sidebar, click **Connect Agent**, and copy the HMAC secret. From there, point any compatible agent at the channel — for OpenClaw, import `ShadowBrokerClient` from `openclaw-skills/shadowbroker/sb_query.py` (see `SKILL.md` for examples); for any other agent, use the same HMAC contract documented above (timestamp + nonce + body digest, tier-gated). Discovery: `GET /api/ai/tools` and `GET /api/ai/capabilities`. The channel is the protocol, not the agent.
 
+**Docker Compose + remote agents:** The dashboard UI talks to the backend over Docker's private bridge (trusted automatically). An OpenClaw agent running on the **host** (outside the container) hits `http://localhost:8000` from the Docker gateway IP — **HMAC is required** there. In AI Intel → **Connect Agent**, click **Bootstrap** then **Reveal**, copy `SHADOWBROKER_HMAC_SECRET` into your agent env, and restart the backend once so `data/openclaw.env` on the `backend_data` volume is loaded. Smoke-test with:
+
+```bash
+export SHADOWBROKER_URL=http://127.0.0.1:8000
+export SHADOWBROKER_HMAC_SECRET=<from Connect Agent modal>
+python openclaw-skills/shadowbroker/verify_hmac.py
+```
+
+Use the backend port (`:8000`), not the Next.js dashboard port (`:3000`). Hand-rolled signers must hash the exact POST bytes: `json.dumps(payload, separators=(",", ":"), sort_keys=True)`.
+
 ### ⏱️ Time Machine — Snapshot Playback (NEW in v0.9.7)
 
 A media-style transport for the entire telemetry feed. Treat the live map as a recording that can be scrubbed, paused, and replayed.
@@ -1127,6 +1137,7 @@ MESH_SAR_EARTHDATA_TOKEN=                     # NASA Earthdata token (paired wit
 MESH_SAR_COPERNICUS_USER=                     # Copernicus Data Space user (SAR Mode B — EGMS / EMS)
 MESH_SAR_COPERNICUS_TOKEN=                    # Copernicus token (paired with user above)
 OPENCLAW_ACCESS_TIER=restricted               # OpenClaw agent tier: "restricted" (read-only) or "full"
+# OPENCLAW_HMAC_SECRET=                         # Optional; UI Bootstrap persists to data/openclaw.env in Docker
 GFW_API_TOKEN=your_gfw_token                  # Global Fishing Watch — fishing_activity layer (Settings → Maritime)
 TELEGRAM_OSINT_ENABLED=true                   # Telegram OSINT layer (default on)
 TELEGRAM_OSINT_CHANNELS=osintdefender,...     # Comma-separated public channel slugs (see .env.example)
diff --git a/backend/.env.example b/backend/.env.example
index a82958c..7ec1449 100644
--- a/backend/.env.example
+++ b/backend/.env.example
@@ -385,7 +385,11 @@ AIS_API_KEY=              # https://aisstream.io/ — free tier WebSocket key
 
 # ── OpenClaw Agent ─────────────────────────────────────────────
 # HMAC shared secret for remote OpenClaw agent authentication.
-# Auto-generated via the Connect OpenClaw modal — do not set manually.
+# Prefer AI Intel → Connect Agent → Bootstrap → Reveal in the UI.
+# Docker: the secret is persisted to data/openclaw.env on the backend_data
+# volume (survives container restarts). Host-side agents must sign requests
+# to http://localhost:8000 — the dashboard :3000 proxy does not forward
+# X-SB-* HMAC headers. Verify with openclaw-skills/shadowbroker/verify_hmac.py
 # OPENCLAW_HMAC_SECRET=
 # Access tier: "restricted" (read-only) or "full" (read+write+inject)
 # OPENCLAW_ACCESS_TIER=restricted
diff --git a/docker-compose.yml b/docker-compose.yml
index 388dbcf..707a25d 100644
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -100,6 +100,9 @@ services:
       - GT_ANALYTICS_HIGH_RISK_THRESHOLD=${GT_ANALYTICS_HIGH_RISK_THRESHOLD:-0.6}
       - GT_ANALYTICS_BASE_PRIOR=${GT_ANALYTICS_BASE_PRIOR:-0.15}
       - GT_ANALYTICS_WATCHED_CHANNELS=${GT_ANALYTICS_WATCHED_CHANNELS:-}
+      # Optional override. Leave unset and use AI Intel → Connect Agent → Bootstrap
+      # instead — the UI persists OPENCLAW_HMAC_SECRET to data/openclaw.env on the
+      # backend_data volume so host-side agents can HMAC-auth after container restarts.
       - OPENCLAW_HMAC_SECRET=${OPENCLAW_HMAC_SECRET:-}
     volumes:
       - backend_data:/app/data