ghostnet-openclaw/AGENT_INSTRUCTIONS.md

Stand: 01.06.2026

📋 Handover & Context Prompt for the Next AI Agent

Context: We are developing a fully local, containerized AI agent workspace called ghostnet-openclaw on CachyOS (Arch Linux). The stack runs entirely inside unprivileged, rootless Podman containers using a modular, multi-vendor GPU setup managed via podman-compose (the native Python parser). Current Architecture Stack:

1. LLM Engine (ollama): Running on the official ollama/ollama:rocm base image (built via custom Containerfile and an advanced entrypoint.sh boot-script that auto-polls and pulls models defined in MODEL_LIST). It features successful full AMD ROCm GPU Passthrough (Navi 31) with privileged: true and explicit host mapping for /dev/dri, /dev/kfd, and system render groups (44, 109).
2. Core Agent (openclaw-agent): Running OpenClaw v2026.5.28 in local gateway mode with password authentication. It utilizes userns_mode: "keep-id" to synchronize config file edits with the host alongside :Z,U volume flags to allow rootless Node.js writing to local host workspaces without permission degradation.
3. Network Tunnel Sidecar (openclaw-ollama-bridge): Running an offline-ready alpine/socat:latest image mapping directly into the network namespace of the agent (network_mode: "service:agent"). This tunnels local 127.0.0.1:11434 calls directly to ollama:11434 inside the closed bridge, bypassing a strict OpenClaw TUI bug where the embedded chat utility ignores global container environment variables.

Current Repository State:

• Fully dynamic variables outsourced to a root .env file (supporting SHM_SIZE, MODEL_LIST, OPENCLAW_PASSWORD, DNS servers, and absolute host system paths).
• Split monolithic configurations for various GPU vendors ready to go (compose.amd.yaml, compose.nvidia.yaml, compose.intel.yaml).
• Successfully tested and running gemma4:e4b at 100% GPU (VRAM) streaming tokens fluidly inside the native chat terminal without system freezes or context window pollution.
• Clean operational cycle verified: podman-compose -f compose.amd.yaml up -d --build runs without faults, and podman exec -it openclaw-agent openclaw chat opens the TUI flawlessly.

Next Task / Where to Continue: The core infrastructure is now solid, secure, and fully GPU-accelerated. The user wants to expand the project from here. Please analyze this setup and offer actionable next steps, such as:

1. Integrating external search indexers (like a local SearXNG service into the networks block).
2. Setting up explicit messenger interfaces or multi-account policies within the openclaw.json channels structure.
3. Building automated helper utilities (like a start.sh wrapper script to let users dynamically choose their vendor profile upon booting).

Stand: 03.06.2026

📋 Handover & Context Prompt for the Next AI Agent

Context: Wir entwickeln eine lokale, containerisierte AI-Workspace-Infrastruktur namens ghostnet-openclaw auf CachyOS. Der Stack nutzt unprivilegierte Podman-Container und eine Multi-Vendor GPU-Strategie.

Current Architecture Stack:

1. LLM Engine (ollama): Läuft auf ollama/ollama:rocm. Voller GPU-Passthrough für AMD Radeon RX 7900 XTX (Navi 31). Ein Entrypoint-Script automatisiert das Pulling der Modelle via MODEL_LIST.
2. Core Agent (openclaw-agent): OpenClaw v2026.5.28 im Local Gateway Mode. Nutzt keep-id und :Z,U für persistente Host-Workspaces ohne Permission-Issues.
3. Socat Bridge: Tunnelt 127.0.0.1:11434 (Agent) zu ollama:11434 (Engine), um den TUI-Loopback-Bug zu umgehen.
4. MCP Infrastructure (The Router): Ein dedizierter ghostnet-router (Python/FastAPI) dient als zentrales Tool-Gateway. Er integriert Skills via Model Context Protocol (MCP).
5. Search Skill: Ein tool-searchfetch Container (Bridge), der über den Router Suchanfragen an einen lokalen searxng Dienst delegiert.

Current Repository State:

• Networking: Alle Services kommunizieren über ein isoliertes Bridge-Netzwerk. DNS-Auflösung für externe Registeries (Ollama) muss im Podman-Netzwerk stabilisiert werden.
• Stability: Die maintain_connection-Logik im Router wurde erfolgreich implementiert; der CancelledError bei SSE-Handshakes ist behoben.
• Verification: End-to-End Test (Client -> Router -> Search-Bridge -> SearXNG) war erfolgreich. Tools wie searxng_web_search werden korrekt propagiert.

Next Tasks / Where to Continue:

1. OpenClaw Integration: Die openclaw.json muss so konfiguriert werden, dass der Agent den ghostnet-router (SSE-Endpunkt) als primäre Tool-Quelle nutzt.
2. Modell-Management: DNS-Problematik in der Ollama-Container-Registry beheben (Registry-Auflösung schlägt aktuell fehl).
3. Skill Expansion: Entwicklung weiterer MCP-Bridges (z.B. für lokales Filesystem-Management oder Datenbank-Abfragen), die einfach am Router "angepluggt" werden können.
4. UX-Automation: Ein ghostnet.sh Wrapper, der die Vendor-Erkennung automatisiert und den Stack konsistent hochfährt.