Concept
Workstations
A workstation is a registered machine running the Tanjiren desktop app. It is the physical compute layer — a real Windows, macOS, or Linux machine — where AI coding agents execute commands, run prompts, and produce results.
Real machines
Each workstation is a physical or virtual machine with its own OS, filesystem, and installed tools. Not a container or sandbox.
Cryptographic identity
Each workstation generates an ES256 key pair on first connection. Every request is signed with a proof-of-possession token.
Heartbeat presence
Workstations send a heartbeat every 30-60 seconds. If no heartbeat is received for 2 minutes, the workstation is considered offline.
Lifecycle
A workstation goes through four stages from registration to active use:
Registration
Created from the dashboard or API. At this point the workstation is just a database record with a name and ID. Status: offline.
Key binding
The desktop app exchanges a one-time pairing code for a sender-constrained token. An ES256 key pair is generated on the machine and the public key is stored server-side.
Heartbeats
The desktop app starts sending periodic heartbeats with status, OS info, capabilities, and active task count. The workstation transitions to online.
Relay connection
Optionally, the workstation opens a persistent WebSocket to the relay. This enables remote terminal access from the dashboard. Status becomes relay_online.
Status model
Workstation status is computed, not stored. It is derived from the last heartbeat timestamp and the relay connection state.
| Status | Condition | Can receive tasks? |
|---|---|---|
| No heartbeat in the last 2 minutes | No | |
| online | Recent heartbeat, relay not connected | Yes (non-interactive) |
| relay_online | Recent heartbeat + relay WebSocket active | Yes (full access) |
Heartbeat
The desktop app sends a heartbeat to POST /api/instances/:id/heartbeat every 30-60 seconds. The heartbeat carries:
The server responds with a list of up to 10 pending tasks assigned to this workstation. This piggyback mechanism delivers task assignments without requiring a separate polling channel.
Authentication
Workstations authenticate using Device Trust v2, a sender-constrained token protocol based on ES256 key pairs and DPoP (Demonstration of Proof-of-Possession).
On first connection, the desktop app generates a P-256 key pair and registers the public key with the server. Every subsequent request includes a signed proof that the machine possesses the private key. This prevents token theft — even if someone intercepts a token, they cannot use it without the private key.
Keys can be rotated through an admin-approved process. The old key is revoked and a new one is activated, maintaining the cryptographic chain of trust.
Tags
Workstations can be tagged with arbitrary labels for fleet management and task routing. Tags are used as targeting selectors when creating tasks — for example, targeting all workstations tagged staging or gpu.
Tags also surface as worker capabilities (prefixed with tag:), making them visible to task routing decisions.
Workstation vs Worker
A common source of confusion: workstation and worker refer to different layers of the same machine.
| Workstation | Worker | |
|---|---|---|
| What it is | A registered machine (database record) | A computed identity projected over that machine |
| Stored in DB? | Yes (instances table) | No (computed at query time) |
| Includes | Name, OS, keys, status, relay state | Health score, capacity, capabilities, readiness |
| Used for | Identity, connectivity, authentication | Task routing, capacity planning |
Think of it this way: the workstation is the machine; the worker is what that machine can do right now.
MCP tools and resources
| Tool | Scope | Description |
|---|---|---|
| list_workstations | mcp:read | List all workstations with status, OS, and tags |
| get_workstation | mcp:read | Full details for one workstation |
Resources
tanjiren://workstations/{id}Full workstation state including tags and metadata