Installation

Prerequisites

Before installing MoFA, ensure you have the following:

Rust toolchain

Rust 1.85 or newer (edition 2024)

Git

For cloning the repository

LLM API key

OpenAI, Anthropic, or other provider

Build tools

C compiler and linker (platform-specific)

Install Rust

MoFA requires Rust 1.85 or newer. If you don’t have Rust installed:

Linux / macOS
Windows
macOS (Homebrew)

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable

Add Cargo to your PATH (usually automatic):

source $HOME/.cargo/env

brew install rustup
rustup-init
rustup default stable

Verify installation

rustc --version   # Should show 1.85.0 or newer
cargo --version

If the version is below 1.85, update Rust:

rustup update stable

Get MoFA source

MoFA is currently distributed via source code:

git clone https://github.com/mofa-org/mofa.git
cd mofa

Note: A crates.io package (mofa-sdk) is available, but we recommend using the latest source during active development.

Build MoFA

Build the workspace

Build all crates in release mode for optimal performance:

cargo build --release

This compiles:

mofa-kernel - Microkernel core
mofa-foundation - Business logic layer
mofa-runtime - Agent lifecycle management
mofa-plugins - Plugin system
mofa-sdk - Main SDK
mofa-cli - Command-line tools

First build may take 5-10 minutes as Cargo downloads and compiles dependencies.

Run tests

Verify everything works:

cargo test -p mofa-sdk
cargo test -p mofa-kernel

All tests should pass. If you see failures, check your Rust version and system configuration.

Build specific features

MoFA has optional features you can enable:

# Build with PostgreSQL persistence
cargo build --features persistence-postgres

# Build with Dora-rs distributed runtime
cargo build --features dora

# Build with monitoring dashboard
cargo build --features monitoring

# Build with all features
cargo build --all-features

Platform-specific setup

Linux
macOS
Windows

Install build dependencies:

sudo apt update
sudo apt install build-essential pkg-config libssl-dev

Optional: PostgreSQL

If using persistence features:

# Ubuntu/Debian
sudo apt install postgresql postgresql-contrib libpq-dev

# Fedora/RHEL
sudo dnf install postgresql postgresql-server postgresql-devel

Install Xcode Command Line Tools:

xcode-select --install

Optional: PostgreSQL

brew install postgresql@14
brew services start postgresql@14

Optional: Ollama (for local LLMs)

brew install ollama
ollama serve

Install Visual Studio Build Tools:

Download Build Tools for Visual Studio
Run the installer
Select “Desktop development with C++”
Install

Optional: PostgreSQL

Download and install from PostgreSQL Downloads

Path configuration

Ensure %USERPROFILE%\.cargo\bin is in your PATH:

$env:Path += ";$env:USERPROFILE\.cargo\bin"

Configure LLM provider

MoFA supports multiple LLM providers. Choose one and set up credentials:

OpenAI
Anthropic
Ollama (Local)
OpenRouter

Get an API key from OpenAICreate .env in your project root:

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o           # Optional, default: gpt-4o

Or set environment variables:

export OPENAI_API_KEY=sk-...
export OPENAI_MODEL=gpt-4o

Get an API key from AnthropicCreate .env:

ANTHROPIC_API_KEY=sk-ant-...
ANTHROPIC_MODEL=claude-sonnet-4-5-latest   # Optional

Or set environment variables:

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_MODEL=claude-sonnet-4-5-latest

Install and run Ollama:

# macOS
brew install ollama
ollama serve

# Linux
curl -fsSL https://ollama.com/install.sh | sh
ollama serve

Pull a model:

ollama pull llama3.2

Configure .env:

OPENAI_API_KEY=ollama          # Any value works
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_MODEL=llama3.2

Get an API key from OpenRouterConfigure .env:

OPENAI_API_KEY=<your_openrouter_key>
OPENAI_BASE_URL=https://openrouter.ai/api/v1
OPENAI_MODEL=google/gemini-2.0-flash-001  # Or any other model

OpenRouter gives access to:

Google Gemini
Anthropic Claude
Meta Llama
Many other models

Optional: Database setup

If you’re using persistence features, set up a database:

PostgreSQL
MySQL
SQLite

Install PostgreSQL (see platform-specific instructions above)Create a database:

psql -U postgres
CREATE DATABASE mofa_dev;
CREATE USER mofa WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE mofa_dev TO mofa;
\q

Configure .env:

DATABASE_URL=postgres://mofa:your_password@localhost/mofa_dev

Build with PostgreSQL feature:

cargo build --features persistence-postgres

Install MySQL, then:

CREATE DATABASE mofa_dev;
CREATE USER 'mofa'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON mofa_dev.* TO 'mofa'@'localhost';
FLUSH PRIVILEGES;

Configure .env:

DATABASE_URL=mysql://mofa:your_password@localhost/mofa_dev

Build with MySQL feature:

