Configuration (config.yaml)

Motia projects run on iii, which uses a config.yaml file for its modular runtime configuration. When you scaffold a project with npx motia@latest create, this file is generated for you with sensible defaults.

The config.yaml is an iii configuration file. Most modules (API, queue, state, streams, cron, observability) are iii infrastructure concerns. Visit iii.dev/docs for the full module reference.

Project Setup

Your package.json must have "type": "module" and use iii as the dev command:

package.json

{
  "name": "my-app",
  "type": "module",
  "scripts": {
    "dev": "iii",
    "build": "motia build"
  },
  "dependencies": {
    "motia": "next"
  }
}

Running npm run dev starts the iii runtime, which reads config.yaml and boots all configured modules -- including the Motia application via the Shell Exec module.

Motia-Specific Configuration

The portion of config.yaml specific to Motia is the Shell Exec module, which tells iii how to build and run your Motia application:

config.yaml (Motia portion)

  - name: iii-exec
    config:
      watch:
        - steps/**/*.ts
      exec:
        - npx motia dev
        - node dist/index-dev.js

watch -- glob patterns for files to watch. When these change, the exec commands are re-run.
exec -- commands to execute in order. npx motia dev builds your Steps, and node dist/index-dev.js runs the bundled output.

Full Development Config

A complete config.yaml for local development. The iii infrastructure modules use file-based storage by default:

config.yaml

workers:
  - name: iii-stream
    config:
      port: ${STREAM_PORT:3112}
      host: 127.0.0.1
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/stream_store
 
  - name: iii-state
    config:
      adapter:
        name: kv
        config:
          store_method: file_based
          file_path: ./data/state_store.db
 
  - name: iii-http
    config:
      port: 3111
      host: 127.0.0.1
      default_timeout: 30000
      concurrency_request_limit: 1024
      cors:
        allowed_origins:
          - http://localhost:3000
          - http://localhost:5173
          - http://localhost:3113
        allowed_methods:
          - GET
          - POST
          - PUT
          - DELETE
          - OPTIONS
 
  - name: iii-queue
    config:
      adapter:
        name: builtin
        config:
          store_method: file_based
          file_path: ./data/queue_store
 
  - name: iii-pubsub
    config:
      adapter:
        name: local
 
  - name: iii-cron
    config:
      adapter:
        name: kv
 
  - name: iii-observability
    config:
      enabled: ${OTEL_ENABLED:true}
      service_name: ${OTEL_SERVICE_NAME:iii-engine}
      exporter: ${OTEL_EXPORTER_TYPE:memory}
 
  - name: iii-exec
    config:
      watch:
        - steps/**/*.ts
      exec:
        - npx motia dev
        - node dist/index-dev.js

All config values support environment variable interpolation: ${VARIABLE_NAME:default_value}. If the variable is not set, the default after : is used.

For production configuration with Redis adapters and OTLP exporters, see the Deployment Guide and iii.dev/docs.

Configuration (config.yaml)

Project Setup

Motia-Specific Configuration

Full Development Config

What's Next?

Streams

State Management

On this page