Scaling
Horizontal runtime workers — YOKE_WORKER_ID, instance ownership, and queue partitioning.
Multiple Yoke runtime workers can share one Postgres database. Each worker drains queues only for actor instances it owns — partitioning compute without partitioning the append stream.
Worker model
GLOBAL STREAM (shared)
│
async fan-out (all workers)
│
┌─────────────────┼─────────────────┐
▼ ▼ ▼
Worker A Worker B Worker C
instances 1,2 instances 3,4 instances 5,6
drain loops drain loops drain loops| Property | Behavior |
|---|---|
| Stream append | Shared — any worker or external client can append |
| Fan-out | All workers share fan-out index; enqueue is global |
| Queue drain | Partitioned — only owning worker dispatches process() |
Configuration
export YOKE_WORKER_ID=worker-us-east-1aDefault: {hostname}-{uuid} — unique per process.
Instance assignment
| Event | worker_id |
|---|---|
ctx.instances.create() on worker A | Set to A's YOKE_WORKER_ID |
Boot with worker_id IS NULL rows | Claimed by starting worker |
| Portal/HTTP create | Creating executor's worker id |
Worker registry
Workers register in runtime_workers and heartbeat every 15 seconds.
Stale workers (no heartbeat for 60s) are excluded from yoke_runtime_workers gauge. Instance ownership is not automatically migrated yet — orphan instances (worker_id pointing to dead worker) idle until manually reassigned or a worker claims NULL rows.
Scaling guidelines
| Concern | Guidance |
|---|---|
| CPU-bound actors | Add workers; create instances across workers |
| Single hot instance | Increase queue.concurrency, not workers |
| Stream throughput | Postgres write scaling; fan-out is async |
| Stateful actors | SQLite stays with instance on owning worker |
Multi-tenant vs horizontal
| Pattern | Scope |
|---|---|
| Horizontal workers | Multiple processes, same tenant, shared Postgres |
| Multi-tenant sandboxes | One executor per hot tenant, scheduler-managed |
They compose: each tenant executor can run multiple workers or a single worker, depending on your deployment.
Worker partitioning
Workers partition actor instances, not the append stream. All workers for a tenant share the same global stream; each worker owns a subset of actor instances and drains their queues.
Metrics
| Metric | Purpose |
|---|---|
yoke_runtime_workers | Active workers with recent heartbeat |
yoke_queue_depth | Per-instance backlog — detect hot spots |