Agent Dashboard

A multi-agent orchestration system with tool access control, Docker isolation, planner-driven workspace generation, mission Kanban board, specialist council insights, and real-time communication.

🎯 What This Does

Agent Dashboard is a production-ready multi-agent orchestration platform that allows you to:

Spawn specialized AI agents with isolated workspaces
Control tool access per agent (security + specialization)
Run agents in Docker containers (optional isolation)
Manage projects via Mission Control Kanban board
Get specialist insights from rotating council per project
Real-time communication via channels, DMs, and project war-rooms
Planner-driven setup generates agent workspaces automatically

🏗️ Architecture

Stack

Frontend: Next.js 15, React 19, Tailwind CSS
API: Express + Socket.IO for real-time updates
Runner: TypeScript agent runner with planner integration
Database: PostgreSQL + Prisma ORM
Monorepo: npm workspaces

Directory Structure

agent-dashboard/
├── apps/
│   ├── api/              # Express API server + WebSocket
│   ├── runner/           # Agent spawning + workspace planner
│   └── web/              # Next.js dashboard UI
├── packages/
│   └── db/               # Prisma schema, migrations, client
├── agent-workspaces/
│   ├── .template/        # Base template for agents
│   │   ├── agent-types.json    # 6 agent type definitions
│   │   └── SOUL.md, MISSION.md, etc.
│   └── <agent-id>/       # Generated agent workspaces (git-ignored)
├── tools.json            # Tool registry (24 tools, 6 presets)
├── migrate-tools-docker.sh   # Migration script
└── start.sh              # Startup script

⚡ Quick Start

1. Prerequisites

Node.js 20+
PostgreSQL (local or remote)
npm 10+

2. Installation

# Clone and install
git clone <your-repo>
cd agent-dashboard
npm install

# Create database
createdb agent_dashboard

# Run migrations
npm run db:generate
npm run db:migrate

3. Start

./start.sh

Access points:

Dashboard: http://localhost:3001
Mission Control: http://localhost:3001/mission-control
Communication Hub: http://localhost:3001/comms
API: http://localhost:4001

LAN URLs are printed on startup for mobile/tablet access.

🔧 Tool Access Control

Every agent has fine-grained control over which tools they can use.

Tool Presets

Preset	Tools	Use Case
minimal	read, web_search, web_fetch, session_status	Read-only, safest
standard	+ write, edit, sessions_send	Most agents
developer	+ exec, process	Full dev access
researcher	+ browser, image	Research tasks
orchestrator	sessions_*, agents_list	Multi-agent coordination
unrestricted	`*` (all tools)	⚠️ Admin agents only

How It Works

Tools are resolved in this priority:

Custom allowlist (explicit per-agent)
Preset (from tools.json)
Agent type defaults (from agent-types.json)

Examples

Spawn agent with minimal tools:

curl -X POST http://localhost:4001/api/agents/spawn \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Safe Bot",
    "type": "research-agent",
    "task": "Research AI safety papers",
    "toolPreset": "minimal"
  }'

Update agent to developer tools:

curl -X PATCH http://localhost:4001/api/agents/{agent-id}/tools \
  -H "Content-Type: application/json" \
  -d '{"preset": "developer"}'

Custom tool allowlist:

curl -X PATCH http://localhost:4001/api/agents/{agent-id}/tools \
  -H "Content-Type: application/json" \
  -d '{"allowedTools": ["read", "write", "web_search", "exec"]}'

Tool Registry

The tools.json file contains metadata for all 24 OpenClaw tools:

Tool metadata: name, category, description
Risk levels: low, medium, high, critical
Categories: filesystem, shell, network, automation, system, orchestration, AI, memory
Common usage: which agent types typically need each tool

Available tools:

Filesystem: read, write, edit
Shell: exec, process
Network: web_search, web_fetch, browser
Orchestration: sessions_spawn, sessions_send, sessions_list, sessions_history, agents_list
AI: image, tts
Memory: memory_search, memory_get
System: gateway, nodes, cron, message, canvas, session_status

🐳 Docker Container Spawning

Agents can optionally run inside Docker containers for isolation and security.

Benefits

Isolation: Separate filesystem and network
Security: Limit system access
Reproducibility: Consistent environment across runs
Resource control: CPU/memory limits

Docker Images

