OpenClawDashboard/ARCHITECTURE.md

Tiger Command Center — Architecture

Last updated: 2026-06-10. Covers the gateway migration, real sub-agent spawning, the TASKS.md inbox loop, the Telegram transcript mirror, and the unified audit trail.

---

1. System Overview

Self-hosted AI agent orchestration on a Hetzner VPS (8 GB RAM, Helsinki; Tailscale 100.75.128.45). Three host services + one containerised AI runtime behind Traefik, with ALL model traffic routed through a self-hosted LiteLLM gateway — no third-party balance can silently kill the system.

Internet/Manohar
     |  HTTPS 443
     v
dokploy-traefik (v3.6.7)
     |
     +-- agent.manohargupta.com --> tiger-dashboard (Next.js, :3100)
     |                                    | /api/* proxies (token server-side)
     |                                    v
     |                             tiger-bridge (Express+tsx, :3456, localhost)
     |                                    |  docker exec / volume reads
     |                                    v
     |                             tiger-openclaw (OpenClaw v2026.3.12)
     |                                    |
     +-- llm.manohargupta.com ----> litellm-gateway <-- ALL model calls
     |                                    |-- MiniMax API (own key): minimax-3 (primary),
     |                                    |   minimax-2.7, minimax-2.7-fast
     |                                    +-- Anthropic API (own key): claude-haiku, claude-sonnet
     |
     +-- angel.manohargupta.com --> position-tracker (standalone repo/deploy)
     |
Telegram @Tiger_4321_bot <--> OpenClaw native channel (long-polling, owns the bot)

2. Model Routing (post-OpenRouter)

OpenRouter was removed 2026-06-10 after its credits ran dry and silently broke both Tiger and the bridge's classifier. Everything now goes through the self-hosted gateway:

• OpenClaw (openclaw.json): custom provider litellm (baseUrl: https://llm.manohargupta.com/v1, api: openai-completions). Primary litellm/minimax-3 (1M ctx), fallbacks litellm/minimax-2.7 → litellm/claude-haiku (cross-provider: survives a MiniMax outage).
• Bridge (lib/llm.ts): slugs starting anthropic/ go to Anthropic direct; everything else goes to the gateway. Env: LLM_GATEWAY_URL, LLM_GATEWAY_KEY, TIGER_ROUTER_MODEL (default minimax-3).
• Gateway config: /root/litellm/litellm_config.yaml (request_timeout: 300 to match the cron budget).

3. Sub-Agent Execution (the orchestration layer)

bridge/src/lib/agents.ts is the canonical specialist registry: cody (code), ethan (research), cathy (writing), elon (PM). Legacy ids coder/researcher/writer/pm are accepted as aliases.

A spawn (POST /tiger/spawn) runs an isolated OpenClaw session (--session-id spawn-<agent>-<id>) with the specialist persona prepended. Message transport is docker-cp of a temp file (escaping-proof). Runs are tracked in the executions table and serialized (MAX_CONCURRENT=1 — parallel turns push the 8GB host into swap and everything times out). Completion fires a Telegram notification via /tiger/notify.

Upgrade path: define real per-agent entries in openclaw.json agents.list (own IDENTITY.md + workspace each), then change the --agent flag in spawn.ts. Documented in lib/agents.ts; deferred until the RAM situation is resolved.

4. TASKS.md Inbox Loop

workspace/TASKS.md has a ## 📥 INBOX section. bridge/src/lib/inbox.ts checks every 30 min (09:00–20:00 IST): takes the first - [ ] line, classifies it (classifyAgent), spawns the specialist, rewrites the line to - [⏳ run-id → agent]. Manual trigger: POST /tiger/inbox/drain. Bridge-side scheduling means zero model tokens burned on empty checks and no bearer tokens embedded in cron prompts.

5. Telegram

• The bot is owned by OpenClaw's native channel (long-polling). The bridge's TelegramChannel, telegram-webhook.ts and chat-mirror.ts are legacy: Telegram forbids webhook + getUpdates on one token, so the webhook design could never receive a message.
• The dashboard mirror reads the native session transcript — routes/chat-telegram.ts resolves the telegram: session from sessions.json and serves the JSONL with cursor pagination and mtime caching. It filters to what Telegram actually saw: assistant messages carrying toolCall blocks (working narration) are skipped, thinking blocks ignored, injected metadata/system boilerplate stripped from user messages.

6. Audit Trail

GET /tiger/activity/audit merges, at read time, every durable action store: executions (spawns), tasks (lifecycle), outputs (artifacts), and OpenClaw's cron run JSONL. Cursor-paginated (before=<ISO>), type filters. The dashboard /activity page adds recent file-modification events on the first page. Read-time merging means history is complete retroactively and no action can happen without its audit row.

7. Crons (OpenClaw, tz Asia/Kolkata)

Job	Schedule	Timeout
Trade Baseline Reset	9:15 daily	60s
Trade P&L Monitor	every 2 min	60s
Hourly Trade Summary + News	hourly	90s
Hourly Task Check-in	0 9-21	300s
EOD Trade Summary	16:00 Mon–Fri	300s
Weekly Digest	Mon 9:00	300s

Timeout budget rationale: agent turns on this RAM-starved host can take minutes; 300s is the ceiling that made chronically-failing jobs pass.

8. Security Posture

• Bridge: Bearer auth on all routes; token in bridge/.env + dashboard/.env.local + embedded in cron payloads (rotate all four together — jobs.json has it twice). Rotated 2026-06-10 after the old token leaked via a hardcode in agents-activity.ts to the public GitHub mirror. NEVER hardcode tokens in source: this repo mirrors publicly.
• Git: Forgejo (origin, SSH port 2222, key id_ed25519_forgejo) + GitHub mirror. Push both.
• position-tracker binds 127.0.0.1:3457; public access via Traefik at angel.manohargupta.com.
• Known weak spots: litellm-db password, /opt/dashboard fossil with a stale token, dual Telegram pollers (bridge poller should be disabled).

9. Known Constraints

• RAM: ~13GB workload on 8GB physical; 6+GB swap in steady state. This is the root cause of historical cron timeouts and the reason spawn concurrency is 1. Decision pending: evict homelab services vs upgrade.
• OpenClaw v2026.3.12 predates MiniMax-M3, hence the explicit litellm/minimax-3 provider-prefixed model id.