iii
How-to Guides

Configure the Engine

Complete reference for iii-config.yaml with all modules, adapters, and options.

Goal

Configure iii functionality through its config file to enable modules, functionality, set up adapters, and customize behavior.

Overview

The config file controls:

  • Engine settings - WebSocket port for SDK connections
  • Modules - Features like HTTP endpoints, queues, state, cron, observability
  • Adapters - Storage backends (file, memory, Redis, RabbitMQ, etc.)

Specifying the config file

Configs can be specified to iii at startup with either the -c or --config flag:

iii -c iii-config.yaml

Environment Variables

Configuration values can use environment variables with optional defaults:

port: ${III_PORT:49134}
endpoint: ${OTEL_ENDPOINT:http://localhost:4317}
redis_url: ${REDIS_URL}  # No default - must be set

Syntax: ${VAR_NAME:default_value} or ${VAR_NAME} (required).

Common Configurations

Development

When doing development it is common to use built-in adapters with persistent file_based storage, and non-persistent in_memory storage.

iii-config.yaml
port: 49134
modules:
  - class: modules::api::RestApiModule
    config:
      port: 3111
  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::KvStore
        config:
          store_method: file_based # or in_memory
          file_path: ./data/state_store
  - class: modules::queue::QueueModule
    config:
      queue_configs:
        default:
          max_retries: 5
          concurrency: 5
          type: standard
      adapter:
        class: modules::queue::BuiltinQueueAdapter
        config:
          store_method: file_based # or in_memory
          file_path: ./data/queue_store

Production

While iii's built-in file_based adapters can be used in production it's common to swap them out for other adapters that are built for purpose such as Redis, or RabbitMQ.

Don't use in_memory in production

Do not use in_memory storage in production. in_memory storage does not persist between engine restarts if used can cause irrecoverable data loss.

iii-config.yaml
port: ${III_PORT:49134}
modules:
  - class: modules::api::RestApiModule
    config:
      port: ${HTTP_PORT:3111}
  - class: modules::state::StateModule
    config:
      adapter:
        class: modules::state::adapters::RedisAdapter
        config:
          redis_url: ${REDIS_URL}
  - class: modules::queue::QueueModule
    config:
      queue_configs:
        default:
          max_retries: 5
          concurrency: 5
          type: standard
      adapter:
        class: modules::queue::RabbitMQAdapter
        config:
          amqp_url: ${AMQP_URL}
        # class: modules::queue::RedisAdapter
        # config:
        #   redis_url: ${REDIS_URL}
  - class: modules::cron::CronModule
    config:
      adapter:
        class: modules::cron::RedisCronAdapter
        config:
          redis_url: ${REDIS_URL}
  - class: modules::observability::OtelModule
    config:
      enabled: true
      exporter: otlp
      endpoint: ${OTEL_ENDPOINT}
      level: warn
      format: json

Full Configuration Reference

Interactive reference for iii-config.yaml. Click sections to expand.

Engine Settings

Engine WebSocket port for SDK/worker connections.

Default: 49134

port:49134
class:modules::api::RestApiModule

TCP port for the HTTP server. Default: 3111

port:3111

Network interface to bind. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost only.

host:0.0.0.0

Maximum time (ms) before an HTTP request times out. Default: 30000

default_timeout:30000

Maximum concurrent HTTP requests the server will handle. Default: 1024

concurrency_request_limit:1024

Cross-Origin Resource Sharing configuration for browser clients.

class:modules::stream::StreamModule

TCP port for WebSocket connections. Default: 3112

port:3112

Network interface to bind. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost only.

host:0.0.0.0

Function that validates stream connection/subscription requests (e.g., auth checks).

Set to null or omit to allow all connections.

auth_function:stream.auth

Storage backend for stream state (subscriptions, message history).

Alternative adapters:

class:modules::state::StateModule

Alternative adapters:

class:modules::queue::QueueModule

Alternative adapters:

class:modules::pubsub::PubSubModule

Alternative adapter:

class:modules::cron::CronModule

Alternative adapter:

class:modules::observability::OtelModule

Master switch for all observability features.

enabled:false

Service name in traces/metrics/logs. Used for filtering in observability backends.

service_name:iii

Service version tag. Useful for correlating deployments with telemetry changes.

service_version:'1.0.0'

Namespace/environment label (e.g., production, staging, development).

service_namespace:production

Trace export destination. Options: memory (queryable via API), otlp (send to collector), both

exporter:both

OTLP collector endpoint. Required when exporter is otlp or both.

Common endpoints: Jaeger (4317), Grafana Tempo (4317), Honeycomb, Datadog.

endpoint:http://localhost:4317

Base sampling ratio (0.0-1.0). 1.0 = sample all traces, 0.1 = sample 10%.

Overridden by advanced sampling rules below when configured.

sampling_ratio:1.0

Advanced sampling - fine-grained control over which traces to keep.

Maximum spans to retain in memory. Used when exporter is memory or both.

Higher = more history for local debugging, more memory usage.

memory_max_spans:10000

Metrics collection for counters, gauges, histograms.

metrics_enabled:true

Metrics storage. Options: memory (queryable via API), otlp (send to collector)

metrics_exporter:memory

How long (seconds) to retain metrics before expiration. Default: 3600 (1 hour)

metrics_retention_seconds:3600

Maximum metric data points to store. Prevents unbounded memory growth.

metrics_max_count:10000

Log collection and storage.

logs_enabled:true

Log export destination. Options: memory (queryable via API), otlp (send to collector), both

logs_exporter:both

Maximum log records to retain in memory.

logs_max_count:1000

How long (seconds) to retain logs before expiration. Default: 3600 (1 hour)

logs_retention_seconds:3600

Batch size for OTLP log export. Larger batches = fewer network calls, higher latency.

logs_batch_size:100

How often (ms) to flush logs to OTLP collector.

logs_flush_interval_ms:5000

Log sampling ratio (0.0-1.0). 1.0 = keep all logs, 0.5 = keep 50%.

logs_sampling_ratio:1.0

Also print SDK logs to engine console for local debugging.

logs_console_output:true

Alert rules - trigger actions when metrics cross thresholds.

Engine console log level. Options: trace, debug, info, warn, error

trace = most verbose, error = only errors.

level:info

Alias for level (deprecated, use level instead).

log_level:info

Console output format. Options: default (human-readable with colors), json (structured)

format:json
class:modules::http_functions::HttpFunctionsModule

Local development alternative — relaxes security to allow localhost targets:

class:modules::shell::ExecModule

Directories to watch for file changes. Changes trigger process restart.

Command and arguments to execute. First element is command, rest are args.

class:modules::shell::ExecModule
class:modules::bridge_client::BridgeClientModule

WebSocket URL of the remote iii engine to connect to.

url:ws://localhost:49134

Unique identifier for this client in the remote engine's registry.

service_id:bridge-client

Human-readable name for logging and observability.

service_name:bridge-client

Functions to expose to the remote engine (remote can call local functions).

Functions to forward to remote engine (local calls invoke remote functions).

class:modules::telemetry::TelemetryModule

Enable/disable anonymous telemetry. Set to false to opt out.

enabled:true

API key for telemetry backend (leave empty for anonymous tracking).

api_key:''

Separate API key for SDK telemetry events.

sdk_api_key:''

How often (seconds) to send heartbeat events. Default: 21600 (6 hours)

heartbeat_interval_secs:21600

Create a Custom Trigger Type

Register a custom trigger type so functions can be fired by events that iii does not handle natively.

Architecture

The structural components of an iii system.

On this page

Goal
Overview
Specifying the config file
Environment Variables
Common Configurations
Development
Production
Full Configuration Reference
Engine Settings
RestApiModule
StreamModule
StateModule
QueueModule
PubSubModule
CronModule
OtelModule
HttpFunctionsModule
ExecModule
ExecModule
BridgeClientModule
TelemetryModule