What's New

The latest ForgeAI release focuses on deeper security hardening, durable memory, better diagnostics, and safer autonomous execution.

Quick Start

Get ForgeAI running in under 2 minutes with Docker:

git clone https://github.com/forgeai-dev/ForgeAI.git
cd ForgeAI
docker compose up -d

Open http://localhost:18800 → the Setup Wizard guides you through SMTP, 2FA, and admin PIN configuration → add an LLM API key in Settings → start chatting.

No .env file needed. Security secrets are auto-generated on first run. The Setup Wizard appears only once, on the very first access.

From Source

pnpm install && pnpm -r build
node packages/cli/dist/index.js onboard   # Interactive setup wizard
node packages/cli/dist/index.js start --migrate

Prerequisites: Node.js ≥ 22, pnpm ≥ 9, MySQL 8.x. Gateway runs at http://127.0.0.1:18800.

Installation

Linux (Ubuntu/Debian)

# Install Node.js 22 + pnpm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
corepack enable && corepack prepare pnpm@latest --activate

# Install MySQL 8
sudo apt-get install -y mysql-server
sudo systemctl start mysql && sudo systemctl enable mysql
sudo mysql -e "CREATE DATABASE forgeai CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# Clone, install, configure, start
git clone https://github.com/forgeai-dev/ForgeAI.git && cd ForgeAI
pnpm install && pnpm -r build
pnpm forge onboard   # Interactive wizard
pnpm forge start     # http://127.0.0.1:18800

macOS

brew install node@22 mysql
brew services start mysql
mysql -u root -e "CREATE DATABASE forgeai CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
corepack enable && corepack prepare pnpm@latest --activate
git clone https://github.com/forgeai-dev/ForgeAI.git && cd ForgeAI
pnpm install && pnpm -r build
pnpm forge onboard && pnpm forge start

Windows

# Install Node.js 22 from https://nodejs.org
# Install MySQL 8 (installer or XAMPP)
corepack enable
corepack prepare pnpm@latest --activate
git clone https://github.com/forgeai-dev/ForgeAI.git
cd ForgeAI
pnpm install && pnpm -r build
pnpm forge onboard
pnpm forge start

Docker

git clone https://github.com/forgeai-dev/ForgeAI.git && cd ForgeAI
cp .env.example .env  # Edit with your settings
docker compose up -d  # Gateway + MySQL, ready at http://localhost:18800

# Optional: Enable custom domain with automatic HTTPS
bash scripts/setup-domain.sh

Configuration

Environment Variables (.env)

# Database
MYSQL_HOST=127.0.0.1
MYSQL_PASSWORD=your_password
MYSQL_DATABASE=forgeai

# Security (auto-generated by onboard wizard)
JWT_SECRET=your-random-jwt-secret
VAULT_MASTER_PASSWORD=your-strong-vault-password

# Gateway
GATEWAY_PORT=18800

LLM API keys and channel tokens are managed via the Dashboard Settings page. They are validated with a test call and stored encrypted in the Vault — never in .env or plain text.

Workspace Files (.forgeai/)

All editable from Dashboard → Workspace.

Channels (8)

One AI, every platform. Each channel gets real-time progress updates, typing indicators, and automatic message chunking.

Built-in Tools (19)

LLM Providers (10)

All model lists are configurable per provider via the Dashboard Settings page or the POST /api/providers/:name/models endpoint. Custom models are stored encrypted in Vault.

Every provider has circuit breaker protection (5-failure threshold, 2-minute cooldown), exponential backoff retries, and automatic failover to the next provider in the chain.

Tip: You don't need a pay-as-you-go API key to use Claude. If you have a Claude Pro/Max/CLI subscription plan, paste the API key in Dashboard → Settings → Anthropic.

Security Modules (17)

ForgeAI now ships with 17 security modules. The visualization below shows the core request flow, while the additional hardening layers protect tool outputs, file access, command execution, outbound traffic, and model-specific risk.

Encrypted Vault

All secrets (API keys, tokens, passwords) encrypted with AES-256-GCM. PBKDF2 key derivation. Never stored in plain text or .env.

RBAC

Role-based access control. Admin and user roles with hard enforcement (403 block for non-admin authenticated users on restricted endpoints).

Rate Limiting

Configurable per-IP and per-user rate limits. Protects against brute force and abuse.

Prompt Guard

Detects and blocks prompt injection attempts before they reach the LLM. The current guard includes direct injection, role hijacking, encoding tricks, delimiter abuse, context manipulation, and multilingual attack patterns.

2FA & Email OTP

TOTP-based 2FA with QR code setup. Email OTP for external access with styled HTML emails, 5-minute expiry, rate limiting.

Audit Log

Tamper-proof audit logging with hash chains. Every action recorded. Rotation support.

First-Run Setup Wizard

Guided setup on first access: SMTP configuration with test connection, 2FA (TOTP) with QR code, admin PIN change.

Smart IP Detection

Automatically detects whether requests come from localhost or an external IP. On a VPS or any internet-facing deployment, ForgeAI automatically requires an additional Email OTP step with no extra configuration.

Tool Output Sanitizer

Scans content returned by tools before it is injected into the model context. This blocks indirect prompt injection coming from web pages, search results, files, and other external content sources.

Sensitive File Guard

Detects and blocks reads of highly sensitive material such as .env files, SSH keys, PEM/KEY files, vault artifacts, cloud credentials, and password databases like /etc/shadow or Windows SAM.

Exfiltration Prevention

Prevents suspicious outbound shell commands that attempt to send secrets to external destinations via curl, wget, scp, nc, and similar patterns.

