docs(runtime): clarify persistence + add /data install defaults (#139)

Author: vignesh07

Dockerfile

@@ -47,11 +47,22 @@ RUN apt-get update \
   && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
     ca-certificates \
     tini \
+    python3 \
+    python3-venv \
   && rm -rf /var/lib/apt/lists/*
 
 # `openclaw update` expects pnpm. Provide it in the runtime image.
 RUN corepack enable && corepack prepare pnpm@10.23.0 --activate
 
+# Persist user-installed tools by default by targeting the Railway volume.
+# - npm global installs -> /data/npm
+# - pnpm global installs -> /data/pnpm (binaries) + /data/pnpm-store (store)
+ENV NPM_CONFIG_PREFIX=/data/npm
+ENV NPM_CONFIG_CACHE=/data/npm-cache
+ENV PNPM_HOME=/data/pnpm
+ENV PNPM_STORE_DIR=/data/pnpm-store
+ENV PATH="/data/npm/bin:/data/pnpm:${PATH}"
+
 WORKDIR /app
 
 # Wrapper deps

README.md

@@ -71,6 +71,39 @@ If you’re filing a bug, please include the output of:
 4) Copy the **Bot Token** and paste it into `/setup`
 5) Invite the bot to your server (OAuth2 URL Generator → scopes: `bot`, `applications.commands`; then choose permissions)
 
+## Persistence (Railway volume)
+
+Railway containers have an ephemeral filesystem. Only the mounted volume at `/data` persists across restarts/redeploys.
+
+What persists cleanly today:
+- **Custom skills / code:** anything under `OPENCLAW_WORKSPACE_DIR` (default: `/data/workspace`)
+- **Node global tools (npm/pnpm):** this template configures defaults so global installs land under `/data`:
+  - npm globals: `/data/npm` (binaries in `/data/npm/bin`)
+  - pnpm globals: `/data/pnpm` (binaries) + `/data/pnpm-store` (store)
+- **Python packages:** create a venv under `/data` (example below). The runtime image includes Python + venv support.
+
+What does *not* persist cleanly:
+- `apt-get install ...` (installs into `/usr/*`)
+- Homebrew installs (typically `/opt/homebrew` or similar)
+
+### Optional bootstrap hook
+
+If `/data/workspace/bootstrap.sh` exists, the wrapper will run it on startup (best-effort) before starting the gateway.
+Use this to initialize persistent install prefixes or create a venv.
+
+Example `bootstrap.sh`:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Example: create a persistent python venv
+python3 -m venv /data/venv || true
+
+# Example: ensure npm/pnpm dirs exist
+mkdir -p /data/npm /data/npm-cache /data/pnpm /data/pnpm-store
+```
+
 ## Troubleshooting
 
 ### “disconnected (1008): pairing required” / dashboard health offline

src/server.js

@@ -1369,6 +1369,27 @@ const server = app.listen(PORT, "0.0.0.0", async () => {
     console.warn("[wrapper] WARNING: SETUP_PASSWORD is not set; /setup will error.");
   }
 
+  // Optional operator hook to install/persist extra tools under /data.
+  // This is intentionally best-effort and should be used to set up persistent
+  // prefixes (npm/pnpm/python venv), not to mutate the base image.
+  const bootstrapPath = path.join(WORKSPACE_DIR, "bootstrap.sh");
+  if (fs.existsSync(bootstrapPath)) {
+    console.log(`[wrapper] running bootstrap: ${bootstrapPath}`);
+    try {
+      await runCmd("bash", [bootstrapPath], {
+        env: {
+          ...process.env,
+          OPENCLAW_STATE_DIR: STATE_DIR,
+          OPENCLAW_WORKSPACE_DIR: WORKSPACE_DIR,
+        },
+        timeoutMs: 10 * 60 * 1000,
+      });
+      console.log("[wrapper] bootstrap complete");
+    } catch (err) {
+      console.warn(`[wrapper] bootstrap failed (continuing): ${String(err)}`);
+    }
+  }
+
   // Auto-start the gateway if already configured so polling channels (Telegram/Discord/etc.)
   // work even if nobody visits the web UI.
   if (isConfigured()) {