clawlama/TODO.AI.md

ClawLama — TODO.AI.md

Phase 1: Core Container (MVP)

1.1 Dockerfile

• Create multi-stage Dockerfile with debian:bookworm-slim base
• Stage 1 (builder): Install Node.js LTS via NodeSource node_lts.x apt repo with GPG key
• Stage 1 (builder): Download latest Ollama binary from GitHub releases (/releases/latest/download/ollama-linux-${TARGETARCH})
• Stage 1 (builder): Install OpenClaw via npm install -g openclaw@latest
• Stage 2 (runtime): Install Node.js LTS runtime (same repo method)
• Stage 2 (runtime): Install tini, procps, gettext-base, curl
• Stage 2 (runtime): Copy Ollama binary from builder
• Stage 2 (runtime): Copy OpenClaw global npm install from builder
• Stage 2 (runtime): Copy rootfs/ overlay
• Stage 2 (runtime): Create clawlama user/group, /data/ollama, /data/workspace dirs
• Stage 2 (runtime): chmod -R a-w /etc for hard /etc write protection
• Stage 2 (runtime): Set ENV defaults (all CLAWLAMA_* and OLLAMA_* vars)
• Stage 2 (runtime): VOLUME ["/data"], EXPOSE 18789
• Stage 2 (runtime): HEALTHCHECK pointing to /usr/local/bin/healthcheck.sh
• Stage 2 (runtime): ENTRYPOINT ["tini", "--"] + CMD ["/usr/local/bin/entrypoint.sh"]
• Verify no curl | sh or curl | bash anywhere in Dockerfile

1.2 OpenClaw Config Template

• Create rootfs/etc/clawlama/openclaw.template.json with envsubst placeholders
• Include models.providers.ollama block with baseUrl, apiKey: "ollama-local", api: "openai-completions"
• Include model entry with ${CLAWLAMA_MODEL}, ${CLAWLAMA_CONTEXT_WINDOW}, ${CLAWLAMA_MAX_TOKENS}
• Include agents.defaults with workspace: "/data/workspace", concurrency settings
• Include tools block: profile: "full", exec.security: "full", exec.ask: "off", elevated.enabled: false
• Include exec.applyPatch.workspaceOnly: true, fs.workspaceOnly: false

1.3 TOOLS.md

• Create rootfs/etc/clawlama/TOOLS.md with git restrictions (no commit, push, reset --hard)
• Include filesystem restriction note (no writes to /etc)

1.4 Entrypoint Script

• Create rootfs/usr/local/bin/entrypoint.sh (POSIX shell, #!/bin/sh)
• Detect architecture (uname -m → amd64/arm64)
• Detect CPU cores (nproc or /proc/cpuinfo) and available RAM
• Set OLLAMA_NUM_THREADS if not already set (physical cores)
• Detect SIMD capabilities (AVX/AVX2/AVX-512 on amd64, NEON on arm64) and log them
• GPU detection: probe nvidia-smi, log GPU model + VRAM if found, log CPU-only if not
• Print startup banner (arch, cores, RAM, GPU status, model, ports)
• Generate openclaw.json from template via envsubst → /data/workspace/.openclaw/openclaw.json
• Copy TOOLS.md to /data/workspace/TOOLS.md (only if not already present — don't overwrite user edits)
• Handle multi-model support: parse CLAWLAMA_MODELS comma-separated list, generate multiple model entries
• Handle Telegram integration: if CLAWLAMA_TELEGRAM_BOT_TOKEN set, inject channel config
• Start Ollama in background: ollama serve &, capture PID
• Wait for Ollama health: poll curl -sf http://localhost:11434/ with retry loop (max ~60s)
• Pull model if not cached: ollama pull ${CLAWLAMA_MODEL}
• Start OpenClaw gateway in foreground: openclaw gateway --port ${CLAWLAMA_OPENCLAW_PORT}
• Trap SIGTERM/SIGINT: forward to Ollama PID, wait for clean shutdown
• Monitor Ollama background process: if it exits unexpectedly, exit entrypoint (trigger Docker restart)

1.5 Health Check Script

• Create rootfs/usr/local/bin/healthcheck.sh
• Check Ollama: curl -sf http://localhost:11434/ or exit 1
• Check OpenClaw: curl -sf http://localhost:${CLAWLAMA_OPENCLAW_PORT}/ or exit 1
• Both pass → exit 0

---

Phase 2: Build & Compose

2.1 Build Script

• Create scripts/build.sh
• Set up docker buildx builder (create if not exists)
• Build + push multi-arch manifest: docker buildx build --platform linux/amd64,linux/arm64 --push -t docker.io/casjaysdevdocker/clawlama:latest .
• Add optional --load mode for local testing (single arch)
• Add build timestamp label

2.2 docker-compose.yml

• Create docker-compose.yml with service definition
• Volume mount: clawlama-data:/data
• Port mapping: 18789:18789
• Restart policy: unless-stopped
• Environment variables with defaults via .env file reference
• GPU variant: commented-out deploy.resources.reservations.devices for NVIDIA

2.3 Environment Template

• Create .env.example with all CLAWLAMA_* and OLLAMA_* vars with defaults and comments

---

Phase 3: Utility Scripts

3.1 Backup Script

• Create scripts/backup.sh
• Tar /data volume contents to timestamped archive
• Support custom output path argument
• Print backup size and location

3.2 Restore Script

• Create scripts/restore.sh
• Restore from tar archive to /data volume
• Validate archive before extracting
• Warn if container is running

---

Phase 4: Documentation

4.1 README.md

• Project description and purpose
• Quick start (CPU-only, GPU, custom model examples)
• Environment variable reference table
• Quantized model recommendations by RAM tier (8 GB / 16 GB / 32+ GB)
• GPU setup guide (NVIDIA Container Toolkit prerequisite)
• Multi-model configuration examples
• Telegram integration setup
• Volume and data persistence explanation
• Backup/restore usage
• Troubleshooting section (common issues, logs, health checks)
• Security notes (don't expose gateway publicly, prompt injection surface)
• Portainer/Dockge usage note
• Override config via bind mount

---

Phase 5: Validation

5.1 Success Criteria Verification

• docker pull succeeds on amd64
• docker pull succeeds on arm64
• docker run brings up both services with zero manual intervention
• Model auto-pulled on first run (CPU)
• OpenClaw responds within 120s of container start
• CLAWLAMA_MODEL change + restart pulls new model
• Data persists across docker stop && docker start
• Runs on x86_64 Linux VM
• Runs on Apple Silicon Mac (Docker Desktop)
• Runs on Raspberry Pi 5 (arm64)
• --gpus all on NVIDIA host → GPU detected in logs
• Without --gpus → CPU-only, no GPU errors in logs
• Image size < 500 MB compressed (excluding models)

5.2 Edge Cases

• First run with no pre-existing /data volume
• Container restart with existing model cache (should skip pull)
• Invalid CLAWLAMA_MODEL value → clear error message
• Ollama crash during runtime → container exits, restart policy recovers
• SIGTERM during model pull → clean shutdown
• Low memory host (4 GB) with 7B model → functional but slow