From a8f2ac54119825c99938c3d66172ba364a8e93ed Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 24 Jan 2026 08:00:07 +0000
Subject: [PATCH] docs(fly): add configuration guidance for bind mode, memory,
 and troubleshooting

---
 docs/platforms/fly.md | 83 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 78 insertions(+), 5 deletions(-)

diff --git a/docs/platforms/fly.md b/docs/platforms/fly.md
index a843549f2..ca15610f5 100644
--- a/docs/platforms/fly.md
+++ b/docs/platforms/fly.md
@@ -35,12 +35,58 @@ fly deploy
 
 ## Configuration
 
-The included `fly.toml` configures:
+The included `fly.toml` is a starting template. Key settings to customize:
 
-- **Region**: `lhr` (London) - change to your preferred [region](https://fly.io/docs/reference/regions/)
-- **VM**: `shared-cpu-1x` with 512MB RAM (sufficient for most use cases)
-- **Storage**: Persistent volume mounted at `/data`
-- **Auto-scaling**: Disabled to maintain persistent connections
+### VM Size
+
+The default `shared-cpu-1x` with 512MB may be too small for production. Recommended:
+
+```toml
+[[vm]]
+  size = "shared-cpu-2x"
+  memory = "2048mb"
+```
+
+### Bind Address
+
+**Important**: The gateway must bind to `0.0.0.0` for Fly's proxy to reach it:
+
+```toml
+[processes]
+  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"
+```
+
+When using `--bind lan`, you must also set a gateway token for security:
+
+```bash
+fly secrets set CLAWDBOT_GATEWAY_TOKEN=$(openssl rand -hex 32)
+```
+
+### State Directory
+
+Store persistent data on the volume:
+
+```toml
+[env]
+  CLAWDBOT_STATE_DIR = "/data"
+```
+
+### Full Example
+
+```toml
+[env]
+  NODE_ENV = "production"
+  CLAWDBOT_PREFER_PNPM = "1"
+  CLAWDBOT_STATE_DIR = "/data"
+  NODE_OPTIONS = "--max-old-space-size=1536"
+
+[processes]
+  app = "node dist/index.js gateway --allow-unconfigured --port 3000 --bind lan"
+
+[[vm]]
+  size = "shared-cpu-2x"
+  memory = "2048mb"
+```
 
 ## Secrets
 
@@ -67,6 +113,33 @@ fly logs
 fly ssh console
 ```
 
+## Troubleshooting
+
+### "App is not listening on expected address"
+
+If you see this warning, the gateway is binding to `127.0.0.1` instead of `0.0.0.0`. Add `--bind lan` to your process command (see Configuration above).
+
+### OOM / Memory Issues
+
+If the container gets killed or restarts frequently, increase memory:
+
+```toml
+[[vm]]
+  memory = "2048mb"
+```
+
+### Gateway Lock Issues
+
+If the gateway refuses to start with "already running" errors after a container restart, this is a stale PID lock. The lock file persists on the volume but the process doesn't survive restarts.
+
+**Fix**: Delete the lock file via SSH:
+```bash
+fly ssh console
+rm /data/.clawdbot/run/gateway.*.lock
+```
+
+Then restart the machine.
+
 ## Notes
 
 - Fly.io uses **x86** architecture (not ARM)