Quickstart

Create your first project with BlueForge in under 2 minutes.

Installation

BlueForge is available as a desktop app (macOS/Windows), an npm CLI, and Docker image.

Desktop App

Download for the full IDE experience with integrated terminal, file browser, and live preview.

CLI (npm)

Requires Node.js 18+.

Docker

# One-shot mode
docker run --rm -v $(pwd):/workspace \
  -e ANTHROPIC_API_KEY=sk-... \
  blueforge-cli "Build a landing page"

# HTTP server mode
docker run -d -p 3202:3202 \
  -v $(pwd):/workspace \
  blueforge-cli --serve

System Requirements

Import existing project

Bring your existing project into BlueForge. Auto-detect your tech stack, scan for databases, and continue building with AI assistance.

Steps

Supported Stacks

Database Detection

Home

Your project hub. Create, import, and manage all projects from here.

Project Cards

Each project is a card with name, description, tech stack, and last modified date. Click to open.

Sidebar Navigation

• Home — Project list
• Settings — API keys, preferences
• MCP Servers — Manage MCP connections
• Commands — Slash command management
• Agent Skills — Passive behavioral skills
• Extensions — Marketplace

Discovery

The Discovery wizard guides you through defining your project. Describe what you want, and BlueForge generates a complete architecture blueprint.

Blueprint

A visual representation of your entire app architecture, organized into 5 layers.

5-Layer Structure

Implementation Tiers

Project Dashboard

A 9-phase lifecycle view from planning to production monitoring.

Layout

Header shows project name and progress gauge. The Phase Timeline displays 9 circular stages below.

Phases

Data Persistence

All settings are auto-saved to project.json. Tokens are stored in OS secure keychain.

Phase 1 — Plan

Summarizes project requirements from Discovery.

Radar Chart

Displays 5 axes — Screens, Features, Architecture, Processes, DB/API — showing project scope. This phase is read-only. Edit the Blueprint directly.

Phase 2 — Design

Configure your project's visual design system.

Design Theme

8 AI-recommended themes. Click a card to apply. "Browse All" for the full preset library.

Color Palette

6 colors: Primary, Secondary, Accent, Background, Surface, Text.

Live Preview

Preview in Login, Landing, and Dashboard layouts.

Typography

Heading, Body, and Mono fonts from Google Fonts with live preview.

Theme & Shape

Mode (Light/Dark/System) and Radius (None/Small/Medium/Large).

Phase 3 — Source Control

Connect GitHub for version control.

Phase 4 — Infrastructure

Choose backend, hosting, and database stack.

Recommended Combos

7 pre-configured stacks (ForgeDB Native, Vercel+Supabase, AWS Full Stack). Each shows price tier.

Custom Stack

Phase 5 — Build

Code generation, task management, and quality verification.

Generate Tasks

AI analyzes your blueprint and generates development tasks by tier.

Build History

Recent 5 builds with success/failure, task count, errors, and deploy status.

Quality Gate

Automatic lint, type checking, and build verification.

Phase 6 — Test

Configure and run tests across multiple categories.

Test Types

Toggle: Unit, Integration, E2E, Component, A/B, Load, Security.

Modes

• Auto — Detects Jest/Vitest and runs automatically.
• Manual — Record Pass/Fail/Skip manually.

AI Test Generation

"Generate Tests" creates test items per category from code analysis.

Phase 7 — Docs

Select documentation types to generate.

Toggle: README, API Docs, Storybook, ADR, User Guide, Changelog. Generated after first deployment.

Phase 8 — Deploy

Configure deployment infrastructure.

Domain Provider

Cloudflare, Namecheap, GoDaddy, Route53, or None.

CDN

Cloudflare, Vercel Edge, AWS CloudFront, or None.

Phase 9 — Monitor

Monitoring and analytics setup.

Monitoring

Sentry, Datadog, or None.

Analytics

Google Analytics 4, PostHog, Mixpanel, or None.

Build Studio

AI-powered coding workspace. The agent reads your blueprint and generates production-ready code in real-time.

Interface

• Chat Panel — Communicate with the AI agent
• Code Editor — Monaco Editor with syntax highlighting
• File Explorer — Browse project files
• Terminal — Integrated xterm.js
• Preview — Live preview of your running app

AI Agent Workflow

LLM Selection

Device Lab

Test across multiple devices simultaneously. Compare iOS, Android, and desktop viewports in real-time.

Supported Devices

iOS

iPhone SE, 14/14 Pro, 15/15 Pro, 16/16 Pro and Plus/Max variants.

Android

Pixel 7–9 Pro, Galaxy S23–S25 Ultra, Z Flip/Fold 6, Galaxy A54, OnePlus 12.

Web

Desktop 1920x1080, 1440x900, 1280x720, iPad, iPad Pro 12.9", Galaxy Tab S9.

Usage

Settings

Configure API keys, LLM preferences, and account settings.

API Keys (BYOK)

Key Priority

1. Explicit selection   (manual model picker)
2. Environment vars     (ANTHROPIC_API_KEY, etc.)
3. App settings         (Settings page BYOK)
4. BlueForge credits    (default fallback)

