diff --git a/docker/entrypoint.sh b/docker/entrypoint.sh
index b6fc724b5..238af6a1b 100644
--- a/docker/entrypoint.sh
+++ b/docker/entrypoint.sh
@@ -12,4 +12,20 @@ if [ ! -d "${HOME}/.picoclaw/workspace" ] && [ ! -f "${HOME}/.picoclaw/config.js
     exit 0
 fi
 
+# Run bootstrap on every start
+BOOTSTRAP="${HOME}/.picoclaw/workspace/bootstrap.sh"
+ERROR_LOG="${HOME}/.picoclaw/workspace/bootstrap.error.log"
+
+if [ -f "$BOOTSTRAP" ]; then
+    echo "[bootstrap] Running bootstrap.sh..."
+    if sh "$BOOTSTRAP" 2>"$ERROR_LOG"; then
+        # Success — clear any previous error log
+        rm -f "$ERROR_LOG"
+    else
+        echo "[bootstrap] WARNING: bootstrap.sh failed. See $ERROR_LOG for details."
+        echo "[bootstrap] Some capabilities may be missing. The agent will attempt to fix bootstrap.sh."
+        # Do NOT exit — continue starting the gateway so the agent can be reached
+    fi
+fi
+
 exec picoclaw gateway "$@"
diff --git a/pkg/agent/context.go b/pkg/agent/context.go
index c2921294b..b1725a51b 100644
--- a/pkg/agent/context.go
+++ b/pkg/agent/context.go
@@ -465,6 +465,12 @@ func (cb *ContextBuilder) LoadBootstrapFiles() string {
 		}
 	}
 
+	// Surface bootstrap errors so the agent can diagnose and fix bootstrap.sh
+	errorLogPath := filepath.Join(cb.workspace, "bootstrap.error.log")
+	if data, err := os.ReadFile(errorLogPath); err == nil && len(data) > 0 {
+		fmt.Fprintf(&sb, "## BOOTSTRAP ERROR WARNING\n\nThe last container start ran `bootstrap.sh` and it FAILED. Some capabilities may be missing. You should read `bootstrap.sh`, identify the issue, fix it, and tell the user to restart the container.\n\nError output:\n```\n%s\n```\n\n", data)
+	}
+
 	return sb.String()
 }
 
diff --git a/workspace/bootstrap.sh b/workspace/bootstrap.sh
new file mode 100644
index 000000000..8856f77bf
--- /dev/null
+++ b/workspace/bootstrap.sh
@@ -0,0 +1,10 @@
+#!/bin/sh
+# bootstrap.sh — runs on every container start.
+# Edit this file to persist capabilities across restarts.
+# The agent will modify this file when you ask it to install tools.
+
+# Example: GitHub CLI (gh)
+if ! command -v gh >/dev/null 2>&1; then
+    echo "[bootstrap] Installing gh CLI..."
+    apk add --no-cache github-cli
+fi