RustForge

Local AI Agent Orchestrator - Ultra-fast, privacy-focused agent workflow execution built in Rust.

Overview

RustForge is a high-performance orchestration engine for AI agent workflows. Define multi-agent workflows in YAML, execute them locally with full control over your data, and leverage powerful features like variable interpolation, checkpointing, and real-time event streaming.

Current Status: Phase 5 - UI Layer ✅

Phase 5 adds a modern web UI built with Svelte 5, featuring visual workflow builder, real-time execution monitoring, and comprehensive workflow management.

Features

Core Foundation (Phase 1)

YAML-based Workflow Definitions - Simple, declarative workflow syntax
Sequential Execution Engine - Reliable step-by-step agent orchestration
Variable Interpolation - Dynamic context passing between agents with {agent_id.output} syntax
State Persistence - Embedded redb database for execution history and checkpoints
Event Bus - Real-time workflow execution events
Flexible Configuration - Multi-layer config system (defaults → user → project → env vars)
CLI Interface - Intuitive commands for workflow management

LLM + Agent Layer (Phase 2)

Ollama Integration - Local LLM support for privacy-focused execution
OpenAI Fallback - Automatic cloud fallback when local LLM unavailable
Agent System - BaseAgent with LLM provider integration
Memory Store - Conversation history persistence with redb
Real Agent Execution - Workflows now execute with actual LLM calls
Thread-Safe Registries - Concurrent agent and LLM provider management

Tool Layer & Security (Phase 3)

6 Built-in Tools - FileSystem, WebScraper, PDF Parser, Shell Executor, API Client, Clipboard
Tool Registry - Thread-safe tool management and execution
Permission System - Allow/Deny/Prompt policies for tool execution
Process Isolation - Sandboxed subprocess execution with timeout enforcement
Audit Logging - Security event tracking for compliance
Path & Command Validation - Prevent unauthorized access and dangerous operations

API & Execution Patterns (Phase 4)

REST API - Full HTTP API with Axum for workflow and execution management
WebSocket Support - Real-time execution event streaming with bidirectional control
Parallel Execution - Concurrent agent execution with tokio::spawn
Merge Strategies - Concat, Vote, and LLM-based result merging
Timeout & Cancellation - Graceful shutdown with CancellationToken
Unified Executor - Single executor supporting sequential, parallel, and DAG modes
Integration Tests - Comprehensive end-to-end workflow testing

UI Layer (Phase 5) 🆕

Modern Web UI - Built with Svelte 5 and Technical Blueprint aesthetic
Visual Workflow Builder - Drag-and-drop canvas for designing workflows
Real-time Monitoring - Live execution tracking with WebSocket updates
Execution History - Browse and review past workflow runs
Settings Management - Configure API endpoints and preferences
Responsive Design - Clean, intuitive interface with status indicators

Installation

Prerequisites

Rust 1.70+ and Cargo
Git
Ollama (optional, for local LLM) - Install Ollama
OpenAI API Key (optional, for cloud fallback)

Build from Source

# Clone the repository
git clone https://github.com/apus3404-oss/RustForge.git
cd RustForge

# Build release binary
cargo build --release

# Binary will be at target/release/rustforge
./target/release/rustforge --version

Setup LLM Providers

Option 1: Ollama (Local, Recommended)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

# Pull a model
ollama pull llama2

Option 2: OpenAI (Cloud Fallback)

# Set API key
export OPENAI_API_KEY="your-api-key"

Add to PATH (Optional)

# Linux/macOS
export PATH="$PATH:$(pwd)/target/release"

# Or copy to system location
sudo cp target/release/rustforge /usr/local/bin/

Quick Start

1. Start the Backend

# Build and start the API server
cargo build --release
./target/release/rustforge serve --port 3000

The backend will be available at http://localhost:3000

2. Start the UI (Optional)

# Navigate to UI directory
cd ui

# Install dependencies
npm install

# Start development server
npm run dev

The UI will be available at http://localhost:5173

