# Worker Pool

**Last Updated:** 2025-01
**Confidence:** High (Planned - see address-the-gaps.md)

## Summary

Shared pool of claudebox workers (3-5 pods) that can build any project. Workers register, send heartbeats, and poll for tasks. Scales horizontally by adding workers, not projects.

**Key Facts:**
- Workers labeled `rdev.orchard9.ai/role=worker`
- StatefulSet: `claudebox-worker` with 3+ replicas
- Each worker has dedicated PVC for workspace
- Workers poll rdev-api for tasks every 5 seconds
- Health tracked via heartbeat endpoint

**File Pointers:**
- Port: `internal/port/worker_registry.go`
- Adapter: `internal/adapter/postgres/worker_registry.go`
- Handler: `internal/handlers/workers.go`
- K8s manifest: `deployments/k8s/base/claudebox-worker.yaml`

## Port Interface

```go
type WorkerRegistry interface {
    Register(ctx context.Context, worker WorkerInfo) error
    Heartbeat(ctx context.Context, workerID string) error
    Deregister(ctx context.Context, workerID string) error
    ListActive(ctx context.Context) ([]WorkerInfo, error)
}

type WorkerInfo struct {
    ID          string
    PodName     string
    Namespace   string
    Status      string // "idle", "busy", "unhealthy"
    LastSeen    time.Time
    CurrentTask string
}
```

## Worker Lifecycle

1. Pod starts → calls `POST /workers` to register
2. Main loop: heartbeat every 5s, poll for tasks
3. Task received → clone repo, run Claude, commit, report
4. Pod shutdown → `DELETE /workers/{id}` to deregister

## Environment Variables

```
WORKER_ID=$(hostname)
RDEV_API_URL=http://rdev-api.rdev.svc:8080
RDEV_API_KEY=<worker service key>
```

## Related Topics

- [Work Queue](./work-queue.md)
- [Build Orchestration](../features/build-orchestration.md)