cargo build --features persistence-mysql

No installation needed! SQLite is embedded.Configure .env:

DATABASE_URL=sqlite:./mofa.db

Build with SQLite feature:

cargo build --features persistence-sqlite

SQLite is perfect for development and small deployments.

IDE setup

VS Code
RustRover / IntelliJ
Neovim / Vim

Install recommended extensions:

rust-analyzer - Rust language server
CodeLLDB - Debugger
crates - Dependency management

Open the workspace:

code mofa

rust-analyzer will automatically detect Cargo.toml and provide IntelliSense.

Install RustRover or IntelliJ IDEA with Rust plugin
Open the mofa directory
Let the IDE index the project

The IDE will automatically configure build targets and dependencies.

Use a Rust LSP setup:

" With vim-plug
Plug 'neovim/nvim-lspconfig'
Plug 'simrat39/rust-tools.nvim'

" Configure rust-analyzer
lua << EOF
require('rust-tools').setup({})
EOF

Or use AstroNvim with Rust support.

Verify installation

Run a simple example to confirm everything works:

cd examples
cargo run -p chat_stream

You should see:

========================================
  MoFA LLM Agent
========================================

Agent loaded: LLM Agent

If you see this output, your installation is complete!

Troubleshooting

Error: could not find 'Cargo.toml'

Make sure you’re in the mofa directory:

cd mofa
cargo build

Error: linking with 'cc' failed

Install C compiler and build tools (see platform-specific setup above).Linux: sudo apt install build-essentialmacOS: xcode-select --installWindows: Install Visual Studio Build Tools

Error: OpenSSL not found

Install OpenSSL development libraries:

# Ubuntu/Debian
sudo apt install libssl-dev

# Fedora/RHEL
sudo dnf install openssl-devel

# macOS
brew install openssl

Error: OPENAI_API_KEY not found

Set your API key:

export OPENAI_API_KEY=sk-...

Or create a .env file:

echo "OPENAI_API_KEY=sk-..." > .env

Rust version too old

Update Rust to 1.85 or newer:

rustup update stable
rustup default stable
rustc --version  # Should show 1.85+

Feature flags reference

MoFA uses Cargo features for optional functionality:

Feature	Description
`default`	Core functionality only
`dora`	Enable Dora-rs distributed runtime
`persistence-postgres`	PostgreSQL database backend
`persistence-mysql`	MySQL database backend
`persistence-sqlite`	SQLite database backend
`monitoring`	Built-in monitoring dashboard
`uniffi`	Multi-language bindings (Python, Java, Swift, Kotlin, Go)
`openai`	OpenAI provider (enabled by default)
`kokoro`	Kokoro TTS engine

Enable features when building:

cargo build --features "dora,persistence-postgres,monitoring"

Or in your Cargo.toml:

[dependencies]
mofa-sdk = { version = "0.1", features = ["dora", "persistence-postgres"] }

Next steps

Quick start

Build your first agent in under 10 minutes

Architecture

Learn about MoFA’s microkernel design

Examples

Explore 27+ working examples

API docs

Browse the Rust API reference

Tip: Join our Discord community if you need help with installation or configuration.

Get Started

Core Concepts

Building Agents

Plugin Development

Multi-Agent Systems

Advanced Features

Language Bindings

Installation

Prerequisites

Rust toolchain

Git

LLM API key

Build tools

Install Rust

Verify installation

Get MoFA source

Build MoFA

Platform-specific setup

Optional: PostgreSQL

Optional: PostgreSQL

Optional: Ollama (for local LLMs)

Optional: PostgreSQL

Path configuration

Configure LLM provider

Optional: Database setup

IDE setup

Verify installation

Troubleshooting

Feature flags reference

Next steps

Quick start

Architecture

Examples

API docs

Build docs developers (and LLMs) love

Get Started

Core Concepts

Building Agents

Plugin Development

Multi-Agent Systems

Advanced Features

Language Bindings

​Prerequisites

Rust toolchain

Git

LLM API key

Build tools

​Install Rust

​Verify installation

​Get MoFA source

​Build MoFA

​Platform-specific setup

​Optional: PostgreSQL

​Optional: PostgreSQL

​Optional: Ollama (for local LLMs)

​Optional: PostgreSQL

​Path configuration

​Configure LLM provider

​Optional: Database setup

​IDE setup

​Verify installation

​Troubleshooting

​Feature flags reference

​Next steps

Quick start

Architecture

Examples

API docs

Build docs developers (and LLMs) love

Prerequisites

Install Rust

Verify installation

Get MoFA source

Build MoFA

Platform-specific setup

Optional: PostgreSQL

Optional: PostgreSQL

Optional: Ollama (for local LLMs)

Optional: PostgreSQL

Path configuration

Configure LLM provider

Optional: Database setup

IDE setup

Verify installation

Troubleshooting

Feature flags reference

Next steps