Skip to main content

​
The engine is just a router

Think of the engine like a router, it receives requests, routes them to workers, and routes responses back as needed.

​
Engine configuration

The iii engine starts from a config.yaml file at your project root. Pass --config <path> to point at a different file, or --use-default-config to start with a default set of workers (handy for first-run and scratch work). 
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 a config block whose shape is defined by that worker and is read once, as a first-boot seed. 
workers:
  - name: iii-http
    config:
      port: 3111
      host: 127.0.0.1

  - name: iii-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; 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 for the full lifecycle. Per-worker config schemas live on each worker’s Worker Docs page. See Worker Registry for where to find a worker’s config reference.
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) for the full story.
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 for more information.

​
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. 
workers:
  - name: iii-http
    config:
      port: ${HTTP_PORT:3111}
      host: ${HTTP_HOST:127.0.0.1}

​
Default configuration

Run iii --use-default-config to start the engine with a default set of workers without writing a config.yaml. Useful for first-run and scratch work. Once you need to customize ports, adapters, or the set of workers, switch to a real config.yaml.