> ## 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. # Workers > Using workers in your iii project. ## Workers are sort of like services Think of workers as iii's version of a self-contained, isolated service that freely interoperates with every other worker. Any time you're adding functionality that functionality will come in the form of a worker. Workers differ from traditional services by not requiring any integration to use. Instead workers can be installed and managed like npm packages with the command `iii worker add` below. The difference is that you get complete deployable runtimes rather than a library. See the section on adding workers below. ## Worker lifecycle Workers connect to iii over WebSocket. When a worker connects it becomes visible to the entire iii system and every other worker within it. When a worker disconnects, its functions and triggers stop being callable until it reconnects. > [!NOTE] > > For the SDK calls that establish the connection from worker code, see [Creating Workers / > Workers](https://iii.dev/docs/0-12-0/creating-workers/workers.md#connecting-to-the-engine). ## Finding workers We maintain a worker registry which you can explore at [workers.iii.dev](https://workers.iii.dev/). The registry contains many workers that encapsulate common services. See [Worker Registry](https://iii.dev/docs/0-12-0/using-iii/workers-registry.md) for more information on the worker registry. ## Adding a worker > [!NOTE] > > You need iii [installed](https://iii.dev/docs/0-12-0/install.md) and [running](https://iii.dev/docs/0-12-0/using-iii/engine.md) before adding a worker. To > spin up a temporary iii instance for testing, run `iii --use-default-config` (see [Default > configuration](https://iii.dev/docs/0-12-0/using-iii/engine.md#default-configuration)). `iii worker add ` installs a worker into your project: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker add iii-state ``` The worker is added to `config.yaml` and started automatically. To force a redownload of an existing worker, use `iii worker reinstall ` (equivalent to `add --force`). > [!NOTE] > > For local paths, Docker / OCI images, and version pinning, see [Worker Registry / Adding a > worker](https://iii.dev/docs/0-12-0/using-iii/workers-registry.md#adding-a-worker). ## Listing workers `iii worker list` shows every worker declared in your project's `config.yaml` along with its current status: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker list ``` ## Starting and stopping workers Added workers start automatically with the engine. To control them manually, use the `start`, `stop`, and `restart` commands: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker start # start one worker iii worker stop # stop one worker iii worker restart # stop then start ``` > [!NOTE] > > To call functions inside running workers (directly with `iii.trigger` / `iii trigger`, or by > binding them to events with optional condition gates), see [Triggers](https://iii.dev/docs/0-12-0/using-iii/triggers.md). ## Inspecting a worker To check a specific worker's state, follow its logs, or run a command inside the worker's sandbox, use: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker status # config, sandbox state, recent logs iii worker logs # stream the worker's logs iii worker exec -- # run a command inside the worker ``` ## Worker skills Every worker also ships with skills for Agentic work. Skills are managed by the `skills` worker, an actively developed content-registry worker added to a project like any other. Skill bodies load lazily. Top-level entries stay small; agents fetch deeper content via `iii:///` section URIs only when a function reference resolves to one. We ship high level skills as well which make it possible for any agent to make immediate use of iii and its workers. ## Available functions and triggers Functions and triggers come from connected workers. To use a trigger of a given type, you need the worker that provides it to be connected. For example if you add `http` triggers via the iii-http worker then you can now expose endpoints for your function just as you would in a web framework like Express or FastAPI. ## Versioning and pinning Workers are published with semver versions. Installing without a version specifier picks the latest release. Append `@` to a registry name to pin a specific release rather than tracking the latest: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker add iii-state@1.2.0 ``` The pin is recorded in `iii.lock` and replays on every subsequent install, so the same deployment of an iii system is reproducible across machines. ## Updating a worker `iii worker update` re-resolves locked workers and writes the new pins back to `iii.lock`. Pass a worker name to update one, or omit it to update every locked worker: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker update # one worker iii worker update # every locked worker ``` ## The lockfile (iii.lock) `iii.lock` is a YAML file at your project root. It pins each managed worker to a specific version and source so the same worker set installs the same way across machines and platforms. Binary workers can pin per-platform artifacts (macOS, Linux, Windows) in the same lockfile. Commit `iii.lock` alongside `config.yaml` for reproducible installs. Two commands operate on the lockfile directly: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker sync # install workers exactly from iii.lock iii worker sync --frozen # CI form: verify the lockfile without mutating local files iii worker verify # report drift between config.yaml and iii.lock ``` `iii worker update` (above) is the third lockfile command; it re-resolves pins to the latest permitted versions and writes them back to `iii.lock`. ## Removing a worker `iii worker remove` drops a worker from `config.yaml` and the engine tears down the running worker process: ```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}} iii worker remove ``` Downloaded artifacts remain on disk after removal. To delete them too, use `iii worker clear `. Omit the name to clear every worker's artifacts. ## Authoring workers Creating a new worker, registering functions and triggers in worker code, and building or publishing a worker image are out of scope for this page. See [Creating Workers / Workers](https://iii.dev/docs/0-12-0/creating-workers/workers.md) and [Creating Workers / Worker Registry](../creating-workers/workers-registry). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.