Image	Description	Use Case
`openclaw/agent-node:latest`	Standard Node.js env	Most agents
`openclaw/agent-devops:latest`	DevOps tools (Docker, kubectl)	DevOps agents
`openclaw/agent-python:latest`	Python 3.11+ with ML libs	ML/data agents
`openclaw/agent-minimal:latest`	Alpine minimal	Lightweight tasks

Examples

Enable Docker for existing agent:

curl -X PATCH http://localhost:4001/api/agents/{agent-id}/docker \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "image": "openclaw/agent-node:latest"
  }'

Spawn agent with Docker:

curl -X POST http://localhost:4001/api/agents/spawn \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Isolated Bot",
    "type": "devops-agent",
    "task": "Monitor system health",
    "useDocker": true,
    "dockerImage": "openclaw/agent-devops:latest",
    "dockerConfig": {
      "volumes": ["/var/run/docker.sock:/var/run/docker.sock:ro"],
      "environment": {
        "DOCKER_HOST": "unix:///var/run/docker.sock"
      }
    }
  }'

Docker Configuration

Docker config supports:

Custom image: Override default per agent
Volume mounts: Share directories (use :ro for read-only)
Environment variables: Pass config to container
Resource limits: CPU/memory constraints
Network mode: bridge, host, none, etc.

🤖 Agent Types

Six pre-configured agent types (in agent-workspaces/.template/agent-types.json):

1. Code Agent

Specialization: Software development, refactoring, debugging
Default tools: developer preset
Skills: github, skill-creator, codex-helper
Docker: Optional (Node.js image)

2. Content Agent

Specialization: Blog posts, social media, documentation
Default tools: standard preset
Skills: bird (Twitter CLI)
Docker: Optional (Node.js image)

3. Research Agent

Specialization: Information gathering, analysis
Default tools: researcher preset
Skills: search-reddit, blogwatcher
Docker: Optional (Node.js image)

4. Fitness Agent

Specialization: Workout tracking, nutrition
Default tools: developer preset
Skills: fitness-tracker (PostgreSQL access)
Docker: Optional (Node.js + DB env vars)

5. DevOps Agent

Specialization: System monitoring, deployment
Default tools: developer preset
Skills: None (system-level)
Docker: Enabled by default (DevOps image with Docker socket)

6. GSoC Coach Agent

Specialization: GSoC guidance, contribution strategy
Default tools: researcher preset
Skills: github, search-reddit
Docker: Optional (Node.js image)

📡 API Reference

Agents

Method	Endpoint	Description
GET	`/api/agents`	List all agents
GET	`/api/agents/:id`	Get single agent
POST	`/api/agents/spawn`	Spawn new agent (recommended)
POST	`/api/agents/:id/start`	Start agent session
POST	`/api/agents/:id/stop`	Stop agent session
POST	`/api/agents/:id/message`	Send message to agent
PATCH	`/api/agents/:id`	Update agent config
DELETE	`/api/agents/:id`	Delete agent

Tools (New)

Method	Endpoint	Description
GET	`/api/tools`	Get full tools registry
GET	`/api/tools/presets`	List available presets
GET	`/api/agents/:id/tools`	Get agent's tools
PATCH	`/api/agents/:id/tools`	Update agent tools

Docker (New)

Method	Endpoint	Description
GET	`/api/agents/:id/docker`	Get Docker config
PATCH	`/api/agents/:id/docker`	Update Docker config
GET	`/api/docker/images`	List available images

Projects / Mission Control

Method	Endpoint	Description
GET	`/api/projects`	List all projects
GET	`/api/projects/:id`	Get single project
POST	`/api/projects`	Create project
PATCH	`/api/projects/:id`	Update project
GET	`/api/projects/:id/insights`	Get specialist insights
POST	`/api/projects/:id/scan`	Trigger council scan
GET	`/api/projects/:id/chat`	Get war-room messages
POST	`/api/projects/:id/chat`	Post to war-room

Messages

Method	Endpoint	Description
GET	`/api/messages`	Get messages (with filters)
POST	`/api/messages`	Send message
GET	`/api/channels/:name`	Get channel messages

Friday Integration (Spawn Requests)

Method	Endpoint	Description
GET	`/api/spawn-requests`	Get pending spawns (for Friday polling)
POST	`/api/agents/:id/request-spawn`	Request spawn
POST	`/api/spawn-requests/:id/update`	Update spawn status
GET	`/api/agents/:id/spawn-status`	Get spawn status

🛠️ Development

Commands

# Start dev servers (API + Web)
npm run dev

# Build all workspaces
npm run build

