Installation

This guide covers installing the Motia CLI and iii engine, the two core components needed to build Motia applications.

Overview

Motia consists of:

Motia CLI - Project scaffolding and development tools
iii Engine - Rust-based runtime for HTTP, queues, cron, streams, and observability

The CLI automatically installs the iii engine when you create your first project, but you can also install them separately.

System Requirements

Required

Node.js 18+ (for TypeScript/JavaScript)
macOS, Linux, or WSL2 (Windows via WSL)
curl or Homebrew

Optional

Python 3.10+ (for Python Steps)
Redis 6+ (for queues and streams)
Docker (for containerized deployments)

Installing Motia CLI

Option 1: Homebrew (Recommended for macOS)

Add Motia tap

brew tap MotiaDev/tap

Install CLI

brew install motia-cli

Verify installation

motia-cli --version

Option 2: Shell Script (Linux/macOS/WSL)

The shell script automatically detects your platform and installs the CLI:

curl -fsSL https://raw.githubusercontent.com/MotiaDev/motia-cli/main/install.sh | sh

The installer places the CLI in /usr/local/bin by default. You may need sudo permissions.

Option 3: Manual Download

Download the latest release for your platform:

macOS (ARM)
macOS (Intel)
Linux (x64)

curl -L https://github.com/MotiaDev/motia-cli/releases/latest/download/motia-cli-macos-arm64 -o motia-cli
chmod +x motia-cli
sudo mv motia-cli /usr/local/bin/

curl -L https://github.com/MotiaDev/motia-cli/releases/latest/download/motia-cli-macos-x64 -o motia-cli
chmod +x motia-cli
sudo mv motia-cli /usr/local/bin/

curl -L https://github.com/MotiaDev/motia-cli/releases/latest/download/motia-cli-linux-x64 -o motia-cli
chmod +x motia-cli
sudo mv motia-cli /usr/local/bin/

Installing iii Engine

The iii engine is automatically installed when you run motia-cli create, but you can also install it separately:

Automatic Installation (Recommended)

The iii engine will be installed automatically when you create your first project:

motia-cli create my-app
# iii engine automatically installed during setup

Manual Installation

If you need to install the iii engine separately:

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

Custom Install Directory
Specific Version

curl -fsSL https://install.iii.dev/iii/main/install.sh | BIN_DIR=$HOME/.local/bin sh

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh -s -- v0.6.3

Verify iii Engine Installation

command -v iii && iii --version

Expected output:

/usr/local/bin/iii
iii v0.6.3

Installing Motia Packages

Depending on your language choice, install the appropriate Motia package:

TypeScript/JavaScript
Python

npm install motia

The package includes:

Type definitions for Steps
iii-sdk for engine communication
Build tools and CLI

pip

pip install motia

Or with optional OpenTelemetry support:

pip install motia[otel]

For development:

pip install motia[dev]

Installing Redis (Optional)

Redis is required for queue and stream features. If you don’t need these features, you can skip this step.

Docker (Recommended)
Homebrew (macOS)
apt (Ubuntu/Debian)
Cloud Hosted

docker run -d -p 6379:6379 --name motia-redis redis:latest

brew install redis
brew services start redis

sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server

Use a managed Redis service:

Update your iii-config.yaml with the connection URL.

Verify Redis Connection

redis-cli ping

Expected output: PONG

Creating Your First Project

Now that everything is installed, create your first Motia project:

motia-cli create my-first-app

The CLI will prompt you to:

Choose a language

Select TypeScript, JavaScript, or Python

Pick a template

Options:

Basic - Minimal starter with one Step
Todo App - Complete CRUD example
Custom - Empty project

Install dependencies

The CLI automatically installs package dependencies

Project Structure

After creation, your project will have this structure:

my-first-app/
├── steps/                    # Your Step files
│   ├── hello-api.step.ts    # Example HTTP Step
│   └── process-hello.step.ts # Example Queue Step
├── iii-config.yaml          # iii engine configuration
├── package.json             # Dependencies (Node.js)
├── tsconfig.json            # TypeScript config (if using TS)
├── .env                     # Environment variables
├── .gitignore
└── README.md

For Python projects:

my-first-app/
├── steps/
│   └── hello_api_step.py
├── iii-config.yaml
├── pyproject.toml          # Python dependencies
├── .env
└── README.md

Configuration Files

iii-config.yaml

The iii-config.yaml file configures the iii engine:

iii-config.yaml

