Skip to main content

Documentation Index

Fetch the complete documentation index at: https://iii.dev/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
How workers expand iii

Workers add capability to an iii system. Each one contributes functions and triggers the engine can route to. This page covers deploying and wiring workers into a project. For the authoring surface a worker uses to register its functions and triggers (the SDK), see each language’s Worker Docs authoring guide.

​
Connecting to the engine

A worker connects to the engine over WebSocket. Set the engine URL via the III_URL environment variable, or pass it explicitly to register_worker. The connection string is the only coupling between a worker and the iii instance it joins, so the worker process can be deployed anywhere reachable on the network. 
import { registerWorker } from "iii-sdk";

const worker = registerWorker(process.env.III_URL);

​
Worker lifecycle states

Workers transition through a small set of states after connecting: connecting → connected → available / busy → disconnected. connecting is the WebSocket handshake. connected means the Worker has joined the Engine’s registry. available and busy describe whether the Worker is currently handling invocations. disconnected is the terminal state when the WebSocket closes. The Engine tracks these transitions and surfaces them to other Workers and tooling through its discovery functions, so the rest of the system can react.

​
Handling Worker disconnects

When a Worker’s WebSocket closes, the Engine cleans up after it automatically. Its Functions and Triggers leave the live registry, and any in-flight invocations of those Functions are cancelled. There are two things to handle on the caller side:
  1. Catch invocation_stopped. Callers waiting on a Function whose Worker disconnects mid-flight receive an invocation_stopped error rather than a timeout. Treat it like a cancellation, not a transient failure. Retrying will fail until a Worker reconnects and re-registers the Function.
  2. Subscribe to the discovery events if you need to react to topology changes:
    • engine::workers-available fires immediately when a Worker connects or disconnects.
    • engine::functions-available is eventually consistent; it fires on the next polling tick once the function-list hash changes.

​
Inspecting the live registry

To see what’s currently connected to the Engine, use one of two surfaces depending on whether you want a snapshot or a live subscription:
  • Read a snapshot by invoking one of the engine::*::list Functions:
    • engine::workers::list: every connected Worker with metrics.
    • engine::functions::list: every registered Function (filterable by include_internal).
    • engine::triggers::list: every registered Trigger (filterable by include_internal).
    • engine::trigger-types::list: every advertised Trigger type with its config and call schemas.
  • Subscribe to changes by registering a Trigger against engine::workers-available (fires when a Worker connects or disconnects) or engine::functions-available (fires when a Function is registered or unregistered). See Handling Worker disconnects for their consistency semantics.
These are the high-level call surfaces. For the wire-level shapes, see Engine protocol.

​
Worker manifest

When a worker is checked into a project so iii can launch it locally, iii.worker.yaml at the worker’s root tells iii how to install dependencies, run the worker, and pass through configuration. 
name: math-worker
runtime:
  kind: python
  package_manager: pip
  entry: math_worker.py
scripts:
  install: "pip install -r requirements.txt"
  start: "python math_worker.py"
The manifest is metadata about starting the Worker. Once the Worker is running, the WebSocket connection to the Engine and the function registrations are what matter. A Worker started by iii worker add and a Worker started by hand in a container behave identically to the Engine. For the full manifest field schema, see Using iii / Workers.

​
What a worker contributes

Once connected, a worker exposes: The SDK calls a worker uses to register these are language-specific and documented in each language’s Worker Docs authoring guide.

​
Run an ephemeral worker

For one-shot jobs (Kubernetes Jobs, serverless containers, scheduled scripts), an SDK worker can connect to a remote engine, register its functions, do the work, and exit. The engine cleans up the worker’s registrations on disconnect. Set III_URL to point the worker at the remote engine (see Connecting to the engine), register the work the job needs to expose, and let the process exit when the job is done.