# Database operations
npm run db:migrate          # Run migrations
npm run db:generate         # Generate Prisma client
npm run db:seed             # Seed database

# Individual workspace commands
npm run dev --workspace apps/api
npm run dev --workspace apps/web

Environment Variables

Create .env files in respective apps:

packages/db/.env:

DATABASE_URL="postgresql://user:password@localhost:5432/agent_dashboard"

apps/api/.env:

DATABASE_URL="postgresql://user:password@localhost:5432/agent_dashboard"
GATEWAY_URL="http://localhost:3721"  # Optional: OpenClaw gateway
FRONTEND_URL="http://localhost:3001"  # Optional: explicit CORS

apps/web/.env.local:

NEXT_PUBLIC_API_URL="http://localhost:4001"  # Optional: force API URL

🚀 Migration: Tools & Docker Features

These features were added Feb 2026 and require a database migration.

Run Migration

Automated:

./migrate-tools-docker.sh

Manual:

npm run db:generate
npx prisma migrate dev --name add_tools_and_docker
npm run dev

What Gets Added

Database columns (Agent model):

allowed_tools (JSON) — Tool allowlist
use_docker (boolean) — Docker spawn toggle
docker_image (string) — Docker image name
docker_config (JSON) — Docker configuration

Files:

tools.json — Tool registry with 24 tools

Agent types updated:

All 6 agent types now have toolPreset and docker config

Verify Migration

# Test endpoints
curl http://localhost:4001/api/tools | jq .
curl http://localhost:4001/api/tools/presets | jq .
curl http://localhost:4001/api/docker/images | jq .

# Spawn test agent
curl -X POST http://localhost:4001/api/agents/spawn \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Test Bot",
    "type": "research-agent",
    "task": "Test task",
    "toolPreset": "minimal"
  }' | jq .

🔒 Security Best Practices

Tool Access

Start minimal: Use minimal or standard presets by default
Add incrementally: Grant tools only when needed
Avoid wildcards: ["*"] grants full access — use sparingly
Review dangerous tools: Be cautious with exec, browser, message, gateway, cron

Docker Isolation

Use Docker for untrusted code: Especially agents executing external code
Limit volumes: Only mount necessary paths, prefer read-only (:ro)
No privileged mode: Unless absolutely required
Set resource limits: Prevent resource exhaustion
Use minimal images: Smaller attack surface

📊 Mission Control Features

Specialist Council

Every project gets a lead agent (auto-assigned or manual)
Rotating council of 3 specialist agents per project
Council scans every 15 minutes, generates insights
Insights posted to project war-room automatically

Domain Playbook

Six specialist domains:

Architecture — System design, boundaries, integration
Design — UI/UX, visual hierarchy, affordances
SEO & Content — Discoverability, metadata, search intent
Analytics — Decision-grade metrics, KPIs
Onboarding — First-run experience, activation
Reliability — Error handling, retries, fallbacks

Each domain contributes:

Angle: Specialist perspective
Proposal: Actionable recommendation
Question: Critical question for lead/owner

🔄 WebSocket Events

Real-time updates via Socket.IO:

agent:created — New agent spawned
agent:updated — Agent status/config changed
agent:deleted — Agent removed
agent:status — Agent status change
project:created — New project added
project:updated — Project modified
project:insight — New council insight
project:chat — War-room message
message:new — New message in any channel
message:sent — Message delivery confirmed
task:created — Task assigned
task:updated — Task status changed

📝 Notes

What's Git-Tracked

Source code (apps/, packages/)
Agent templates (agent-workspaces/.template/)
Tool registry (tools.json)
Scripts (start.sh, migrate-tools-docker.sh)
Documentation (README.md)

What's Git-Ignored

Generated workspaces (agent-workspaces/<agent-id>/)
Build outputs (.next/, dist/)
Dependencies (node_modules/)
Environment files (.env, .env.local)
Runtime files (logs/)

LAN Access

start.sh automatically detects and prints LAN URLs for access from other devices on your network:

✅ Agent Dashboard running:
   Local:  http://localhost:3001
   LAN:    http://192.168.1.100:3001

🎯 Common Workflows

Spawn a New Agent

curl -X POST http://localhost:4001/api/agents/spawn \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Code Assistant",
    "type": "code-agent",
    "task": "Review PRs and suggest improvements",
    "toolPreset": "developer",
    "useDocker": false
  }'

Create a Project

