# 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)