> ## Documentation Index > Fetch the complete documentation index at: https://motiadev-docs-deployment-guide.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Workers > Using workers in your iii project. {/* TODO: Add back once worker init is merged. This page covers using existing workers. For creating new workers (`iii worker init`), registering functions and triggers, and building or publishing worker images, see [Creating Workers / Workers](../creating-workers/workers). */} ## 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. For the SDK calls that establish the connection from worker code, see [Creating Workers / Workers](../creating-workers/workers#connecting-to-the-engine). ## Managing workers The `iii worker` CLI commands cover the full lifecycle of every worker in your project: finding new ones in the registry, installing them into `config.yaml` and `iii.lock`, controlling their running state, inspecting their logs, and removing them when they're no longer needed. ### 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](./workers-registry) for more information on the worker registry. ### Adding a worker You need iii [installed](../install) and [running](./engine) before adding a worker. To spin up a temporary iii instance for testing, run `iii --use-default-config` (see [Default configuration](./engine#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`). For local paths, Docker / OCI images, and version pinning, see [Worker Registry / Adding a worker](./workers-registry#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 -y # stop one worker (-y skips the confirmation prompt) iii worker restart # stop then start ``` To call functions inside running workers (directly with `worker.trigger` / `iii trigger`, or by binding them to events with optional condition gates), see [Triggers](./triggers). ### 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 ``` ### 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 ``` ### 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 -y # -y skips the confirmation when the worker is running ``` Downloaded artifacts remain on disk after removal. To delete them too, use `iii worker clear -y `. Omit the name to clear every worker's artifacts. ## 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 iii workers follow semver. A project records the resolved version of every managed worker in `iii.lock`, which makes installs reproducible across machines and platforms. ### Version pins 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. ### 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`](#updating-a-worker) is the third lockfile-related command; it re-resolves pins to the latest permitted versions and writes them back to `iii.lock`. ## 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](../creating-workers/workers).