Skip to main content

​
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
modules:
  - class: modules::worker::WorkerModule
    config:
      port: 49134

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

​
Configuration Reference

​
port
integer
default:"49134"
Engine WebSocket port for SDK/worker connections.
​
modules
array
required
List of modules to enable. Each entry requires a class identifier and an optional config object.

​
Modules

Class: modules::api::RestApiModuleExposes HTTP endpoints for triggers and the core API surface. Functions with HTTP triggers are served through this module.
​
config.port
integer
default:"3111"
TCP port for the HTTP server.
​
config.host
string
default:"0.0.0.0"
Network interface to bind. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost only.
​
config.default_timeout
integer
default:"30000"
Maximum time (ms) before an HTTP request times out.
​
config.concurrency_request_limit
integer
default:"1024"
Maximum concurrent HTTP requests the server will handle.
​
config.cors
object
Cross-Origin Resource Sharing configuration for browser clients.
Class: modules::stream::StreamModuleReal-time WebSocket pub/sub for live data streaming to clients. Clients connect via WebSocket to receive pushed updates on subscribed channels.
​
config.port
integer
default:"3112"
TCP port for WebSocket connections.
​
config.host
string
default:"0.0.0.0"
Network interface to bind. Use 0.0.0.0 for all interfaces, 127.0.0.1 for localhost only.
​
config.auth_function
string
Function that validates stream connection/subscription requests (e.g., auth checks). Set to null or omit to allow all connections.
​
config.adapter
object
required
Storage backend for stream state (subscriptions, message history).
Class: modules::state::StateModulePersistent key-value storage for function state across invocations. Functions use ctx.state.get / ctx.state.set to read and write stateful data.
​
config.adapter
object
required
Storage backend for state data.
Class: modules::queue::QueueModuleBackground job processing with retries, dead-letter queues, and concurrency control. Functions enqueue jobs; subscribers process them asynchronously.
​
config.adapter
object
required
Job queue backend.
Class: modules::pubsub::PubSubModuleIn-process event fanout for decoupled function communication. Functions publish events; multiple subscribers receive them immediately.
​
config.adapter
object
required
PubSub backend.
Class: modules::cron::CronModuleTime-based job scheduling using cron expressions. Functions with cron triggers execute on schedule.
​
config.adapter
object
required
Cron scheduling backend.
Class: modules::observability::OtelModuleOpenTelemetry tracing, metrics, logs, and alerting. Provides visibility into function execution, performance, and errors.
​
config.enabled
boolean
default:"false"
Master switch for all observability features.
​
config.service_name
string
default:"iii"
Service name in traces/metrics/logs. Used for filtering in observability backends.
​
config.service_version
string
default:"1.0.0"
Service version tag. Useful for correlating deployments with telemetry changes.
​
config.service_namespace
string
default:"production"
Namespace/environment label (e.g., production, staging, development).
​
config.exporter
string
default:"both"
Trace export destination. Options: memory (queryable via API), otlp (send to collector), both.
​
config.endpoint
string
default:"http://localhost:4317"
OTLP collector endpoint. Required when exporter is otlp or both. Common endpoints: Jaeger (4317), Grafana Tempo (4317), Honeycomb, Datadog.
​
config.sampling_ratio
float
default:"1.0"
Base sampling ratio (0.0–1.0). 1.0 = sample all traces, 0.1 = sample 10%. Overridden by advanced sampling rules when configured.
​
config.sampling
object
Advanced sampling — fine-grained control over which traces to keep.
​
config.memory_max_spans
integer
default:"10000"
Maximum spans to retain in memory (when exporter is memory or both). Higher = more history for local debugging, more memory usage.
​
config.metrics_enabled
boolean
default:"true"
Enable metrics collection for counters, gauges, and histograms.
​
config.metrics_exporter
string
default:"memory"
Metrics storage. Options: memory (queryable via API), otlp (send to collector).
​
config.metrics_retention_seconds
integer
default:"3600"
How long (seconds) to retain metrics before expiration.
​
config.metrics_max_count
integer
default:"10000"
Maximum metric data points to store. Prevents unbounded memory growth.
​
config.logs_enabled
boolean
default:"true"
Enable log collection and storage.
​
config.logs_exporter
string
default:"both"
Log export destination. Options: memory (queryable via API), otlp (send to collector), both.
​
config.logs_max_count
integer
default:"1000"
Maximum log records to retain in memory.
​
config.logs_retention_seconds
integer
default:"3600"
How long (seconds) to retain logs before expiration.
​
config.logs_batch_size
integer
default:"100"
Batch size for OTLP log export. Larger batches = fewer network calls, higher latency.
​
config.logs_flush_interval_ms
integer
default:"5000"
How often (ms) to flush logs to the OTLP collector.
​
config.logs_sampling_ratio
float
default:"1.0"
Log sampling ratio (0.0–1.0). 1.0 = keep all logs, 0.5 = keep 50%.
​
config.logs_console_output
boolean
default:"true"
Also print SDK logs to engine console for local debugging.
​
config.alerts
array
Alert rules — trigger actions when metrics cross thresholds.
​
config.level
string
default:"info"
Engine console log level. Options: trace, debug, info, warn, error. trace = most verbose, error = only errors.
​
config.format
string
default:"json"
Console output format. Options: default (human-readable with colors), json (structured).
Class: modules::http_functions::HttpFunctionsModuleEnables HTTP-invoked functions (outbound HTTP calls from the engine). Required for functions registered with HttpInvocationConfig. The engine makes the HTTP request on behalf of the function and enforces URL security policies.
​
config.security
object
URL security policies for outbound requests.
For local development, you can relax security by setting block_private_ips: false and require_https: false to allow localhost targets.
Class: modules::shell::ExecModuleSpawns external processes (SDK workers) and watches for file changes. Useful for setups where workers need to run alongside the engine on the same host, or from frameworks like Motia.
​
config.watch
string[]
Directories to watch for file changes. Changes trigger process restart.
​
config.exec
string[]
Command and arguments to execute. First element is the command, rest are arguments.
# Example: run Python SDK worker
- class: modules::shell::ExecModule
  config:
    watch:
      - ./steps
    exec:
      - motia-py

# Example: run Node.js SDK worker
- class: modules::shell::ExecModule
  config:
    watch:
      - ./steps
    exec:
      - npx
      - motia-node
Class: modules::bridge_client::BridgeClientModuleConnects this engine to a remote iii instance for cross-instance function invocation. Enables distributed architectures and function federation.
​
config.url
string
required
WebSocket URL of the remote iii engine to connect to.
​
config.service_id
string
required
Unique identifier for this client in the remote engine’s registry.
​
config.service_name
string
Human-readable name for logging and observability.
​
config.expose
array
Functions to expose to the remote engine (remote can call local functions).
​
config.forward
array
Functions to forward to the remote engine (local calls invoke remote functions).
Class: modules::telemetry::TelemetryModuleAnonymous product usage analytics for iii development. Helps the team understand usage patterns and prioritize features.
​
config.enabled
boolean
default:"true"
Enable/disable anonymous telemetry. Set to false to opt out.
​
config.api_key
string
API key for telemetry backend. Leave empty for anonymous tracking.
​
config.sdk_api_key
string
Separate API key for SDK telemetry events.
​
config.heartbeat_interval_secs
integer
default:"21600"
How often (seconds) to send heartbeat events. Default is 6 hours.