openclaw-taskboard/README.md

Claw Fleet Console

openclaw-taskboard is now a Next.js + React + Tailwind + shadcn-style dashboard for the deployed Claw fleet.

It tracks and visualizes:

• OpenClaw swarm agents on ubuntu
• ZeroClaw host runtimes on grizzley and ice
• direct SSH host targets for pve, truenas, and panda
• shared task assignment and dispatch across all families
• wiki pages and architecture documentation rendered in the UI
• dispatch audit history, failure queues, heartbeat overlays, and task templates

Stack

• Next.js App Router
• React 19
• Tailwind CSS
• shadcn-style UI components under components/ui
• SQLite task storage

Key Pages

• /tasks - unified Kanban board
• /agents - configured OpenClaw, ZeroClaw, and direct host targets
• /openclaw - focused OpenClaw swarm view
• /zeroclaw - focused ZeroClaw host-runtime view
• /dispatch - dispatch audit log and failure queue
• /architecture - deployed architecture documentation with ASCII topology
• /wiki - markdown-backed runbooks and generated docs
• /usage - usage aggregates from the local tracking table

Control Plane Features

• typed fleet config and task template config
• dispatch lifecycle states and SQLite audit history
• OpenClaw swarm dispatch into ~/.clawdbot/active-tasks.json
• ZeroClaw webhook dispatch for grizzley and ice
• direct SSH dispatch for pve, truenas, and panda
• task callback API for remote completion/result sync
• OpenClaw registry sync API for swarm task state reconciliation
• heartbeat pickup API at /api/heartbeat/{agent} for queue inspection and self-dispatch
• failure queue and dispatch history views
• family-specific runtime views for OpenClaw and ZeroClaw plus unified direct-host visibility
• architecture documentation rendered directly from tracked config

Fleet Model

OpenClaw

• Host: ubuntu
• Service: openclaw.service
• Runtime: /srv/state/openclaw/current
• Config: ~/.openclaw/openclaw.json
• Channels:
  • Telegram DM allowlist
  • Homelab HQ forum topics
  • local gateway on :18789

ZeroClaw

• Primary runtime: grizzley
• Control-plane runtime: ice
• Runtime roots:
  • /srv/state/zeroclaw/current
  • /home/bear/.zeroclaw-admin
• Channels:
  • paired HTTP gateway access
  • Homelab-Ice forum topics
• remote gateway routing from ice

Direct SSH Targets

• Execution host: ubuntu taskboard container
• Transport: ssh using the mounted host key
• Configured targets:
  • pve via root@192.168.50.11
  • truenas via christopher@192.168.50.12
  • panda via bear@192.168.50.196
• Dispatch model:
  • select a direct target agent
  • dispatch a built-in safe action
  • capture stdout/stderr
  • write completion through the same callback pipeline as remote runtimes

Important Environment Variables

• DB_PATH
• WIKI_DIR
• AGENTS_DIR
• SWARM_TASKS_FILE
• SWARM_REPO_MAP_FILE
• SWARM_WORKTREES_DIR
• REPO_ACCESS_ROOTS
• OPENCLAW_CONFIG
• ZEROCLAW_GRIZZLEY_URL
• ZEROCLAW_GRIZZLEY_TOKEN
• ZEROCLAW_ICE_URL
• ZEROCLAW_ICE_TOKEN
• DIRECT_SSH_KEY_PATH
• DIRECT_SSH_TIMEOUT_MS

Heartbeat Pickup

Configured OpenClaw and ZeroClaw runtimes can hit:

curl -s http://127.0.0.1:8395/api/heartbeat/<agent>

The heartbeat endpoint will:

• sync OpenClaw swarm state before scheduling
• inspect the agent's assigned tasks
• skip tasks blocked by depends-on:<task-id> or dependency:<task-id> tags
• auto-dispatch the next runnable task when the agent does not already have an active unblocked task
• return queue state, blocked items, and any task that was dispatched during the heartbeat

This is the canonical path for agent-driven task pickup. Assignment alone does not start work; heartbeat pickup or an explicit dispatch does.

Development

npm install
npm run dev

Production Build

npm run build
npm start

Deployment Shape On Ubuntu

• app source checkout: /srv/apps/openclaw-taskboard/current
• taskboard data: /srv/state/openclaw-taskboard/data
• OpenClaw mounts:
  • /home/bear/.openclaw/agents
  • /home/bear/.openclaw/openclaw.json
  • /home/bear/.openclaw/workspace/wiki
• ZeroClaw architecture:
  • rendered from the tracked fleet model in this repo
  • optional runtime path overrides can be provided via ZEROCLAW_PRIMARY_DIR and ZEROCLAW_CONTROL_DIR
• Direct SSH:
  • taskboard container mounts /home/bear/.ssh as read-only
  • direct targets use /root/.ssh/id_ed25519 by default

Notes

• The UI intentionally treats OpenClaw, ZeroClaw, and direct host targets as separate families with different runtime and channel models.
• ice ZeroClaw remains tied to host-local secret/encryption state; the dashboard reads that runtime but does not attempt to rewrite it.
• Direct targets are intentionally limited to safe built-in actions from config/fleet.json, not arbitrary shell commands from the browser.

Status Docs

• Implementation status
• Roadmap