From 2354d8b6e8d57cf221d27282eb02bcf277962d03 Mon Sep 17 00:00:00 2001 From: casjay Date: Tue, 17 Feb 2026 22:52:35 -0500 Subject: [PATCH] Create initial TODO.AI.md for ClawLama project Add detailed TODO list for ClawLama project phases including Docker setup, configuration, utility scripts, documentation, and validation criteria. --- TODO.AI.md | 142 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 142 insertions(+) create mode 100644 TODO.AI.md diff --git a/TODO.AI.md b/TODO.AI.md new file mode 100644 index 0000000..a3be422 --- /dev/null +++ b/TODO.AI.md @@ -0,0 +1,142 @@ +# 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