Concept
Workers
A worker is the operational identity projected over a workstation. While a workstation is a registered machine, the worker represents what that machine can do right now: its health, current load, capabilities, and readiness to accept tasks.
Computed, not stored
Workers are not database records. They are computed at query time from the workstation's state, runtime status, and task statistics.
Health score
Each worker has a 0-100 health score based on status, trust state, task load, and heartbeat recency. Routing prefers healthier workers.
Readiness check
Before a task is routed, each worker is checked for readiness. Reasons like offline, untrusted, or already busy prevent assignment.
Worker identity
Every worker has an ID in the format worker:{instanceId}. This ID is what appears in task assignments, lease ownership, and heartbeat data. There is exactly one worker per workstation.
Workers also have a display name, which defaults to the workstation name followed by "agent" (e.g., "dev-machine agent"). This can be overridden via a worker profile to give each agent a distinct identity.
Status
Worker status is derived from the underlying workstation status and the worker's current task load:
— Workstation is offline. Worker cannot receive tasks.
ready — Workstation is online and worker has no active tasks. Preferred for routing.
busy — Workstation is online but worker has one or more active tasks. Can still receive tasks if max concurrency allows.
Health score
Each worker is assigned a health score from 0 to 100. The routing engine uses this score to prefer healthier workers when multiple candidates are available.
| Factor | Penalty | Condition |
|---|---|---|
| Offline | -60 | Workstation status is offline |
| Busy | -15 | Worker has 1+ active tasks |
| Untrusted | -20 | No cryptographic identity (browser session only) |
| High load | -5 per task | More than 2 active tasks (capped at -20) |
| Stale presence | -15 | Last heartbeat over 10 minutes ago |
A fully healthy, idle, trusted worker with a recent heartbeat scores 100. The routing engine uses the strategy prefer_ready_least_loaded by default, which sorts candidates by readiness first, then by health score.
Capabilities
Workers advertise a set of capability flags that describe what they can do. These are derived automatically from the workstation state and augmented by heartbeat-reported capabilities.
Readiness
Before a task is routed to a worker, a readiness check evaluates whether the worker can accept it. If not ready, one or more reasons are attached:
worker_offlineWorkstation is offline or has no recent heartbeatrelay_unavailableTask requires relay but workstation is not relay-connecteduntrusted_identitySecurity policy requires trusted controller but worker is untrustedalready_busyWorker has reached max concurrent task limitstale_presenceLast heartbeat is over 10 minutes oldWorker profiles
Admins can customize a worker's behavior through its profile:
| Setting | Effect |
|---|---|
| displayNameOverride | Custom agent name instead of workstation name |
| enabled | Disable to exclude from task routing entirely |
| routingWeight | Relative priority for routing (default 100) |
| maxActiveTaskCount | Cap on concurrent tasks before worker is considered full |
MCP tools and resources
| Tool | Scope | Description |
|---|---|---|
| list_workers | mcp:read | List workers with health, status, capabilities, and readiness |
| get_worker | mcp:read | Full worker details including profile and active tasks |
Resources
tanjiren://workers/{id}Worker identity, health, capacity, and current taskstanjiren://workers/runtime-overviewFleet-wide worker summary and capacity