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

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 (deprecated)

The engine injects iii-engine-functions, iii-telemetry, iii-observability, and the iii-sandbox router 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.

iii-stream is deprecated (iii-stream) and will be removed in an upcoming release. Behavior is unchanged for now: the engine still accepts the configuration shown below. See Migrate from iii-stream and pubsub.

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. A Compose-managed engine is bound to the sandbox-libkrun adapter for you. An engine that no Compose file manages sets the top-level sandbox section in this file instead, or its sandbox::* calls fail with S303:

sandbox:
  adapter: sandbox-libkrun
  namespace: default

adapter is the adapter’s function prefix, and namespace is the namespace it registers in (default when omitted). See Sandboxes.

Project workers

HTTP, cron, queue, state, pubsub, bridge, application workers, and other registry workers belong in worker-compose.yaml. The pubsub worker is deprecated; see Migrate from iii-stream and pubsub. For the normal managed lifecycle, move the four engine configs into its direct engine.workers map and start the single file:

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 for Compose lifecycle operations and Move workers from config.yaml 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.

Getting Started

Using iii

Understanding iii

Creating Workers

Upgrading

The engine is the router

Engine configuration

Project workers

Environment variable expansion

Default configuration

​The engine is the router

​Engine configuration

​Project workers

​Environment variable expansion

​Default configuration

The engine is the router

Engine configuration

Project workers

Environment variable expansion

Default configuration