Persistence Blocker

Blocks persistence techniques such as reverse shells, SSH key injection, cron manipulation, systemd service installation, and scheduled task abuse across both shell_exec and file_manager.

Model Security Profiles

ForgeAI maps supported models into security tiers and automatically applies stricter prompt defense thresholds to weaker or more manipulation-prone models.

Network Egress Control

Blocks known exfiltration domains and prevents SSRF-style access to sensitive metadata endpoints from AWS, GCP, and Azure.

Sandbox Isolation

Code execution is sandboxed by default with read-only filesystems, no-new-privileges, disabled networking, and memory/CPU limits to reduce blast radius during code execution tasks.

System Prompt Defense

ForgeAI injects explicit defensive rules into the model instructions so the agent treats untrusted external content as hostile by default instead of blindly obeying embedded instructions.

Dashboard (19 Pages)

Full-featured React 19 SPA served directly by the Gateway. No separate deployment needed. Real-time WebSocket updates.

Desktop Apps

ForgeAI offers two desktop applications with different purposes. Understanding the distinction is important to choose the right one for your use case:

ForgeAI Companion — AI Desktop Controller (Tauri 2)

Native desktop client (packages/companion) built with Tauri 2 + React + Rust. The Companion connects to any ForgeAI Gateway (local or remote) and gives the AI agent the ability to control your Windows desktop — creating files, running commands, taking screenshots, and more. The Gateway itself can run on any platform (Linux VPS, Docker, etc.), while the Companion runs on your Windows machine.

Desktop App — Dashboard Wrapper (Electron)

Lightweight native wrapper (packages/desktop) that packages the ForgeAI Dashboard as a standalone desktop application. Instead of opening a browser tab to access http://localhost:18800, the Desktop App gives you a native window with OS-level integration. It does not connect to the Gateway as a client or give the AI control over your PC — it simply displays the same Dashboard UI in a native window.

Persistent Memory

ForgeAI memory is now durable across restarts, rebuilds, and deployments. Instead of living only in-process, important learnings are stored in MySQL and retrieved with semantic search when relevant.

Skill Registry

The Skill Registry lets you extend ForgeAI with runtime-managed capabilities. Skills are persisted, can be enabled or disabled on demand, and are injected into the agent context automatically.

Intent Classifier

Zero-cost heuristic classification that runs before every LLM call — no extra API request needed. Classifies user messages into intent types and optimizes what gets sent to the model.

Agent Workflow Engine

A state-machine execution model for complex autonomous tasks. The engine tracks structured steps, manages retries, and persists state to MySQL so workflows survive restarts.

Forge Teams & Task Delegation

Create coordinated teams of specialist agents that work together on complex projects. Independent tasks run in parallel; dependent tasks wait for upstream results and receive them as context.

Adaptive Prompt Optimizer

The agent learns from past task outcomes and automatically improves prompts for future tasks. Inspired by DSPy's optimization concepts, built natively for ForgeAI.

Blocked IP Persistence

IPs blocked by rate limiting or threat detection are now persisted in MySQL instead of only living in memory. They survive server restarts, Docker rebuilds, and redeploys.

Audit Hash Chain Integrity

The audit log uses a hash chain (each entry's hash includes the previous entry's hash) for tamper detection. Phase 36 fixed a precision issue and added auto-repair.

Node Protocol (IoT/Embedded)

Connect lightweight devices to your AI via WebSocket. A single Go binary (~5MB, zero dependencies) turns any Linux board into an AI-powered node.

Supported: Raspberry Pi, Jetson Nano, BeagleBone, Orange Pi, NanoKVM, ESP32 (MicroPython).

# Download binary from GitHub Releases
wget https://github.com/forgeai-dev/ForgeAI/releases/download/node-agent-latest/forgeai-node-linux-arm64
chmod +x forgeai-node-linux-arm64

# Run
./forgeai-node-linux-arm64 \
  --gateway http://YOUR_GATEWAY_IP:18800 \
  --token YOUR_NODE_API_KEY \
  --name "My-RaspberryPi"

RAG Engine

Ingest documents (text, markdown, PDF text), chunk with configurable overlap, generate TF-IDF or OpenAI embeddings, search semantically. Retrieved context is injected into the agent's prompt automatically. Persistence to disk with auto-load on startup.

Workflow Engine

Define multi-step workflows with conditions, delays, transforms, and parallel branches. Execute via API or schedule with cron. Each step can call tools, send messages, or trigger other workflows.

Autopilot

Define scheduled tasks in AUTOPILOT.md with tags: @startup, @hourly, @morning, @evening, @daily, @weekly. Editable from Dashboard.

Config Sync

Securely transfer all Gateway configurations between instances using encrypted one-time sync codes. AES-256-GCM encryption, 5-minute TTL, single-use, rate-limited, audit-logged.

Domain / HTTPS (Native)

Built-in Caddy reverse proxy with automatic Let's Encrypt SSL. Run bash scripts/setup-domain.sh for interactive setup that validates DNS, checks ports, configures .env, and deploys.

Static Site Hosting

The Gateway automatically serves static websites created by the agent at /sites/<project-name>/. No extra ports, no HTTP servers needed. With a domain: https://yourdomain.com/sites/<project-name>/.

API Reference (150+ Endpoints)

Full list available at GET /info. Key endpoints:

CLI Reference

pnpm forge onboard   # Interactive first-time setup
pnpm forge start     # Start Gateway + Dashboard
pnpm forge doctor    # Check Runtime, Configuration, LLM Providers, Services, Workspace
pnpm forge status    # Quick status check

Chat Commands (from any channel)