curl -X POST http://localhost:4001/api/projects \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Build Agent Dashboard",
    "brief": "Multi-agent orchestration system with tool control",
    "priority": 1,
    "tags": ["agents", "orchestration", "tools"]
  }'

Trigger Council Scan

curl -X POST http://localhost:4001/api/projects/{project-id}/scan

Update Agent Tools Mid-Flight

# Give agent more tools
curl -X PATCH http://localhost:4001/api/agents/{agent-id}/tools \
  -H "Content-Type: application/json" \
  -d '{"preset": "developer"}'

🧪 Testing

Manual Testing

# 1. Health check
curl http://localhost:4001/health

# 2. List agents
curl http://localhost:4001/api/agents | jq .

# 3. Get tools registry
curl http://localhost:4001/api/tools | jq .

# 4. Spawn test agent
curl -X POST http://localhost:4001/api/agents/spawn \
  -H "Content-Type: application/json" \
  -d '{"name":"Test","type":"research-agent","task":"Test","toolPreset":"minimal"}' | jq .

Database Inspection

# Open Prisma Studio
npx prisma studio

# Or use psql
psql $DATABASE_URL -c "SELECT id, name, status FROM agents;"

🤝 Contributing

Fork the repo
Create feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push: git push origin feature/amazing-feature
Open Pull Request

📄 License

[Add your license here]

🆘 Troubleshooting

Database Connection Failed

# Check PostgreSQL is running
pg_isready

# Verify DATABASE_URL
echo $DATABASE_URL

# Recreate database
dropdb agent_dashboard
createdb agent_dashboard
npm run db:migrate

Migration Errors

# Reset database (⚠️ deletes all data)
npx prisma migrate reset --force
npm run db:generate
npm run db:migrate

Agent Spawn Fails

Check agent type exists in agent-workspaces/.template/agent-types.json
Verify tools preset is valid (check tools.json)
Ensure workspace directory is writable

Port Already in Use

# Kill processes on ports 3001/4001
lsof -ti:3001 | xargs kill -9
lsof -ti:4001 | xargs kill -9

# Or use different ports
PORT=3002 npm run dev --workspace apps/web
PORT=4002 npm run dev --workspace apps/api

Built with ❤️ for autonomous agent orchestration

Name		Name	Last commit message	Last commit date
Latest commit History 4 Commits
agent-workspaces/.template		agent-workspaces/.template
apps		apps
packages/db		packages/db
.gitignore		.gitignore
COMMUNICATION-GUIDE.md		COMMUNICATION-GUIDE.md
FRIDAY-INTEGRATION.md		FRIDAY-INTEGRATION.md
README.md		README.md
STATUS.md		STATUS.md
SWARM-GUIDE.md		SWARM-GUIDE.md
migrate-tools-docker.sh		migrate-tools-docker.sh
package-lock.json		package-lock.json
package.json		package.json
spawn-gsoc-coach.sh		spawn-gsoc-coach.sh
start.sh		start.sh
tools.json		tools.json

Folders and files

Latest commit

History

Repository files navigation

Agent Dashboard

🎯 What This Does

🏗️ Architecture

Stack

Directory Structure

⚡ Quick Start

1. Prerequisites

2. Installation

3. Start

🔧 Tool Access Control

Tool Presets

How It Works

Examples

Tool Registry

🐳 Docker Container Spawning

Benefits

Docker Images

Examples

Docker Configuration

🤖 Agent Types

1. Code Agent

2. Content Agent

3. Research Agent

4. Fitness Agent

5. DevOps Agent

6. GSoC Coach Agent

📡 API Reference

Agents

Tools (New)

Docker (New)

Projects / Mission Control

Messages

Friday Integration (Spawn Requests)

🛠️ Development

Commands

Environment Variables

🚀 Migration: Tools & Docker Features

Run Migration

What Gets Added

Verify Migration

🔒 Security Best Practices

Tool Access

Docker Isolation

📊 Mission Control Features

Specialist Council

Domain Playbook

🔄 WebSocket Events

📝 Notes

What's Git-Tracked

What's Git-Ignored

LAN Access

🎯 Common Workflows

Spawn a New Agent

Create a Project

Trigger Council Scan

Update Agent Tools Mid-Flight

🧪 Testing

Manual Testing

Database Inspection

🤝 Contributing

📄 License

🆘 Troubleshooting

Database Connection Failed

Migration Errors

Agent Spawn Fails

Port Already in Use

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Packages