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