Creating Workers

<!-- generated by iii-skill-render. DO NOT EDIT (changes here are overwritten on the next render). Edit docs/0-12-0/creating-workers/workers.mdx. -->

# Workers


## 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.

<Tabs>
  <Tab title="Node / TypeScript">
    ```typescript
    import { registerWorker } from "iii-sdk";

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

  </Tab>
  <Tab title="Python">
    ```python
    import os
    from iii import register_worker, InitOptions

    worker = register_worker(
        os.environ.get("III_URL"),
        InitOptions(worker_name="my-worker"),
    )
    ```

  </Tab>
  <Tab title="Rust">
    ```rust
    use iii_sdk::{InitOptions, register_worker};

    let url = std::env::var("III_URL").expect("III_URL must be set");
    let worker = register_worker(&url, InitOptions::default());
    ```

  </Tab>
</Tabs>

## 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.
1. **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](#handling-worker-disconnects) for
  their consistency semantics.

<Note>
  These are the high-level call surfaces. For the wire-level shapes, see [Engine
  protocol](../sdk-reference/engine-sdk#engine-discovery-functions).
</Note>

## 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.

```yaml
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](../using-iii/workers).

## What a worker contributes

Once connected, a worker exposes:

- Functions, callable by `function_id` from anywhere in the system (see
  [Using iii / Functions](../using-iii/functions)).
- Triggers it advertises, which other workers can bind their functions to (see
  [Using iii / Triggers](../using-iii/triggers)).

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](#connecting-to-the-engine)), register the work the job needs to expose,
and let the process exit when the job is done.