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.

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

​
Finding workers

We maintain a worker registry which you can explore at workers.iii.dev. The registry contains many workers that encapsulate common services. See Worker Registry for more information on the worker registry.

​
Adding a worker

You need iii installed and running before adding a worker. To spin up a temporary iii instance for testing, run iii --use-default-config (see Default configuration).
iii worker add <name> installs a worker into your project: 
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 <name> (equivalent to add --force).
For local paths, Docker / OCI images, and version pinning, see Worker Registry / Adding a worker.

​
Listing workers

iii worker list shows every worker declared in your project’s config.yaml along with its current status: 
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: 
iii worker start <name>     # start one worker
iii worker stop <name>      # stop one worker
iii worker restart <name>   # stop then start
To call functions inside running workers (directly with iii.trigger / iii trigger, or by binding them to events with optional condition gates), see Triggers.

​
Inspecting a worker

To check a specific worker’s state, follow its logs, or run a command inside the worker’s sandbox, use: 
iii worker status <name>             # config, sandbox state, recent logs
iii worker logs <name>               # stream the worker's logs
iii worker exec <name> -- <command>  # 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://<worker>/<leaf> 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 @<version> to a registry name to pin a specific release rather than tracking the latest: 
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: 
iii worker update <worker-name>   # 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: 
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: 
iii worker remove <worker-name>
Downloaded artifacts remain on disk after removal. To delete them too, use iii worker clear <worker-name>. 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 and Creating Workers / Worker Registry.