Note: The UI is also served by the backend at http://localhost:3000 when you run rustforge serve.

3. Initialize a Project

rustforge init

This creates:

.rustforge/ - Configuration and state database
workflows/ - Directory for workflow definitions
workflows/example.yaml - Example workflow to get started

2. Create a Workflow

Create workflows/hello.yaml:

name: "Hello Workflow"
mode: sequential
agents:
  - id: greeter
    type: base
    task: "Say hello to the user"
  
  - id: responder
    type: base
    task: "Respond to: {greeter.output}"

3. Run the Workflow

rustforge run workflows/hello.yaml

With inputs:

rustforge run workflows/hello.yaml --inputs '{"user": "Alice"}'

CLI Commands

`rustforge init [PATH]`

Initialize a new RustForge project.

rustforge init              # Initialize in current directory
rustforge init ./my-project # Initialize in specific directory

`rustforge run <WORKFLOW> [OPTIONS]`

Execute a workflow.

rustforge run workflows/my-workflow.yaml
rustforge run workflows/my-workflow.yaml --inputs '{"key": "value"}'
rustforge run workflows/my-workflow.yaml --resume  # Resume from checkpoint

Options:

-i, --inputs <JSON> - Provide workflow inputs as JSON string
-r, --resume - Resume execution from last checkpoint

`rustforge validate <WORKFLOW>`

Validate a workflow definition without executing it.

rustforge validate workflows/my-workflow.yaml

Checks for:

Valid YAML syntax
Required fields (name, mode, agents)
Unique agent IDs
Valid dependency references
Circular dependency detection

`rustforge list`

List all available workflows in the workflows/ directory.

rustforge list

`rustforge config <SUBCOMMAND>`

Manage configuration.

rustforge config show                                    # Show full config
rustforge config get execution.max_parallel_agents       # Get specific value
rustforge config set execution.max_parallel_agents 20    # Set value

Common config keys:

execution.max_parallel_agents - Max concurrent agents (default: 10)
execution.default_timeout - Timeout in seconds (default: 300)
llm.default_provider - Default LLM provider (default: "ollama:llama3")
logging.level - Log level: debug, info, warn, error (default: "info")
ui.port - UI server port (default: 3000)

Workflow Syntax

Basic Structure

name: "Workflow Name"
mode: sequential  # Execution mode (sequential only in Phase 1)

agents:
  - id: agent1           # Unique identifier
    type: base           # Agent type (currently 'base', more types in Phase 3)
    task: "Task description"
    
  - id: agent2
    type: base
    task: "Use output from agent1: {agent1.output}"

Variable Interpolation

Reference outputs from previous agents or workflow inputs:

agents:
  - id: analyzer
    type: base
    task: "Analyze: {input.document}"
  
  - id: summarizer
    type: base
    task: "Summarize: {analyzer.output}"

Variables are resolved at runtime using the execution context.

Parallel Execution (Phase 4)

Execute multiple agents concurrently:

name: "Parallel Analysis"
mode: parallel  # Agents run concurrently

agents:
  - id: analyzer1
    type: base
    task: "Analyze dataset A"
  
  - id: analyzer2
    type: base
    task: "Analyze dataset B"
  
  - id: analyzer3
    type: base
    task: "Analyze dataset C"

Results can be merged using different strategies:

concat: Concatenate all results with newlines
vote: Return most common result
llm_merge: Intelligently synthesize results using LLM

REST API (Phase 4)

RustForge provides a full REST API for workflow management and execution.

Start API Server

rustforge serve --port 8080

API Endpoints

Workflow Management:

POST /api/workflows - Create workflow
GET /api/workflows - List workflows
GET /api/workflows/:id - Get workflow details
DELETE /api/workflows/:id - Delete workflow

Execution:

POST /api/workflows/:id/execute - Execute workflow
GET /api/executions/:id - Get execution status
GET /api/executions - List executions
POST /api/executions/:id/pause - Pause execution
POST /api/executions/:id/resume - Resume execution
DELETE /api/executions/:id - Cancel execution

