160 lines
4.9 KiB
Markdown
160 lines
4.9 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
npm install
|
|
npm run dev
|
|
```
|
|
|
|
## Production Build
|
|
|
|
```bash
|
|
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](./docs/IMPLEMENTATION_STATUS.md)
|
|
- [Roadmap](./docs/ROADMAP.md)
|