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

# Engine

> Configuring and running the iii engine.

## The engine is the router

The engine receives function calls, routes them to connected workers, and routes results back to
callers. Project workers have their own lifecycle under [Compose](./compose); `config.yaml` is not a
general process manager.

## Engine configuration

The engine reads `config.yaml` from the project root. Pass `--config <path>` to select another file.
When the file is missing, interactive sessions offer to create it and non-interactive sessions
create an empty one automatically.

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii --config config.yaml
```

Only workers coupled to the engine lifecycle may be declared in this file:

* `configuration`
* `iii-worker-manager`
* `iii-http-functions`
* `iii-stream`
* `iii-sandbox`

The engine injects `iii-engine-functions`, `iii-telemetry`, and `iii-observability` automatically;
do not declare them. Any other name makes initial startup or config reload fail with
`UNSUPPORTED_CONFIG_WORKERS` and a link to the [manual migration
guide](../upgrading/workers-to-compose).

```yaml theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
workers:
  - name: iii-stream
    config:
      port: ${STREAM_PORT:3112}
      host: 127.0.0.1
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/stream_store

  - name: configuration
    config:
      adapter:
        name: fs
        config:
          directory: ./config
```

The engine watches this file. A valid change reloads the affected engine worker; an invalid change
stops the engine so it cannot continue with a configuration different from the file on disk.

## Project workers

HTTP, cron, queue, state, pubsub, bridge, application workers, and other registry workers belong in
`worker-compose.yaml`. For the normal managed lifecycle, move the five engine configs into its
direct `engine.workers` map and start the single file:

```bash theme={"theme":{"light":"catppuccin-latte","dark":"dark-plus"}}
iii compose --namespace dev --up --file worker-compose.yaml
```

Keep the list-shaped `config.yaml` only when another supervisor owns the engine. In that case omit
`engine:` from the Compose file, run the processes separately, and connect with
`--engine <ws-url>` or `III_URL`.

See [Workers](./workers) for Compose lifecycle operations and [Move workers from config.yaml to
Compose](../upgrading/workers-to-compose) for existing projects.

## Environment variable expansion

Values in direct `config.yaml` and `engine.workers` support `${VAR:default}`; the engine expands
them before typing the generated YAML. Compose-owned fields such as `engine.url` use
`${VAR:-default}`. `config_override` is likewise carried to the configuration worker without
Compose expanding it.

## Default configuration

The generated file contains `workers: []`. Mandatory engine services still start, but no project
worker does. Add project workers to `worker-compose.yaml` and use `iii compose --up`; do not add them
to the empty engine list.

Workers may also be started by another supervisor or on another machine. Any SDK process that
connects and registers is a worker, independent of Compose.