WebSocket:

WS /api/ws/executions/:id - Real-time execution events

Example: Execute Workflow via API

# Create workflow
curl -X POST http://localhost:8080/api/workflows \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API Test",
    "mode": "parallel",
    "agents": [
      {"id": "agent1", "type": "base", "task": "Task 1"},
      {"id": "agent2", "type": "base", "task": "Task 2"}
    ]
  }'

# Execute workflow
curl -X POST http://localhost:8080/api/workflows/{id}/execute

# Get execution status
curl http://localhost:8080/api/executions/{execution_id}

WebSocket Events

Connect to WebSocket for real-time execution updates:

const ws = new WebSocket('ws://localhost:8080/api/ws/executions/{id}');

ws.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data);
  // Events: TaskStarted, TaskCompleted, TaskFailed
};

// Send control commands
ws.send(JSON.stringify({ type: 'pause' }));
ws.send(JSON.stringify({ type: 'resume' }));
ws.send(JSON.stringify({ type: 'cancel' }));

Web UI

RustForge includes a modern web interface for visual workflow management and monitoring.

Accessing the UI

The UI is automatically served by the backend:

rustforge serve --port 3000

Then open http://localhost:3000 in your browser.

UI Features

Home Dashboard

Quick access to all major features
Action cards for creating workflows, viewing executions, and settings

Visual Workflow Builder

Drag-and-drop agent nodes on canvas
Visual connection editor for dependencies
Real-time workflow validation
Support for Sequential, Parallel, and DAG modes
Export workflows as YAML

Execution Monitor

Real-time event timeline with WebSocket updates
Live status tracking (Running, Completed, Failed, Paused)
Execution controls (Pause, Resume, Cancel)
Detailed event logs with agent outputs and errors
Visual status indicators with color coding

Execution History

Browse past workflow executions
Filter by status and workflow
View detailed execution timelines
Error messages for failed runs

Settings

Configure API base URL
Set WebSocket endpoint
Manage UI preferences

UI Development

For UI development and customization:

cd ui
npm install
npm run dev  # Development server at http://localhost:5173
npm run build  # Production build
npm run preview  # Preview production build

See docs/ui-guide.md for detailed UI documentation, features, and troubleshooting.

Variables are resolved at runtime using the execution context.

Architecture

RustForge uses a layered architecture:

┌─────────────────────────────────────┐
│         CLI Layer (clap)            │  User interface
├─────────────────────────────────────┤
│      Config Layer (TOML/YAML)       │  Configuration management
├─────────────────────────────────────┤
│     Storage Layer (redb)            │  State persistence
├─────────────────────────────────────┤
│   Orchestration Engine (tokio)      │  Workflow execution
│  • Parser  • Validator              │
│  • Executor  • Interpolator         │
│  • Event Bus  • Checkpoints         │
└─────────────────────────────────────┘

Key Components:

Config Layer - Multi-source configuration with priority: env vars → project config → user config → defaults
Storage Layer - Embedded redb database for execution state, checkpoints, and audit logs
Engine Layer - Workflow parsing, validation, variable interpolation, and sequential execution
Event Bus - Real-time event streaming for monitoring and UI integration

For detailed architecture documentation, see docs/specs/design.md.

Configuration

Configuration is loaded from multiple sources with the following priority:

Environment Variables (highest priority)
- RUSTFORGE_DEFAULT_LLM
- RUSTFORGE_MAX_PARALLEL_AGENTS
- RUSTFORGE_LOG_LEVEL
Project Config - .rustforge/config.toml in current directory
User Config - ~/.rustforge/config.toml
Defaults (lowest priority)

Example Configuration

[llm]
default_provider = "ollama:llama3"
fallback_enabled = true

[llm.providers.ollama]
base_url = "http://localhost:11434"
default_model = "llama3"
timeout_secs = 300

