Skip to main content

​
Installation

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

​
Prerequisites

  • Node.js 18+ — Required for TypeScript and JavaScript Steps
  • npm, yarn, or pnpm — Package manager of your choice

​
Install the Motia CLI

The Motia CLI helps you create new projects and manage your Motia applications. 
brew tap MotiaDev/tap
brew install motia-cli
Verify the installation: 
motia-cli --version

​
Install the iii engine

The iii engine is the Rust-based runtime that powers Motia. It manages queues, state, streams, cron, and observability.
The Motia CLI will automatically install the iii engine when you create a new project if it’s not already installed.
To install manually: 
brew tap iii-dev/tap
brew install iii
Verify the installation: 
iii --version

​
Install Motia packages

After creating a project with motia-cli create, you’ll need to install the Motia SDK packages. 
npm install motia

​
Optional: Stream client packages

For client-side streaming (browser or Node.js):
npm install @motiadev/stream-client-browser

​
Create your first project

Now that you have the CLI and iii engine installed, create your first project: 
motia-cli create my-app
cd my-app
The CLI will:
  1. Prompt you to choose a language (TypeScript, JavaScript, or Python)
  2. Prompt you to select a template (basic, api, or full-stack)
  3. Generate project files and configuration
  4. Install dependencies
  5. Create an iii-config.yaml configuration file

​
Start the iii engine

Start the iii engine to run your Motia application: 
iii -c iii-config.yaml
The iii engine will:
  • Start the HTTP server (default: http://localhost:3111)
  • Start the WebSocket server for streams (default: ws://localhost:3112)
  • Start the iii Console (default: http://localhost:3113)
  • Auto-discover and register your Steps
  • Set up queues, state, and observability
Visit the iii Console at http://localhost:3113 to monitor your application, view traces, and debug issues.

​
Development workflow

For development with hot reloading:
# Terminal 1: Start iii engine
iii -c iii-config.yaml

# Terminal 2: Watch TypeScript files
npm run dev
# or
motia dev
The motia dev command will:
  • Watch your Step files for changes
  • Rebuild automatically with esbuild
  • The iii engine will hot-reload your Steps

​
Verify installation

Test that everything is working: 
curl http://localhost:3111/health
You should see a health check response from the iii engine.

​
Troubleshooting

If the iii engine is not found, try:
  1. Install it manually: 
    brew install iii-dev/tap/iii
# or
curl -fsSL https://iii.dev/install.sh | sh
  2. Add it to your PATH: 
    export PATH="$HOME/.iii/bin:$PATH"
If ports 3111, 3112, or 3113 are already in use, you can change them in iii-config.yaml:
modules:
  - class: modules::api::RestApiModule
    config:
      port: 3111  # Change this

  - class: modules::stream::StreamModule
    config:
      port: 3112  # Change this
Motia requires Node.js 18 or higher. Update Node.js:
# Using nvm
nvm install 18
nvm use 18

# Or download from https://nodejs.org
Motia requires Python 3.10 or higher. Update Python:
# Using pyenv
pyenv install 3.12
pyenv global 3.12

# Or download from https://python.org

​
Next steps

Quickstart

Build your first Motia app in under 60 seconds

Core concepts

Learn about Steps, triggers, and handlers

Configuration

Configure the iii engine for your needs

Examples

Explore real-world examples

Build docs developers (and LLMs) love

Get started for freeTalk to us