Using Iii

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

# Engine


## Engine configuration

The iii engine starts from a `config.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.

```bash
iii --config config.yaml
```

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

```yaml
workers:
  - name: http
    config:
      port: 3111
      host: 127.0.0.1

  - name: state
    config:
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/state_store.db
```

The `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](./configuration); 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](./configuration) for the full lifecycle.

{/* TODO: replace this paragraph with the auto-generated engine config reference. Per project-rules/config.md, the per-field `workers:` schema should not be hand-authored here; this section is a placeholder pending the generated reference. */}

Per-worker config schemas live on each worker's Worker Docs page. See
[Worker Registry](./workers-registry) for where to find a worker's config reference.

<Note>
  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)](./workers#the-lockfile-iii-lock) for the full story.
</Note>

<Note>
  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](../creating-workers/workers#connecting-to-the-engine) for more information.
</Note>

## Environment variable expansion

Values in `config.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](./configuration#environment-variables-in-values).

```yaml
workers:
  - name: http
    config:
      port: ${HTTP_PORT:3111}
      host: ${HTTP_HOST:127.0.0.1}
```

## Default configuration

Run `iii` 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.