modules:
  # HTTP API module
  - class: modules::api::RestApiModule
    config:
      host: 127.0.0.1
      port: 3111
  
  # Queue module (requires Redis)
  - class: modules::queue::QueueModule
    config:
      redis_url: ${REDIS_URL:redis://localhost:6379}
  
  # Cron scheduler
  - class: modules::cron::CronModule
    config:
      redis_url: ${REDIS_URL:redis://localhost:6379}
  
  # Real-time streams (requires Redis)
  - class: modules::stream::StreamModule
    config:
      redis_url: ${REDIS_URL:redis://localhost:6379}
      port: 3112
  
  # Observability (logging, traces, metrics)
  - class: modules::observability::OtelModule
    config:
      enabled: true
      level: info
      format: default

Environment variables use the syntax ${VAR_NAME:default_value}. Set REDIS_URL in your .env file to override defaults.

Environment Variables

Create a .env file for local development:

.env

# Redis connection
REDIS_URL=redis://localhost:6379

# Application settings
NODE_ENV=development
LOG_LEVEL=info

# Custom environment variables
GREETING_PREFIX=Hello

Running Your Project

Navigate to project directory

cd my-first-app

Start the iii engine

iii -c iii-config.yaml

Access your app

HTTP API: http://localhost:3111
Stream API: http://localhost:3112
iii Console: http://localhost:3112/console
Metrics: http://localhost:9464/metrics

Docker Installation (Production)

For production deployments, use Docker:

docker-compose.yml

version: '3.8'

services:
  iii:
    image: iiidev/iii:latest
    ports:
      - '3111:3111'  # HTTP API
      - '49134:49134'  # WebSocket
      - '3112:3112'  # Stream API
      - '9464:9464'  # Metrics
    volumes:
      - ./iii-config.yaml:/app/config.yaml:ro
    environment:
      - REDIS_URL=redis://redis:6379
    depends_on:
      - redis
  
  redis:
    image: redis:7-alpine
    ports:
      - '6379:6379'
    volumes:
      - redis-data:/data

volumes:
  redis-data:

Start the stack:

docker compose up -d

Updating Motia

Motia CLI
iii Engine
Motia Package

Homebrew

brew upgrade motia-cli

Shell Script

curl -fsSL https://raw.githubusercontent.com/MotiaDev/motia-cli/main/install.sh | sh

curl -fsSL https://install.iii.dev/iii/main/install.sh | sh

Node.js

npm update motia

Python

pip install --upgrade motia

Troubleshooting

CLI command not found

Ensure /usr/local/bin is in your PATH:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Or for zsh:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Permission denied during installation

You may need sudo permissions:

curl -fsSL https://raw.githubusercontent.com/MotiaDev/motia-cli/main/install.sh | sudo sh

iii engine fails to start

Check if ports are available:

lsof -i :3111  # HTTP port
lsof -i :49134  # WebSocket port

Kill conflicting processes or change ports in iii-config.yaml.

Redis connection failed

Verify Redis is running:

redis-cli ping

If not using Redis, disable queue/stream modules in iii-config.yaml.

Python import errors

Ensure you’re using Python 3.10+:

python --version

Reinstall Motia in a virtual environment:

python -m venv venv
source venv/bin/activate
pip install motia

Next Steps

Quickstart

Build your first Motia app in 5 minutes

Your First Step

Learn how to create Steps

Configuration

Configure iii engine and modules

Examples

View 20+ production examples

Uninstalling

Homebrew
Manual

brew uninstall motia-cli
brew untap MotiaDev/tap

sudo rm /usr/local/bin/motia-cli
sudo rm /usr/local/bin/iii

Getting Started

Core Concepts

Triggers

Features

Deployment

Guides

​Overview

​System Requirements

Required

Optional

​Installing Motia CLI

​Option 1: Homebrew (Recommended for macOS)

​Option 2: Shell Script (Linux/macOS/WSL)

​Option 3: Manual Download

​Installing iii Engine

​Automatic Installation (Recommended)

​Manual Installation

​Verify iii Engine Installation

​Installing Motia Packages

​Installing Redis (Optional)

​Verify Redis Connection

​Creating Your First Project

​Project Structure

​Configuration Files

​iii-config.yaml

​Environment Variables

​Running Your Project

​Docker Installation (Production)

​docker-compose.yml

​Updating Motia

​Homebrew

​Shell Script

​Node.js

​Python

​Troubleshooting

​Next Steps

Quickstart

Your First Step

Configuration

Examples

​Uninstalling

Build docs developers (and LLMs) love

Overview

System Requirements

Installing Motia CLI

Option 1: Homebrew (Recommended for macOS)

Option 2: Shell Script (Linux/macOS/WSL)

Option 3: Manual Download

Installing iii Engine

Automatic Installation (Recommended)

Manual Installation

Verify iii Engine Installation

Installing Motia Packages

Installing Redis (Optional)

Verify Redis Connection

Creating Your First Project

Project Structure

Configuration Files

iii-config.yaml

Environment Variables

Running Your Project

Docker Installation (Production)

docker-compose.yml

Updating Motia

Homebrew

Shell Script

Node.js

Python

Troubleshooting

Next Steps

Uninstalling