Workers

Any process that connects to the iii Engine using an SDK and registers Functions.

A Worker is any process that connects to the iii Engine over WebSocket using an SDK and registers Functions. The Engine routes incoming triggers to the correct Worker, which executes the handler and optionally returns a result.

Workers are independent processes — they can be written in any language, run anywhere, and crash without affecting other Workers.

Diagrams

Architecture

Lifecycle Overview

Creating a Worker

A Worker is simply any collection of registered Functions and Triggers that has registered itself with the iii engine. See How to use Functions and Triggers for details on registering functions within workers. Read below for Worker responsibilities and configuration.

What Workers Do

Responsibility	Description
Function hosting	Register Functions with the Engine and execute them when triggered
SDK connection	Connect to the Engine via WebSocket, auto-reconnect on disconnect
Language runtime	Run in their own process in any iii-sdk supported language
Isolation	Workers are independent processes. A crash in one Worker doesn't propagate to others

Init Options

The second argument to registerWorker() configures the Worker's behavior:

Option	Type	Default	Description
`workerName`	`string`	`${hostname}:${pid}`	Name shown in the iii Console and `listWorkers()`
`invocationTimeoutMs`	`number`	`30000`	Default timeout for `trigger()` calls in milliseconds
`enableMetricsReporting`	`boolean`	`true`	Report CPU, memory, and event loop metrics to the Engine
`reconnectionConfig`	`object`	see below	WebSocket reconnection behavior
`otel`	`object`	auto	OpenTelemetry configuration. Set `{ enabled: false }` to disable

Reconnection Config

Workers reconnect automatically on disconnect using exponential backoff:

Field	Default	Description
`initialDelayMs`	`1000`	First retry delay
`maxDelayMs`	`30000`	Maximum retry delay cap
`backoffMultiplier`	`2`	Multiplier applied to delay each attempt
`jitterFactor`	`0.3`	Random jitter 0–1 to prevent thundering herd
`maxRetries`	`-1`	Maximum attempts. `-1` = infinite

Python naming: Python uses snake_case for these fields: initial_delay_ms, max_delay_ms, backoff_multiplier, jitter_factor, max_retries.

import { registerWorker } from 'iii-sdk'

const iii = registerWorker('ws://localhost:49134', {
  workerName: 'user-service',
  invocationTimeoutMs: 10000,
  reconnectionConfig: {
    initialDelayMs: 500,
    maxDelayMs: 10000,
    maxRetries: 10,
  },
})

Worker Lifecycle

When a Worker connects, the SDK sends its metadata to the Engine via engine::workers::register:

runtime: 'node' | 'python' | 'rust'
version: SDK version
name: workerName
os: platform + arch

The Engine assigns a worker_id and the Worker's status transitions through:

connecting → connected → available / busy → disconnected

On disconnect — clean or crash — the Engine automatically removes all the Worker's registered Functions and Triggers. On reconnect, the SDK re-registers everything automatically.

Worker Metadata

You can inspect all connected Workers at runtime:

const workers = await iii.listWorkers()
// returns WorkerInfo[] with: id, name, runtime, version, os,
// status, connected_at_ms, function_count, functions[], active_invocations

workers = iii.list_workers()

On this page