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()

For details on building and deploying Workers in production, see the Quickstart tutorial or the SDK Reference.