{"id":47594867,"url":"https://github.com/mcleo-d/openclaw-pi-oss","last_synced_at":"2026-04-01T17:59:13.636Z","repository":{"id":343061540,"uuid":"1176118372","full_name":"mcleo-d/openclaw-pi-oss","owner":"mcleo-d","description":"Hardened Raspberry Pi 5 deployment of OpenClaw (self-hosted AI agent gateway) with Ollama inference, a minimal Python proxy, and a two-tier Claude Code agent team architecture.","archived":false,"fork":false,"pushed_at":"2026-03-22T10:14:19.000Z","size":166,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-22T11:30:29.278Z","etag":null,"topics":["claude-code","docker","llm","ollama","python","raspberry-pi","self-hosted-ai"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mcleo-d.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-08T16:37:11.000Z","updated_at":"2026-03-22T10:22:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mcleo-d/openclaw-pi-oss","commit_stats":null,"previous_names":["mcleo-d/openclaw-pi-oss"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/mcleo-d/openclaw-pi-oss","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcleo-d%2Fopenclaw-pi-oss","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcleo-d%2Fopenclaw-pi-oss/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcleo-d%2Fopenclaw-pi-oss/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcleo-d%2Fopenclaw-pi-oss/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mcleo-d","download_url":"https://codeload.github.com/mcleo-d/openclaw-pi-oss/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mcleo-d%2Fopenclaw-pi-oss/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290738,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","docker","llm","ollama","python","raspberry-pi","self-hosted-ai"],"created_at":"2026-04-01T17:59:12.712Z","updated_at":"2026-04-01T17:59:13.627Z","avatar_url":"https://github.com/mcleo-d.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenClaw on Raspberry Pi 5\n\n[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)\n[![CI](https://github.com/mcleo-d/openclaw-pi-oss/actions/workflows/ci.yml/badge.svg)](https://github.com/mcleo-d/openclaw-pi-oss/actions/workflows/ci.yml)\n\nA hardened, zero-trust reference deployment of [OpenClaw](https://openclaw.ai) — a\nself-hosted, open-source AI agent gateway — on a Raspberry Pi 5. This project provides\nsanitised configuration templates, security hardening documentation, and a custom Ollama\nproxy that manages context window size, suppresses thinking-mode overhead, truncates\noversized system prompts, and caps conversation history to keep inference fast on\nconstrained hardware.\n\n---\n\n## Who is this for?\n\n- Homelab and edge AI enthusiasts running self-hosted AI agents on low-cost hardware\n- Security-minded developers exploring AI agent threat models and defence in depth\n- Anyone deploying OpenClaw on ARM hardware who wants a hardened starting point\n\n---\n\n## Architecture\n\n```text\nYour Phone (Telegram / Signal)\n        │\n        ▼\n  [Messaging Platform]\n        │\n        ▼\n  OpenClaw Gateway          ← Docker container (hardened, localhost-only)\n  \u003chostname\u003e.local:18789        ← Raspberry Pi 5, 8GB RAM\n        │\n        ▼\n  openclaw-proxy            ← Systemd service\n  \u003cyour-proxy-port\u003e             caps num_ctx, injects think=false,\n                                truncates system prompt, caps history\n        │\n        ▼\n  Ollama (local LLM)        ← Native systemd service, loopback-only\n  127.0.0.1:11434               qwen3:1.7b-q4_K_M (primary)\n                                qwen2.5:3b-instruct-q4_K_M (fallback)\n```\n\nAn enhanced variant (`ollama-proxy`) is also available with two-layer prompt injection\ndetection for operators who need it. See [`docs/04-docker-openclaw.md`](docs/04-docker-openclaw.md).\n\n---\n\n## Hardware requirements\n\n| Component | Requirement |\n|---|---|\n| Hardware | Raspberry Pi 5 (8GB RAM recommended) |\n| OS | Raspberry Pi OS Lite 64-bit (Bookworm / Debian 12) |\n| Python | 3.9 or later (for the Ollama proxy) |\n| Storage | 16GB+ microSD or SSD |\n| Network | Ethernet recommended for stability |\n\nThe Pi 5 (8GB) is the tested configuration. Lower RAM may work but leaves less headroom\nfor the LLM KV cache and the OpenClaw container running concurrently.\n\n---\n\n## The Ollama proxy\n\nThe core custom component in this project is\n[`config/etc/openclaw-proxy/proxy.py`](config/etc/openclaw-proxy/proxy.py) — a lightweight\nPython HTTP proxy that sits between OpenClaw and Ollama.\n\nOn Pi 5 hardware, OpenClaw's default behaviour causes problems that cannot be fixed in\nOpenClaw's own configuration:\n\n| Problem | Proxy fix |\n|---|---|\n| OpenClaw sends `num_ctx=16384` → 1.8 GiB KV cache → inference hangs | Cap `num_ctx` at `PROXY_MAX_CTX` (4096) |\n| qwen3 thinking mode generates 200+ tokens per tool call (~50s/call) | Inject `think: false` on every request |\n| OpenClaw sends a ~4,600-token system prompt → ~248s prefill on Pi 5 | Truncate system message to `PROXY_MAX_SYSTEM_CHARS` |\n| Conversation history grows unboundedly → increasing prefill over time | Cap history to `PROXY_MAX_MESSAGES` (4 non-system messages) |\n\nAll tunable values are environment variables set in `openclaw-proxy.service`. An enhanced\nvariant (`ollama-proxy`) is also provided for operators who require two-layer prompt\ninjection detection; see [`docs/04-docker-openclaw.md`](docs/04-docker-openclaw.md) for both variants.\n\n---\n\n## Security model\n\nThis project applies a zero-trust, defence-in-depth model across seven layers:\n\n| Layer | Control |\n|---|---|\n| 1 | SSH hardening — key-only auth, no root login, session timeouts |\n| 2 | UFW firewall — deny all inbound except SSH; proxy port restricted to container bridge |\n| 3 | fail2ban — brute-force protection on SSH |\n| 4 | Kernel hardening — sysctl: ASLR, SYN cookies, ICMP redirect blocking, martian logging |\n| 5 | Disabled services — bluetooth, ModemManager, triggerhappy removed |\n| 6 | Docker daemon hardening — ICC disabled, no-new-privileges, resource limits |\n| 7 | Container hardening — cap_drop ALL, read-only rootfs, tmpfs, memory/CPU/PID limits |\n\nSee [`docs/03-security-hardening.md`](docs/03-security-hardening.md) for the full rationale\nbehind each control.\n\n---\n\n## Project status\n\n| Component | Status |\n|---|---|\n| Raspberry Pi 5 OS setup | Complete |\n| OS security hardening | Complete |\n| Docker Engine installation | Complete |\n| Ollama installed (native) | Complete — v0.17.0, bound to `127.0.0.1:11434` |\n| Models pulled | Complete — `qwen3:1.7b-q4_K_M` (primary), `qwen2.5:3b-instruct-q4_K_M` (fallback) |\n| Models benchmarked and selected | Complete — see [`docs/05-ollama-model-research.md`](docs/05-ollama-model-research.md) |\n| Ollama proxy deployed | Complete — context cap, think=false, system truncation, history capping |\n| OpenClaw running | Complete — gateway healthy, UI accessible |\n| Telegram integration | Complete — owner-only via pairing policy |\n| Signal integration | Under investigation — see [ROADMAP.md](ROADMAP.md) |\n| AppArmor profile | Planned — see [ROADMAP.md](ROADMAP.md) |\n\n---\n\n## Quick start\n\nSee [`config/README.md`](config/README.md) for the full deployment guide, including:\n\n- File placement and permissions\n- Template placeholder substitution\n- Boot configuration changes required for Docker memory limiting\n- UFW firewall rules\n- Service startup sequence\n\nFor day-to-day operation and troubleshooting, see\n[`docs/04-docker-openclaw.md`](docs/04-docker-openclaw.md).\n\n---\n\n## Documentation\n\n| Document | Description |\n|---|---|\n| [`config/README.md`](config/README.md) | Deployment guide — file map, permissions, step-by-step |\n| [`docs/01-hardware.md`](docs/01-hardware.md) | Hardware and connectivity reference |\n| [`docs/02-os-and-updates.md`](docs/02-os-and-updates.md) | OS setup and update process |\n| [`docs/03-security-hardening.md`](docs/03-security-hardening.md) | Security hardening — all seven layers |\n| [`docs/04-docker-openclaw.md`](docs/04-docker-openclaw.md) | Docker and OpenClaw setup, proxy config, troubleshooting |\n| [`docs/05-ollama-model-research.md`](docs/05-ollama-model-research.md) | Model benchmarks, selection rationale, Pi 5 performance data |\n| [`ROADMAP.md`](ROADMAP.md) | Planned improvements and future work |\n| [`CHANGELOG.md`](CHANGELOG.md) | Change history — breaking changes, new features, fixes |\n| [`GOVERNANCE.md`](GOVERNANCE.md) | Project decision-making and maintainer path |\n| [`SUPPORT.md`](SUPPORT.md) | How to get help and which channel to use |\n| [`NOTICE`](NOTICE) | Third-party attribution (Apache 2.0 requirement) |\n\n---\n\n## Contributing\n\nContributions are welcome — not just code. Hardware testing on different Pi variants, model\nbenchmarks, documentation improvements, and security feedback are all valuable.\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) to get started and [AGENTS.md](AGENTS.md) for\nguidance on AI-assisted contributions.\n\n---\n\n## Licence\n\nApache 2.0 — see [LICENSE](LICENSE).\n\n## Maintainer\n\n[James McLeod](https://github.com/mcleo-d)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcleo-d%2Fopenclaw-pi-oss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmcleo-d%2Fopenclaw-pi-oss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmcleo-d%2Fopenclaw-pi-oss/lists"}