The engine is just a router
Think of the engine like a router, it receives requests, routes them to workers, and routes responses back as needed.Engine configuration
The iii engine starts from aconfig.yaml file at your project root. Pass --config <path> to
point at a different file. When the file doesn’t exist yet, iii offers to create it (handy for
first-run and scratch work); non-interactive sessions create it without asking.
Configuration file structure
config.yaml has a single top-level key, workers:, that lists the workers the engine should load.
Each entry has a name (a registry slug or local worker name) and, optionally, a config block
whose shape is defined by that worker and is read once, as a first-boot seed. A bare - name:
entry (what iii worker add writes) boots the worker with its built-in defaults.
config: block under a worker is a first-boot seed. A worker that registers a
configuration schema reads it once to create its entry in the
configuration worker; from then on its settings are stored in one file per
worker under ./config/, editable in real time from disk, the console, or configuration::set,
and the engine removes the consumed block from config.yaml, leaving a comment in its place. See
Configuration for the full lifecycle.
Per-worker config schemas live on each worker’s Worker Docs page. See
Worker Registry for where to find a worker’s config reference.
The engine reads
config.yaml and launches the worker installations on disk; it does not read
iii.lock. The lockfile is a worker-installation concern, written and consumed by iii worker sync / update / verify to make installs reproducible. See Workers / The lockfile
(iii.lock) for the full story.Workers do not need to be running alongside iii; configuring them in config.yaml is a convenience. A worker
can be deployed anywhere and only needs a connection string to the iii instance. See
Creating Workers / Connecting to the engine for more information.
Environment variable expansion
Values inconfig.yaml support ${VAR:default} syntax. The expansion uses the value of the
environment variable VAR, falling back to default when the variable is not set. Use this to swap
ports, URLs, and feature flags per environment without forking the config file. The same syntax
works inside the per-worker configuration files, where placeholders are re-expanded on every read;
see Configuration / Environment variables in values.
Default configuration
Runiii in a directory with no config.yaml and it offers to create one (non-interactive
sessions such as containers and CI create the file without asking). The created file starts with an
empty workers: list: the engine boots with its internal services (the WebSocket listener
SDK workers connect to, the configuration worker, observability), and you opt into everything else
with iii worker add <name>; the engine watches the file and picks new workers up live. Workers
boot with their built-in defaults. Customize ports, adapters, or credentials at runtime through the
configuration worker or the persisted per-worker config file under ./config/. To seed the initial
configuration instead, add a config: block to an entry before the worker’s first boot.