Local AI Models

Run AI tasks on your own machine using Google Gemma 4 via Ollama. Zero cloud costs, full privacy, no internet required.

Setup

Model Catalog

Google Gemma 4 models, optimized for code generation and analysis.

Task Routing

Choose which AI tasks run on your local machine vs cloud APIs. Tasks are grouped into 9 categories. BlueForge auto-detects your downloaded models and optimizes routing automatically — if you have 26B+ models, Code and Review tasks route locally too.

Cloud-Locked Tasks

These tasks always run on cloud and cannot be routed to local models:

• Image & Vision — No local image generation models are available
• Critical — Full system refactoring and production incidents require premium reasoning capabilities
• Security — Security audits require the highest-quality models for accurate vulnerability detection

Presets

Credits & Pricing

Local model usage is always free — no credits are deducted. This applies regardless of which model you use (E2B through 31B). Only cloud-routed tasks consume credits.

Local (Gemma 4 E2B/E4B/26B/31B)   FREE  # 0 credits
Cloud (Gemini 2.0 Flash)           10    # credits per call
Cloud (Claude Sonnet 4)            20    # credits per call
Cloud (GPT-4o)                     20    # credits per call

System Requirements

CLI Reference

Run BlueForge AI agent from the terminal — Linux, macOS, CI/CD, Docker. No GUI required.

Installation

Three Modes

One-shot

blueforge "Add a login page with email/password"
blueforge -m claude-sonnet-4-20250514 "Refactor auth.ts"
blueforge -p gemini "Generate unit tests for src/utils/"

Interactive

blueforge              # Start interactive session
blueforge -p anthropic # With specific provider

HTTP Server

blueforge --serve
blueforge --serve --port 8080 --api-key my-secret-key

API Endpoints

Environment Variables

MCP Server

Connect your AI agents to BlueForge via Model Context Protocol. Access file operations, terminal, git, and project context.

Architecture

Your Agent  (LLM)
    |
MCP Client  (BlueforgeConnector)
    |  MCP Protocol (stdio / SSE)
BlueForge MCP Server
    +-- file_read / file_write / file_edit
    +-- file_delete / file_list / file_search
    +-- terminal_exec / npm_install
    +-- git_status / git_diff / git_commit
    +-- project_info

Setup

{
  "mcpServers": {
    "blueforge": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "BLUEFORGE_PROJECT_DIR": "/path/to/project"
      }
    }
  }
}

Available Tools

Security

Multi-Agent System

20+ specialized AI agents collaborate on complex tasks. An intelligent router selects the best agent for each request.

Master Agents

Domain Specialists

Quality & Security

Routing

Commands & Agent Skills

BlueForge provides two complementary systems for extending AI behavior: Commands (active, slash-invoked) and Agent Skills (passive, auto-injected).

Commands

Commands are slash-triggered workflows you invoke in the chat with /command-name. They provide specialized behavior for common tasks.

How to use

Built-in Command Categories

Managing Commands

Navigate to Commands in the sidebar to browse, enable, or disable commands. Commands are project-independent and available across all projects.

Agent Skills

Agent Skills are passive behavioral instructions housed in .agent/skills/ directories within your project. They are automatically injected into the AI system prompt for every LLM call, shaping how the AI writes code, reviews, and responds.

Directory structure

my-project/
  .agent/
    skills/
      clean-code/
        SKILL.md              // Main instruction file
      testing-patterns/
        SKILL.md
        scripts/
          test_runner.py      // Optional helper scripts
      frontend-design/
        SKILL.md
        examples/
          card-component.tsx  // Reference implementations

SKILL.md format

Each SKILL.md file has YAML frontmatter followed by markdown instructions.

---
name: Clean Code Standards
description: Pragmatic coding standards for concise, readable code
trigger: always_on
---

# Instructions body (markdown)

All code must follow these rules:
- Use meaningful variable names
- Keep functions under 30 lines
- No unnecessary comments
- Self-documenting code preferred
...

Frontmatter fields

How it works

Managing Agent Skills

Navigate to Agent Skills in the sidebar to view all detected skills, toggle them on/off, and see estimated token usage per skill.

Built-in Skill Categories

BlueForge's .agent/skills/ directory includes 30+ pre-built skills:

Commands vs Agent Skills

Extensions

Access the Extension Marketplace from the sidebar to browse, install, and manage extensions that add new capabilities to BlueForge.

Integrations & Workflows

BlueForge's Platform Workflow Engine (PWE) provides pre-built browser automation workflows for 56+ platforms across 14 categories. The AI Agent uses these workflows to navigate external services, extract credentials, and configure integrations automatically.

Overview

Global Services

BaaS & Database

Auth

AI

Hosting & Compute

AWS (8 Services)

Payment

Email & SMS

Messaging

Maps & SEO

DNS & SCM

Korea

Japan

Southeast Asia

Security Model

Workflows enforce a human-in-the-loop security model. Each step has an agentCanDo flag:

3-Layer Merge Strategy

Workflows are resolved in a 3-layer priority system: