Worker Fleet Migration

Upgrade your on-premises worker fleet from the legacy shared-key passthrough model to the platform-owned execution-capacity model with project-scoped authentication, short-lived runtime JWTs, and structured sandbox orchestration.

Architecture overview

The current execution-capacity model replaces the legacy projects.sandbox_* columns and global WORKER_API_KEY with a structured hierarchy:

Org
└── Execution Provider Pool  (local | docker | kubernetes | e2b | daytona | modal | vercel)
    └── Worker Host           (durable capacity, heartbeats)
        └── Worker            (per-session or host-spawned process)

Project
└── Execution Route           (allowed / preferred / forbidden / fallback pools)

The diagram below shows how a worker authenticates and claims work under the new model:

sequenceDiagram
    participant W as Worker daemon
    participant P as Platform API
    participant R as Redis queue

    W->>P: POST /api/workers/register<br/>Authorization: Bearer rsp_live_...
    P-->>W: { workerId, runtimeJwt, expiresAt }

    loop Every 30 s
        W->>P: POST /api/workers/{id}/heartbeat<br/>Bearer runtimeJwt
    end

    loop Poll for work
        W->>P: GET /api/workers/{id}/poll<br/>Bearer runtimeJwt
        P->>R: ZPOPMIN (atomic claim)
        R-->>P: QueuedWork item
        P-->>W: { sessionId, resolvedProfile, ... }
        W->>P: POST /api/sessions/{id}/claim
    end

Legacy projects.sandbox_* columns remain readable and writable during the transition. The compatibility layer translates them into an org execution pool and project route automatically - no immediate action required for existing projects. New code should use /api/execution/* and /api/projects/:projectId/execution-route.

Migration phases

Phase summary

Upgrade your workers to runtime JWT auth

Legacy workers authenticate with a global WORKER_API_KEY. Platform-managed workers use short-lived runtime JWTs issued by the platform's /api/workers/register endpoint. The runtime JWT carries proj, org, sub, reg, and scope claims.

rensei project tokens create \
  --project <project-slug> \
  --type registration \
  --name "my-worker-host"

curl -X POST https://app.rensei.ai/api/workers/register \
  -H "Authorization: Bearer rsp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "version": "0.5.0",
    "capabilities": ["local"],
    "maxConcurrency": 4
  }'

{
  "workerId": "wkr_abc123",
  "runtimeJwt": "eyJ...",
  "expiresAt": "2026-06-02T02:00:00Z"
}

# Poll for work
GET /api/workers/{workerId}/poll
Authorization: Bearer eyJ...

# Heartbeat (every 30s)
POST /api/workers/{workerId}/heartbeat
Authorization: Bearer eyJ...

rensei fleet status --project <project-slug>

Configure execution provider pools

Provider pools are org-scoped. Configure them at Settings → Execution at the org level (not per-project). Each pool has a providerId, mode, credential binding, and capacity policy.

Supported providers

Project execution routes

Each project declares which org pools it uses via a route policy. Set this at Settings → Execution → Route or via the API:

PUT /api/projects/{projectId}/execution-route
Content-Type: application/json
Authorization: Bearer rsk_live_...

{
  "allowed": ["pool_local_01"],
  "preferred": ["pool_local_01"],
  "forbidden": [],
  "fallback": null
}

preferred pools are tried first; fallback is used if all preferred and allowed pools are at capacity. The platform resolves the final pool on each dispatch and stamps it onto the queued session.

Auth modes and pool pinning

Two auth modes are pinned to local-capacity pools and cannot use cloud sandboxes:

• host-session - requires executionProviderPools.providerId = 'local'
• local - same constraint

Attempting to dispatch with these auth modes against a cloud pool (e2b, modal, etc.) will fail at pre-flight validation. See Auth modes for the full capability matrix.

Legacy compatibility layer

During the migration window, the legacy projects.sandbox_* columns continue to work. The compatibility layer translates them:

Do not write new code against these columns. Use /api/execution/* and /api/projects/:projectId/execution-route for all new integrations.

Legacy worker key (transitional fallback)

Six session endpoints are still passthrough to the legacy @renseiai/agentfactory-nextjs package because they depend on the platform's Linear OAuth client, which was only brought in-platform during Phase 2a. These endpoints accept WORKER_API_KEY only - they will return 401 if you send a runtime JWT:

During the transition window: workers using runtime JWTs for all other endpoints must still send WORKER_API_KEY for these six. Both auth paths work simultaneously - this is intentional, not a gap.

Phase 2b will port all six endpoints to platform-native auth, after which the WORKER_API_KEY fallback will be removed from all handlers.

Ported vs. passthrough endpoint summary

Phases 1a-2a landed platform-owned versions of all worker and most session endpoints. Use this table to determine which auth token each endpoint accepts today:

Verify a clean migration

Run through this checklist after upgrading your fleet:

[ ] All workers appear in /admin/workers with a recent heartbeat
[ ] No worker is using a WORKER_API_KEY-only auth path (check worker logs)
[ ] At least one session has been successfully dispatched and completed under the new fleet
[ ] Project execution routes are configured at Settings → Execution for every active project
[ ] shape census for SDLC workflows shows v1: 0 (separate migration - see SDLC v1→v2)

Source references

Related

• Runner migration - opt in the Go agent runner per org
• Local sandbox provider - configuring daemon workers
• Capacity pools - pool substrate resolution and runtime_provides override
• Auth modes - host-session / local capacity constraints
• CLI: fleet - rensei fleet multi-machine management commands
• CLI: host daemon - install/uninstall/run/status/logs/doctor
• API: worker protocol registration - full register endpoint reference