Worker Management

Worker Management

Overview

White-Ops supports distributing AI agents across multiple PCs. A central master server orchestrates workers that run on separate machines.

How Workers Connect

1. Worker runs ./scripts/add-worker.sh <MASTER_IP>
2. Worker Docker container starts and calls POST /api/v1/workers/register
3. Master stores worker info (hostname, IP, CPU cores, RAM) with status pending
4. Admin approves the worker in System > Workers
5. Worker begins sending heartbeats every 30 seconds
6. Worker starts receiving and executing tasks

Registration Payload

{
  "name": "worker-office-02",
  "hostname": "DESKTOP-ABC123",
  "ip_address": "192.168.1.101",
  "max_agents": 5,
  "cpu_cores": 8,
  "memory_total_mb": 16384,
  "os_info": {"os": "Linux", "architecture": "x86_64"}
}

Heartbeat

Every 30 seconds, each worker sends:

{
  "cpu_usage_percent": 34.2,
  "memory_usage_percent": 62.8,
  "disk_usage_percent": 45.1
}

If no heartbeat for 2 minutes, the worker is marked offline.

Admin Panel

The Workers page shows:

• Worker name, IP address, status badge (online/pending/offline)
• CPU, RAM, Disk usage with progress bars
• Last heartbeat timestamp
• Approve/Reject buttons for pending workers

Worker Groups

Workers can be organized into groups (e.g., "Finance Department", "Research Lab") via the admin panel. Tasks can be routed to specific groups.

Failover

When a worker goes offline:

1. System detects via missed heartbeats (2-minute threshold)
2. In-progress tasks on that worker are set back to pending
3. Tasks are redistributed to other available workers
4. Admin receives notification

Adding a Worker

Option 1: Script

./scripts/add-worker.sh 192.168.1.100

Option 2: Manual Docker Compose

Create docker-compose.yml on the remote PC:

services:
  worker:
    image: ghcr.io/hesper-labs/whiteops-worker:latest
    environment:
      - MASTER_URL=http://192.168.1.100:8000
      - WORKER_NAME=worker-remote-01
      - REDIS_HOST=192.168.1.100
      - REDIS_PASSWORD=<from master .env>

Removing a Worker

1. Stop the worker: docker compose down on the remote PC
2. Remove from admin panel (optional)
3. Any assigned agents are unlinked

Resource Requirements per Worker

Resource	Minimum	Recommended
RAM	2 GB	4+ GB
CPU	2 cores	4+ cores
Disk	10 GB	20+ GB
Network	1 Mbps	10+ Mbps