OpenForge

An autonomous multi-agent task execution system. Turn any VPS or local machine into a powerful AI-driven development platform where specialized agents read files, run shell commands, and complete tasks autonomously.

Overview

OpenForge is a CLI tool that runs on your own hardware and manages a fleet of AI agents. Each agent has its own workspace, instructions (agent.md), and LLM configuration. You create tasks, assign them to agents, and watch them execute in real-time through a web interface.

Core philosophy:

• Local-first: Runs on your machine, your data stays on your machine
• No sandbox: Agents have direct filesystem access within their workspace
• Permission system: Sensitive actions require your approval before execution
• Full control: Everything configurable via agent.md files

Features

• Multi-agent support: Run multiple specialized agents simultaneously
• Web UI: Modern dashboard to manage agents, tasks, and permissions
• Real-time execution: Watch agent progress live via WebSocket
• Permission workflow: Approve or reject sensitive operations
• Tool execution: Agents can read/write files, run shell commands, and more
• OpenRouter integration: Use any compatible LLM model

Requirements

• Node.js 18 or higher
• npm or pnpm
• An OpenRouter API key

Quick Start

Installation

npm install -g openforge

Initialize

openforge init

The init wizard will prompt you for:

1. Workspace directory (default: ~/openforge-workspaces)
2. OpenRouter API key
3. Web UI port (default: 3747)

Start the Server

openforge start

This starts the server and opens the web UI in your browser.

Usage

Create an Agent

1. Open the web UI at http://localhost:3747
2. Go to the Agents page
3. Click New Agent
4. Configure:
   • Name (e.g., "Backend Dev")
   • OpenRouter API token (optional, uses default if empty)
   • Model (e.g., anthropic/claude-3.5-sonnet)
   • Workspace path (where the agent will work)
   • Agent instructions (agent.md)

Create a Task

1. Go to the Tasks page
2. Click New Task
3. Provide a title and description
4. Assign to an agent
5. Click Run to start execution

Monitor Execution

• Watch real-time progress in the Chat view
• Approve/reject permission requests when prompted
• View task status and results

Agent Tools

Agents have access to these tools:

| Tool | Description | |------|-------------| | bash | Execute shell commands in the workspace | | read_file | Read files from the workspace | | write_file | Create or overwrite files | | list_dir | List directory contents | | request_permission | Pause and request admin approval | | task_complete | Mark task as complete |

Architecture

openforge/
├── bin/
│   └── cli.js           # CLI entry point
├── src/
│   ├── server/
│   │   ├── index.ts     # Express server
│   │   ├── websocket.ts # Real-time updates
│   │   ├── db/          # SQLite database
│   │   ├── routes/      # REST API endpoints
│   │   └── services/    # Agent runner, LLM client
│   └── commands/        # CLI commands
└── ui/                  # React frontend

Security

• Workspace path enforcement prevents filesystem escape
• Shell commands run with cwd set to workspace
• Permission system blocks sensitive operations until approved
• Review your agent.md instructions carefully

Warning: Agents can run arbitrary shell commands within their workspace. Only assign tasks from trusted sources.

Configuration

Config is stored at ~/.openforge/config.json:

{
  "workspaceDir": "~/openforge-workspaces",
  "apiKey": "sk-or-v1-...",
  "port": 3747
}

Database: ~/.openforge/openforge.db

CLI Commands

openforge init      # Initialize configuration
openforge start     # Start server and open UI
openforge status    # Show agents and tasks

REST API

| Endpoint | Description | |----------|-------------| | GET /api/agents | List all agents | | POST /api/agents | Create agent | | GET /api/tasks | List all tasks | | POST /api/tasks | Create task | | POST /api/tasks/:id/run | Start task execution | | GET /api/permissions | List permission requests | | POST /api/permissions/:id/resolve | Approve/reject |

WebSocket Events

Connect to ws://host:port/ws for real-time updates:

• task:update - Task status changed
• task:message - New execution message
• agent:update - Agent status changed
• permission:request - New permission request
• permission:resolved - Permission resolved

License

MIT