/iii-engine-config

name: iii-engine-config
description: >-
  Configure a managed iii engine through worker-compose.yaml or a directly supervised engine
  through config.yaml. Use for engine ports, RBAC listeners, streams, sandboxes, and configuration
  storage.

Engine Config

iii has two engine configuration modes. Do not mix them.

Managed Compose engine

The presence of `engine:` means that Compose owns the engine process. Engine worker values are direct mappings; there is no nested `config:` field.

namespace: orders
engine:
  url: ws://127.0.0.1:49134
  registration_namespace_grace_ms: 5000
  workers:
    configuration:
      adapter:
        name: fs
        config:
          directory: ./config
    iii-worker-manager:
      host: 127.0.0.1
      port: 49134
    "iii-worker-manager#rbac":
      host: 0.0.0.0
      port: 49135
      middleware_function_id: auth::middleware
    iii-http-functions: {}
    iii-stream:
      host: 127.0.0.1
      port: 3112
    iii-sandbox:
      auto_install: true
containers: {}

Start it with:

iii compose --namespace orders-daemon --up --file worker-compose.yaml

`engine.url` defaults to `ws://127.0.0.1:49134` and uses Compose's `${VAR:-default}` expansion. `engine.workers` stays opaque until the engine reads the generated YAML, so its values use `${VAR:default}` and retain numeric types. Compose materializes an owner-only config under `<project-dir>/.iii/compose/<daemon-namespace>/` and removes it after clean shutdown. With `III_COMPOSE_STATE_DIR`, it uses `<state-root>/<project-slug>/<daemon-namespace>/`. Changing `engine:` requires restarting Compose. Do not combine a managed file with explicit `--engine`.

Allowed engine worker base names are:

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

Use `#instance` for another instance of an allowed worker. `iii-engine-functions`, `iii-telemetry`, and `iii-observability` are injected automatically and must not be declared.

HTTP, cron, queue, state, pubsub, bridge, application, and custom workers belong under `containers:`. Add registry packages with:

iii trigger -n orders-daemon compose::add worker=state

Directly supervised engine

Keep list-shaped `config.yaml` only when systemd, Kubernetes, or another supervisor owns the engine:

workers:
  - name: configuration
    config:
      adapter:
        name: fs
        config:
          directory: ./config
  - name: iii-worker-manager
    config:
      host: 127.0.0.1
      port: 49134

Start the engine and external Compose daemon separately:

iii --config config.yaml
iii compose --namespace orders-daemon --engine ws://127.0.0.1:49134 --up --file worker-compose.yaml

The external Compose file must omit `engine:`. `III_URL` may replace `--engine`. Direct config expansion uses `${VAR:default}` and accepts only the same five engine-owned worker types. Any project worker stops startup/reload with `UNSUPPORTED_CONFIG_WORKERS`.

Security and operations

• Bind private worker-manager listeners to `127.0.0.1`.
• Put public listeners behind `middleware_function_id` and RBAC registration hooks.
• Keep secrets in environment-backed configuration; do not commit literal credentials.
• Preserve configuration, stream, state, and queue storage paths during migrations.
• Use `compose::status` for process ownership and `engine::workers::list` for live connections.
• `compose::add` never edits `engine:` or restarts the engine.

When to Use

• Use this skill for managed `engine:` maps, direct `config.yaml`, engine-owned workers, ports,

adapters, RBAC listeners, or engine lifecycle selection.

• Use it when migrating engine worker blocks into Compose.

Boundaries

• Project worker lifecycle belongs to Compose, not `config.yaml` or `iii worker`.
• For function and trigger code, use `iii-core-primitives`.
• For worker-specific HTTP, queue, cron, state, or pubsub behavior, use that worker's docs.