[execution]
max_parallel_agents = 10
default_timeout = 300
enable_checkpoints = true
checkpoint_interval = 60

[permissions]
default_policy = "prompt"  # allow, deny, or prompt
audit_log_enabled = true

[logging]
level = "info"
format = "pretty"  # json, pretty, or compact

Development

Run Tests

cargo test

Run with Debug Logging

RUSTFORGE_LOG_LEVEL=debug cargo run -- run workflows/example.yaml

Project Structure

rustforge/
├── src/
│   ├── cli/          # CLI commands and handlers
│   ├── config/       # Configuration types and loader
│   ├── engine/       # Workflow execution engine
│   ├── storage/      # State persistence layer
│   ├── error.rs      # Error types
│   └── main.rs       # Entry point
├── tests/
│   ├── integration/  # Integration tests
│   └── fixtures/     # Test workflows
├── workflows/        # User workflow definitions
└── .rustforge/       # Config and state database

Roadmap

✅ Phase 1: Core Foundation (Completed)
- Config management, CLI, storage, workflow engine
✅ Phase 2: LLM & Agent Layer (Completed)
- Real AI agent implementations with BaseAgent
- LLM provider integrations (Ollama, OpenAI)
- Memory store for conversation history
- Thread-safe registries for agents and providers
✅ Phase 3: Tool & Security Layer (Completed)
- 6 built-in tools (FileSystem, WebScraper, PDF, Shell, API, Clipboard)
- Tool registry and execution framework
- Permission system with allow/deny/prompt policies
- Process isolation for secure subprocess execution
- Audit logging for security events
- Path and command validation
✅ Phase 4: API & Execution Patterns (Completed)
- REST API for workflow execution
- Parallel execution mode
- WebSocket support for real-time events
- Merge strategies and timeout/cancellation
✅ Phase 5: UI Layer (Completed)
- Modern web UI with Svelte 5
- Visual workflow builder
- Real-time execution monitoring
- Execution history and settings management
📋 Phase 6+: Advanced Features (Future)
- Plugin system for custom tools and agents
- Additional LLM providers (Anthropic, Google, etc.)
- Distributed execution across multiple nodes
- Workflow templates library
- Advanced debugging and profiling tools

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Links

Repository: https://github.com/apus3404-oss/RustForge
Documentation: docs/getting-started.md
UI Guide: docs/ui-guide.md
Design Specs: docs/specs/design.md

Name		Name	Last commit message	Last commit date
Latest commit History 92 Commits
.rustforge		.rustforge
dist/ui		dist/ui
docs		docs
src		src
tests		tests
ui		ui
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
Cargo.toml		Cargo.toml
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

RustForge

Overview

Features

Core Foundation (Phase 1)

LLM + Agent Layer (Phase 2)

Tool Layer & Security (Phase 3)

API & Execution Patterns (Phase 4)

UI Layer (Phase 5) 🆕

Installation

Prerequisites

Build from Source

Setup LLM Providers

Add to PATH (Optional)

Quick Start

1. Start the Backend

2. Start the UI (Optional)

3. Initialize a Project

2. Create a Workflow

3. Run the Workflow

CLI Commands

rustforge init [PATH]

rustforge run <WORKFLOW> [OPTIONS]

rustforge validate <WORKFLOW>

rustforge list

rustforge config <SUBCOMMAND>

Workflow Syntax

Basic Structure

Variable Interpolation

Parallel Execution (Phase 4)

REST API (Phase 4)

Start API Server

API Endpoints

Example: Execute Workflow via API

WebSocket Events

Web UI

Accessing the UI

UI Features

UI Development

Architecture

Configuration

Example Configuration

Development

Run Tests

Run with Debug Logging

Project Structure

Roadmap

Contributing

License

Links

About

Resources

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`rustforge init [PATH]`

`rustforge run <WORKFLOW> [OPTIONS]`

`rustforge validate <WORKFLOW>`

`rustforge list`

`rustforge config <SUBCOMMAND>`

Packages