docs: add Mode 3 — MCP containers on Mac host via Docker Compose

Documents how to route MCP servers running in Docker containers through
botlockbox on the Mac host for credential injection without any changes
to the MCP image. Covers proxy env vars, CA cert volume mount, and
per-runtime trust vars (Python, Node.js, Go, curl). Adds a reusable
contrib/docker-compose.example.yml template.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: trodemaster

README.md

@@ -281,6 +281,80 @@ In Docker, this is a two-stage entrypoint: start the proxy as root, then `exec s
 
 ---
 
+### Mode 3: MCP containers on a Mac host (Docker Compose)
+
+Run MCP servers in Docker containers while botlockbox provides credential injection from the Mac host. The containers carry **zero credentials** — all `Authorization` headers are injected by botlockbox before requests reach external APIs.
+
+This works with any MCP server that respects standard HTTP proxy environment variables. No changes to MCP server images are required.
+
+```mermaid
+flowchart TD
+    subgraph mac["Mac Host"]
+        SE["Secure Enclave\n(age-plugin-se)"]
+        BLB["botlockbox\nlisten: 0.0.0.0:8080\n(launchd agent)"]
+        CAPEM["~/.botlockbox/ca.pem"]
+        SE -->|"decrypts silently\nno Touch ID"| BLB
+        BLB -->|"--ca-cert"| CAPEM
+    end
+
+    subgraph docker["Docker Desktop (bridge network)"]
+        MCP1["MCP server A\nPython\nREQUESTS_CA_BUNDLE=\n/etc/botlockbox/ca.pem"]
+        MCP2["MCP server B\nNode.js\nNODE_EXTRA_CA_CERTS=\n/etc/botlockbox/ca.pem"]
+        MCP1 & MCP2 -->|"volume mount :ro"| VOL["/etc/botlockbox/ca.pem"]
+    end
+
+    CAPEM -->|"bind mount"| VOL
+
+    MCP1 -->|"HTTPS_PROXY=\nhost.docker.internal:8080"| BLB
+    MCP2 -->|"HTTPS_PROXY=\nhost.docker.internal:8080"| BLB
+    BLB -->|"Authorization injected\nfrom enclave"| API["External APIs\nOpenAI, GitHub…"]
+```
+
+**Prerequisites:**
+
+1. botlockbox running on the Mac host (Mode 1 — launchd + Secure Enclave).
+2. `listen: "0.0.0.0:8080"` in `botlockbox.yaml` — the default `127.0.0.1` is unreachable from Docker's bridge network.
+3. CA cert written to `~/.botlockbox/ca.pem` via `--ca-cert ~/.botlockbox/ca.pem` in the launchd plist.
+
+**Docker Compose config** (full template in `contrib/docker-compose.example.yml`):
+
+```yaml
+x-botlockbox-proxy: &botlockbox-proxy
+  HTTP_PROXY:  "http://host.docker.internal:8080"
+  HTTPS_PROXY: "http://host.docker.internal:8080"
+  http_proxy:  "http://host.docker.internal:8080"
+  https_proxy: "http://host.docker.internal:8080"
+  NO_PROXY: "localhost,127.0.0.1,*.local"
+
+x-botlockbox-ca: &botlockbox-ca
+  REQUESTS_CA_BUNDLE: /etc/botlockbox/ca.pem   # Python (requests, httpx, boto3, openai-sdk)
+  NODE_EXTRA_CA_CERTS: /etc/botlockbox/ca.pem  # Node.js
+  SSL_CERT_FILE: /etc/botlockbox/ca.pem        # Go stdlib, Ruby net/http
+  CURL_CA_BUNDLE: /etc/botlockbox/ca.pem       # curl / libcurl
+
+services:
+  mcp-server:
+    image: your-mcp-server-image:latest
+    environment:
+      <<: [*botlockbox-proxy, *botlockbox-ca]
+      # No API keys here — botlockbox injects them.
+    volumes:
+      - "${HOME}/.botlockbox/ca.pem:/etc/botlockbox/ca.pem:ro"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"  # needed on Linux Docker; harmless on Mac
+```
+
+**How it works:**
+
+1. Docker Desktop resolves `host.docker.internal` to the Mac host IP automatically.
+2. `HTTPS_PROXY` causes the container's HTTP library to tunnel all HTTPS through botlockbox.
+3. botlockbox MITMs the TLS session with its ephemeral CA, injects the credential from the Secure Enclave, and forwards the request.
+4. The CA cert is mounted read-only from the Mac host; each language runtime trusts it via its own env var — no code changes, no image rebuilds.
+
+**The MCP server's perspective:** it makes a normal HTTPS call to `api.openai.com`. The response arrives and credentials were never in its environment.
+
+---
+
 ## CLI reference
 
 ### `botlockbox seal`

contrib/docker-compose.example.yml

@@ -0,0 +1,73 @@
+# contrib/docker-compose.example.yml
+#
+# Example Docker Compose setup for running MCP servers in containers on a Mac
+# host while botlockbox provides credential injection from the host.
+#
+# Prerequisites:
+#   1. botlockbox is running on the Mac host via launchd (Mode 1 — Secure Enclave).
+#   2. botlockbox.yaml uses  listen: "0.0.0.0:8080"  (NOT 127.0.0.1).
+#      Without this, Docker containers cannot reach the proxy.
+#   3. The CA cert has been written to ~/.botlockbox/ca.pem via
+#      --ca-cert ~/.botlockbox/ca.pem in the launchd plist.
+#
+# Usage:
+#   docker compose -f contrib/docker-compose.example.yml up
+#
+# No credentials are placed in any container.
+# botlockbox on the Mac host injects Authorization / API headers
+# transparently before forwarding requests to external APIs.
+
+# ──────────────────────────────────────────────────────────────────────────────
+# Reusable YAML anchors — merge these into any service's environment block.
+# ──────────────────────────────────────────────────────────────────────────────
+
+x-botlockbox-proxy: &botlockbox-proxy
+  # Route all HTTP/HTTPS traffic through botlockbox on the Mac host.
+  # Docker Desktop resolves host.docker.internal to the host IP automatically.
+  HTTP_PROXY:  "http://host.docker.internal:8080"
+  HTTPS_PROXY: "http://host.docker.internal:8080"
+  http_proxy:  "http://host.docker.internal:8080"
+  https_proxy: "http://host.docker.internal:8080"
+  # Keep container-local and LAN traffic off the proxy.
+  NO_PROXY: "localhost,127.0.0.1,*.local"
+
+x-botlockbox-ca: &botlockbox-ca
+  # Trust the botlockbox ephemeral MITM CA for each language runtime.
+  # All point at the same mounted PEM — no code changes or image rebuilds needed.
+  REQUESTS_CA_BUNDLE: /etc/botlockbox/ca.pem   # Python: requests, httpx, boto3, openai-sdk
+  NODE_EXTRA_CA_CERTS: /etc/botlockbox/ca.pem  # Node.js: all https / fetch
+  SSL_CERT_FILE: /etc/botlockbox/ca.pem        # Go stdlib, Ruby net/http
+  CURL_CA_BUNDLE: /etc/botlockbox/ca.pem       # curl, libcurl (many CLIs)
+
+services:
+  # ──────────────────────────────────────────────────────────────────────────
+  # Replace this with your actual MCP server image.
+  # The only required additions are the environment and volumes blocks below.
+  # ──────────────────────────────────────────────────────────────────────────
+  mcp-server:
+    image: your-mcp-server-image:latest
+    environment:
+      <<: [*botlockbox-proxy, *botlockbox-ca]
+      # Your MCP server's own non-secret config goes here.
+      # API keys / tokens are NOT needed — botlockbox injects them.
+      # MCP_SERVER_PORT: "3000"
+    volumes:
+      # Mount the botlockbox CA cert from the Mac host (read-only).
+      - "${HOME}/.botlockbox/ca.pem:/etc/botlockbox/ca.pem:ro"
+    extra_hosts:
+      # Ensures host.docker.internal resolves on Linux Docker hosts too.
+      # Ignored (harmless) on Docker Desktop for Mac.
+      - "host.docker.internal:host-gateway"
+
+  # ──────────────────────────────────────────────────────────────────────────
+  # Second service example: a Python-based MCP server.
+  # Add as many services as needed; each gets the same proxy + CA config.
+  # ──────────────────────────────────────────────────────────────────────────
+  mcp-fetch:
+    image: ghcr.io/modelcontextprotocol/mcp-server-fetch:latest
+    environment:
+      <<: [*botlockbox-proxy, *botlockbox-ca]
+    volumes:
+      - "${HOME}/.botlockbox/ca.pem:/etc/botlockbox/ca.pem:ro"
+    extra_hosts:
+      - "host.docker.internal:host-gateway"