The iii Engine

Motia is the application framework — you write Steps in TypeScript, Python, or JavaScript. The iii engine is the runtime that powers everything underneath. It manages queues, state storage, stream servers, cron scheduling, HTTP routing, observability, and the lifecycle of your application processes.

How Motia and iii Work Together

┌─────────────────────────────────────────────┐
│                 iii Engine                  │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  Queue   │  │  State   │  │  Stream  │   │
│  │  Module  │  │  Module  │  │  Module  │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐   │
│  │  REST    │  │   Cron   │  │  OTel    │   │
│  │  API     │  │  Module  │  │  Module  │   │
│  └──────────┘  └──────────┘  └──────────┘   │
│  ┌──────────┐  ┌──────────┐                 │
│  │  PubSub  │  │   Exec   │  ← manages      │
│  │  Module  │  │  Module  │    SDK process  │
│  └──────────┘  └──────────┘                 │
│                     │                       │
│                     ▼                       │
│            ┌─────────────────┐              │
│            │   Motia SDK     │              │
│            │  (your Steps)   │              │
│            └─────────────────┘              │
└─────────────────────────────────────────────┘

The iii engine reads a config.yaml file that declares which modules to load and how to configure them. It then starts and manages your Motia application through the ExecModule.

The iii development console gives you full visibility into the running engine — modules, functions, triggers, streams, and workers:

Configuration overview in the iii Console

config.yaml

The config.yaml file is the single source of truth for all infrastructure configuration. It replaces the old motia.config.ts plugin system — no more JavaScript configuration for infrastructure concerns.

workers:
  - name: iii-http
    config:
      port: 3111
      host: 0.0.0.0
 
  - name: iii-queue
    config:
      adapter:
        name: builtin
 
  - name: iii-state
    config:
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/state_store.db
 
  - name: iii-exec
    config:
      watch:
        - steps/**/*.ts
        - motia.config.ts
      exec:
        - npx motia dev

Core Modules

REST API Module

Serves HTTP endpoints defined by your Step triggers. Configures port, host, CORS, timeouts, and concurrency limits.

- name: iii-http
  config:
    port: 3111
    host: 0.0.0.0
    default_timeout: 30000
    concurrency_request_limit: 1024
    cors:
      allowed_origins:
        - http://localhost:3000
      allowed_methods:
        - GET
        - POST
        - PUT
        - DELETE
        - OPTIONS

Queue Module

Manages message queues for async Step-to-Step communication via enqueue(). Supports built-in, Redis, and RabbitMQ adapters.

- name: iii-queue
  config:
    adapter:
      name: builtin
      # For Redis:
      #   name: redis
      #   config: { redis_url: "redis://localhost:6379" }
      # For RabbitMQ:
      #   name: rabbitmq
      #   config: { amqp_url: "amqp://localhost:5672" }

State Module

Key-value state storage grouped by namespace. Supports file-based, in-memory, and Redis adapters.

- name: iii-state
  config:
    adapter:
      name: kv
      config:
        store_method: file_based
        file_path: ./data/state_store.db

Stream Module

Manages real-time data streams with WebSocket support. Supports KvStore and Redis adapters.

- name: iii-stream
  config:
    port: 3112
    host: 0.0.0.0
    adapter:
      name: kv
      config:
        store_method: file_based
        file_path: ./data/stream_store

Cron Module

Schedules and executes cron-based triggers.

- name: iii-cron
  config:
    adapter:
      name: kv

PubSub Module

Internal publish/subscribe messaging between engine components.

- name: iii-pubsub
  config:
    adapter:
      name: local
      # For Redis:
      #   name: redis
      #   config: { redis_url: "redis://localhost:6379" }

OpenTelemetry Module

Distributed traces, metrics, and structured logs for observability.

- name: iii-observability
  config:
    enabled: true
    service_name: my-service
    service_version: 0.1.0
    exporter: memory
    sampling_ratio: 1.0
    metrics_enabled: true
    metrics_exporter: memory
    logs_enabled: true
    logs_exporter: memory
    logs_max_count: 1000

Exec Module

Manages the lifecycle of your Motia SDK process. Watches files for changes and restarts on hot-reload.

- name: iii-exec
  config:
    watch:
      - steps/**/*.ts
      - motia.config.ts
    exec:
      - npx motia dev

The exec array lists the commands to run your SDK process. The watch array lists glob patterns — when matching files change, iii restarts the process automatically.

Adapter Swapping

Every module that manages data (queues, state, streams, cron, pubsub) supports multiple adapters. This lets you use lightweight local adapters during development and swap to production-grade infrastructure without changing your application code.

Module	Local Adapter	Production Adapter
Queue	`BuiltinQueueAdapter`	`RedisAdapter`, `RabbitMQAdapter`
State	`KvStore` (file_based)	`RedisAdapter`
Stream	`KvStore` (file_based)	`RedisAdapter`
Cron	`KvCronAdapter`	`RedisCronAdapter`
PubSub	`LocalAdapter`	`RedisAdapter`

To swap adapters, change the name field in config.yaml — no application code changes needed.

Environment Variable Interpolation

Use ${VAR:default} syntax in config.yaml for environment-specific values:

- name: iii-http
  config:
    port: ${API_PORT:3111}
    host: ${API_HOST:0.0.0.0}

Multi-Runtime Projects

For projects that use both Node.js and Python, configure separate ExecModule entries:

workers:
  - name: iii-exec
    config:
      watch:
        - steps/**/*.ts
      exec:
        - npx motia dev
 
  - name: iii-exec
    config:
      watch:
        - steps/**/*.py
      exec:
        - uv run motia dev --dir steps

Each runtime runs as an independent process managed by iii. Python developers do not need Node.js installed, and vice versa.

Running iii

Start the iii engine with:

iii -c config.yaml

This starts all configured modules and the Motia SDK process. iii handles hot-reloading, process management, and infrastructure lifecycle automatically.