Worker Registration

Corrected 2026-08-08. This page previously documented a "daemon-native" POST /v1/daemon/register path as the preferred registration route. That route was hard-deleted on 2026-06-10 - it was a redundant JWT-minting surface; the daemon has always registered via /api/workers/register in practice. POST /api/workers/register below is the one and only registration endpoint.

Register a donmai/rensei daemon or custom worker with the Rensei platform and obtain a runtime token that authorizes all subsequent worker-protocol calls.

Overview

Every worker must register before it can poll for sessions or send heartbeats. Registration validates a project-scoped registration token (or, for first-run onboarding, a user's own session/API-key credentials), creates or updates a worker record, and returns a workerId plus a runtimeToken. All subsequent calls use Authorization: Bearer <runtimeToken>.

`POST /api/workers/register`

The registration token is passed as the Authorization: Bearer header value.

Headers

Authorization: Bearer rsk_live_...
Content-Type: application/json

Request body

{
  "hostname": "build-host-01",
  "capacity": 4,
  "version": "1.0.0",
  "projects": ["my-project"]
}

Field	Type	Required	Description
`hostname`	`string`	Yes	Human-readable host identifier
`capacity` / `maxAgents`	`number`	Yes	Maximum concurrent sessions (must be `> 0`)
`version`	`string`	No	Worker version
`projects`	`string[]`	No	Legacy Linear project name filter - the platform overwrites this with the project's resolved tracker keys on the registration-token path. Omit to accept all projects.
`machineId`	`string`	No	Stable machine identifier for host deduplication
`hostInfo`	`object`	No	Optional machine telemetry (`ip`, `os`, `osVersion`, `arch`, `cpuCores`, `cpuModel`, `memTotalMb`, `daemonVersion`, `startedAt`). Absent fields leave the corresponding column null.
`daemonProjects`	`array`	No	Daemon-reported project allowlist (`{ id, repository }[]`), distinct from the legacy `projects` field.
`projectId`	`string`	Conditional	Required when authenticating with a user session/API key instead of a registration token (first-run onboarding, before any registration token has been minted) - identifies the project to bind to and enforces project membership. Ignored on the registration-token auth path.

Success response (201 Created)

{
  "workerId": "wkr_a1b2c3d4e5f6g7h8",
  "runtimeToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "runtimeTokenExpiresAt": "2026-06-03T00:00:00.000Z",
  "heartbeatInterval": 30000,
  "pollInterval": 5000
}

heartbeatInterval and pollInterval are in milliseconds.

Generating a registration token

Registration tokens are project-scoped API keys of type worker_registration. You create them in the Rensei dashboard under Settings → Projects → API Keys, or via the management API:

curl -s -X POST https://app.rensei.ai/api/org/<orgId>/keys \
  -H "Authorization: Bearer rsk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "build-host-01 registration key",
    "keyType": "worker_registration",
    "projectIds": ["<projectId>"]
  }'

Token format: rsk_live_<random> (new unified keys) or rsp_live_<random> (legacy). Both are accepted at registration.

The deprecated POST /api/org/api-keys endpoint emits a Deprecation: true header. Use POST /api/org/[orgId]/keys as the canonical path.

Runtime token lifecycle

After registration, store the runtimeToken securely in memory. All worker-protocol endpoints require this token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Token refresh

Refresh the runtime token before it expires using:

POST /api/workers/{workerId}/refresh-token
Authorization: Bearer <current runtimeToken>

The response returns a new runtimeToken and updated runtimeTokenExpiresAt. Implement refresh proactively (e.g. 5 minutes before expiry) rather than waiting for a 401.

Rehydration after Redis eviction

If the platform's Redis state is evicted (restart, TTL expiry, memory pressure), worker registration state can disappear even though the SQL record remains. When this happens, calling poll or heartbeat returns a 404 Worker not found. Rather than re-registering, the platform self-heals via rehydrateWorkerFromSql: on a 404 from poll, the platform attempts to reconstruct the Redis entry from the SQL row, and the worker's next poll succeeds without any re-registration round-trip.

Self-hosting operators do not need to handle this explicitly; the donmai daemon's built-in retry logic covers it. Custom workers should retry a 404 on poll once after a short delay before concluding the worker truly needs to re-register.

Full registration flow

Create a registration token in Settings → Projects → API Keys. Select key type Worker Registration and bind it to the project your agents run under.

Call POST /api/workers/register with the token. Store the returned workerId and runtimeToken.

Begin the work loop: poll every pollIntervalSeconds seconds and send heartbeats every heartbeatIntervalSeconds seconds. See Poll & Heartbeat.

Refresh the runtime JWT before expiry using POST /api/workers/{workerId}/refresh-token.

Deregister gracefully by calling DELETE /api/workers/{workerId}. The platform re-queues any sessions the worker held.

Auth Reference - runtime JWT claims, three auth modes, legacy fallback
Poll & Heartbeat - work polling, inbox messages, heartbeat contract
Session Lifecycle - status transitions, activity reporting
Worker Credentials - credential snapshot and rotate-stream SSE

On this page