External Workers

How SDK processes connect to iii and register application logic.

External workers are application processes that use an iii SDK. They connect to the engine over WebSocket, register functions and triggers, and execute business logic when the engine invokes them.

Lifecycle

1. The worker starts in Node.js, Python, Rust, or the browser.
2. The SDK connects to the engine WebSocket endpoint.
3. The worker registers functions, trigger types, triggers, and optional service metadata.
4. The engine routes matching invocations to that worker.
5. The SDK sends results or errors back over the same connection.

SDKs

SDK	Package
Node.js	iii-sdk
Browser	iii-browser-sdk
Python	iii-sdk
Rust	iii-sdk

External workers can run locally, in containers, on separate hosts, or in browser tabs. They only need network access to the engine WebSocket endpoint. 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 in results from engine::workers::list
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.trigger({
  function_id: 'engine::workers::list',
  payload: {},
})
// workers: WorkerInfo[] with id, name, runtime, version, os,
// status, connected_at_ms, function_count, functions[], active_invocations

result = iii.trigger({
    "function_id": "engine::workers::list",
    "payload": {},
})
workers = result.get("workers", [])

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