Mule

Mule is an AI workflow platform that enables users to create, configure, and execute complex AI-powered workflows. It combines the power of AI agents, custom tools, and WebAssembly modules to create flexible and extensible automation pipelines.

Quick Start with Docker

The easiest way to get started is using Docker Compose:

# Clone the repository
git clone https://github.com/mule-ai/mule.git
cd mule

# Start the services
docker-compose up -d

# Check the services are running
docker-compose ps

# Access the application
# Web UI: http://localhost:8080
# API: http://localhost:8080/v1
# Health check: http://localhost:8080/health

The Docker Compose setup includes:

• Mule API Server: The main application on port 8080
• PostgreSQL Database: Configured with the Mule database schema on port 5432

Docker Development

# Build the Docker image
docker build -t mule:latest .

# Run with custom database connection
docker run -p 8080:8080 \
  mule:latest -db "postgres://user:pass@host:5432/dbname?sslmode=disable"

# View logs
docker-compose logs -f mule
docker-compose logs -f postgres

Manual Installation

Prerequisites

• Go 1.26 or later
• PostgreSQL 12 or later
• Node.js 18+ (for frontend development)

Database Setup

1. Create a PostgreSQL database:

CREATE DATABASE mule;
CREATE USER mule WITH PASSWORD 'mule';
GRANT ALL PRIVILEGES ON DATABASE mule TO mule;

2. (Optional) Apply migrations manually — or just start the server, which applies pending embedded migrations at startup:

psql -h localhost -U mule -d mule -f internal/database/migrations/0001_initial_schema.sql

Building and Running

# Install dependencies
go mod tidy

# Build the application
make build

# Run the server
./cmd/api/bin/mule -db "postgres://mule:mule@localhost:5432/mule?sslmode=disable"

# Or use the Makefile
make run

Documentation

• Product Requirements Document - Complete specification of Mule
• Data Model Diagram - Entity relationship diagram showing database schema
• Sequence Diagram - Workflow execution flow and component interactions
• Software Architecture - High-level system architecture
• Primitives Relationship - How core primitives relate to each other
• Component Interaction - Detailed component interaction diagram
• Database Migrations - Database schema migration guide
• Skill System - Documentation for the pi agent skills system

Overview

Mule consists of a few core primitives:

• AI providers - connections to models, supporting OpenAI-compliant APIs
• Skills - pi agent skills that can be assigned to agents for specialized capabilities
• WASM modules - imperative code execution using the wazero library
• Agents - AI agents powered by pi RPC runtime with configurable skills
• Workflow Steps - either a call to an Agent or execution of a WASM module
• Workflows - ordered execution of workflow steps

Technology Stack

• Backend: Go programming language with pi RPC agent runtime and wazero
• Frontend: React UI compiled into the Go binary with light/dark mode support
• Database: PostgreSQL for configuration storage and job queuing
• API: OpenAI-compatible API as the main interface to workflows
• Containerization: Multi-stage Docker builds with an alpine final stage

Key Features

• Fully static React frontend compiled into Go binary
• Workflow builder with drag-and-drop interface
• Per-step and full workflow execution with real-time output streaming
• Background job processing with configurable worker pools
• Synchronous and asynchronous execution modes
• Light and dark UI modes
• Docker support with multi-stage builds for minimal container size
• Health checks and graceful shutdown
• Built-in tools via pi including filesystem, bash command execution, and more
• Agent skills system for specialized capabilities
• WebSocket support for real-time updates

API Endpoints

Core API

• GET /health - Health check endpoint
• GET /v1/models - List available AI models (agents and workflows)
• POST /v1/chat/completions - OpenAI-compatible chat completions

Skills API

• GET /api/v1/skills - List all skills
• POST /api/v1/skills - Create a new skill
• GET /api/v1/skills/{id} - Get a skill by ID
• PUT /api/v1/skills/{id} - Update a skill
• DELETE /api/v1/skills/{id} - Delete a skill

Agent Skills API

• GET /api/v1/agents/{id}/skills - Get skills assigned to an agent
• PUT /api/v1/agents/{id}/skills - Assign skills to an agent
• DELETE /api/v1/agents/{id}/skills/{skillId} - Remove a skill from an agent

Management API

• GET/POST/PUT/DELETE /api/v1/providers - AI provider management
• GET /api/v1/providers/{id}/models - List models from a provider
• GET/POST/PUT/DELETE /api/v1/agents - Agent management
• GET/POST/PUT/DELETE /api/v1/workflows - Workflow management
• GET /api/v1/workflows/{id}/steps - List workflow steps
• POST /api/v1/workflows/{id}/steps - Create workflow step
• POST /api/v1/workflows/{id}/steps/reorder - Reorder workflow steps
• PUT /api/v1/workflows/{workflow_id}/steps/{step_id} - Update workflow step
• DELETE /api/v1/workflows/{workflow_id}/steps/{step_id} - Delete workflow step
• GET/POST /api/v1/jobs - List or create jobs
• GET /api/v1/jobs/{id} - Job details
• DELETE /api/v1/jobs/{id} - Cancel a job
• GET /api/v1/jobs/{id}/steps - Job step details

Agent Tools API

• GET /api/v1/agents/{id}/tools - Get tools assigned to an agent
• POST /api/v1/agents/{id}/tools - Assign tools to an agent
• DELETE /api/v1/agents/{id}/tools/{toolId} - Remove a tool from an agent

Tools API

• GET/POST/PUT/DELETE /api/v1/tools - Tool management

Configuration API

• GET /api/v1/memory-config - Get memory configuration
• PUT /api/v1/memory-config - Update memory configuration
• GET /api/v1/settings - List all settings
• GET/PUT /api/v1/settings/{key} - Get or update a specific setting

WASM Module API

• GET/POST /api/v1/wasm-modules - List and create WASM modules
• POST /api/v1/wasm-modules/compile - Compile Go code to WASM
• POST /api/v1/wasm-modules/test - Test a WASM module
• GET /api/v1/wasm-modules/example - Get example WASM Go code
• GET/PUT/DELETE /api/v1/wasm-modules/{id} - WASM module CRUD
• GET/PUT /api/v1/wasm-modules/{id}/source - Get or update WASM module source code

Real-time

• WS /ws - WebSocket endpoint for real-time job updates

Configuration

The application can be configured via command-line flags:

./mule -db "postgres://user:pass@host:5432/dbname?sslmode=disable" -listen ":8080"

• -db: PostgreSQL connection string (default: postgres://user:pass@localhost:5432/mule?sslmode=disable)
• -listen: HTTP listen address (default: :8080)

Environment variables:

• MULE_ENCRYPTION_SECRET: 16/24/32-byte secret used to encrypt provider API keys (AES-GCM). Set it in any real deployment; without it the server warns and falls back to a built-in default that provides no real secrecy.

Development

Frontend Development

cd frontend
npm install
npm run dev

Testing

# Run all tests
make test

# Run linting
make lint

# Run with hot reload
make air

Building

# Build for production
make build

# Build Docker image
docker build -t mule:latest .

For detailed technical specifications, see the Product Requirements Document.