clawd-control

name	clawd-control
description	Monitor and manage your Clawdbot agent fleet from within an agent. Query health, sessions, usage, and trigger actions via the Clawd Control dashboard API.
version	1.0.0
author	temaki
tags	["dashboard","monitoring","fleet","management","multi-agent"]
requires	["web_fetch"]

Clawd Control — Agent Skill

Monitor and manage your Clawdbot agent fleet through the Clawd Control dashboard API. This skill lets agents check fleet health, inspect sessions, trigger heartbeats, and manage other agents — all programmatically.

Prerequisites

• Clawd Control server running and accessible (default: http://<host>:3100)
• Auth credentials: password from auth.json in the Clawd Control directory
• Full server: github.com/temaki-ai/clawd-control

Authentication

All API calls require a session cookie. Obtain one first:

curl -s -c cookies.txt http://<HOST>:3100/api/login \
  -H "Content-Type: application/json" \
  -d '{"password": "<PASSWORD>"}'

Or use the Authorization: Bearer <session_token> header.

For agents with web_fetch, you can use the session cookie approach or pass the token as a header.

API Reference

Fleet Overview

GET /api/snapshot Returns the full fleet state: all agents + host metrics in a single call.

Response shape:

{
  "ts": 1706000000000,
  "agents": {
    "gandalf": {
      "id": "gandalf",
      "name": "Gandalf",
      "emoji": "🧙",
      "online": true,
      "lastSeen": 1706000000000,
      "health": { "agents": [...], "uptime": 3600 },
      "sessions": { "sessions": [...] },
      "usage": { "totalCost": 12.50, "shared": true },
      "heartbeat": { "ts": 1706000000000 },
      "channels": { "channels": { "telegram": { "running": true } } },
      "cron": { "jobs": [...] }
    }
  },
  "host": {
    "hostname": "darth-maul",
    "loadAvg": [0.5, 0.3, 0.2],
    "memory": { "total": 16000000000, "used": 8000000000, "available": 8000000000 },
    "disk": { "total": 219000000000, "used": 24000000000 },
    "uptime": 86400
  }
}

Individual Agent State

GET /api/agents/:id Returns live state for a specific agent.

Agent Detail (workspace files + live state)

GET /api/agents/:id/detail Returns everything about an agent: config, workspace files (SOUL.md, MEMORY.md, TASKS.md, etc.), skills list, memory files, recent daily notes, and live state.

Agent Actions

POST /api/agents/:id/action

Body: { "action": "<action_name>" }

Available actions:

Action	Description
heartbeat-enable	Enable heartbeat polling
heartbeat-disable	Disable heartbeat polling
heartbeat-trigger	Trigger an immediate heartbeat
session-new	Archive current main session, start fresh
session-reset	Delete ALL sessions (nuclear — creates backup)

Create Agent

POST /api/create-agent

Body:

{
  "name": "Merry",
  "emoji": "🌿",
  "soul": "Loyal, practical, action-oriented.",
  "model": "anthropic/claude-sonnet-4-5",
  "telegramToken": "123456:ABC-DEF..."
}

Returns step-by-step creation log and result.

Host Metrics

GET /api/host Returns current host machine metrics (CPU load, RAM, disk, uptime).

SSE Live Stream

GET /api/stream Server-Sent Events stream. Emits:

• snapshot — full state on connect
• agent — individual agent updates (includes removed: true when agent is deleted)
• host — host metrics updates

Security Audit

GET /api/security-audit Runs security checks: secrets management, credential exposure, network/ports, system security, gateway config, account inventory.

Usage Patterns

Check if all agents are healthy

Fetch /api/snapshot, iterate agents, check each has online: true.
Flag any with online: false or stale lastSeen (> 5 min).

Monitor costs

Fetch /api/snapshot, sum usage.totalCost across agents.
Note: usage is shared per gateway, so avoid double-counting agents on the same gateway.

Trigger a heartbeat for a specific agent

POST /api/agents/gandalf/action with body {"action": "heartbeat-trigger"}

Reset a stuck agent

POST /api/agents/pippin/action with body {"action": "session-new"}
This archives the current session and starts fresh.

Notes

• The server binds to a specific IP by default (not 0.0.0.0) for security. Ensure your agent can reach it.
• Session tokens are in-memory and expire after sessionTtlHours (default: 24h).
• The SSE stream reconnects automatically on disconnect (client-side).
• Agent state is polled every 15s by default (configurable in agents.json).