Quick Start Guide

Get MetaForge up and running in 5 minutes

Table of contents

1. Prerequisites
2. Installation
   1. 1. Clone the Repository
   2. 2. Install Dependencies
   3. 3. Build MetaForge
   4. 4. Start Data Services
   5. 5. Verify Installation
3. First Project
   1. Initialize Workspace
   2. Interactive Onboarding
4. Run Your First Workflow
   1. 1. Start the Gateway
   2. 2. Edit Your PRD
   3. 3. Run Requirements Agent
   4. 4. Approve Changes
5. Next Steps
   1. Run Architecture Agent
   2. Explore Generated Files
   3. View Session History
6. Common Commands
7. Complete Workflow
8. Troubleshooting
   1. Gateway Not Starting
   2. Agent Execution Fails
   3. Permission Denied
9. What’s Next?

Prerequisites

Before you begin, ensure you have:

• Node.js v18+ — CLI and Dashboard (TypeScript)
• Python 3.11+ — Gateway and Agent Runtime
• Git installed
• Docker (recommended, for Neo4j/Kafka/MinIO)
• KiCad (optional, for EDA integration)
• Text editor (VS Code recommended)

flowchart LR
    A[Node.js 18+<br/>CLI & Dashboard] --> D[Ready!]
    B[Python 3.11+<br/>Gateway & Agents] --> D
    C[Git] --> D
    E[Docker<br/>Data Services] --> D

    style D fill:#27ae60,color:#fff

Installation

1. Clone the Repository

git clone https://github.com/metaforge-labs/forge.git
cd forge

2. Install Dependencies

# Frontend (CLI & Dashboard)
npm install

# Backend (Gateway & Agents)
pip install -r requirements.txt

3. Build MetaForge

npm run build

4. Start Data Services

# Start Neo4j, Kafka, MinIO via Docker
docker compose up -d

5. Verify Installation

forge doctor

Expected output:

✅ Node.js v18.x.x
✅ Python 3.11.x
✅ Git v2.x.x
✅ MetaForge CLI installed
✅ FastAPI Gateway reachable
⚠️  KiCad not found (optional)

First Project

Initialize Workspace

# Create project directory
mkdir my-hardware-project
cd my-hardware-project

# Initialize MetaForge workspace
forge setup

This creates the .forge/ directory with initial configuration:

my-hardware-project/
└── .forge/
    ├── config.json
    ├── sessions/
    ├── traces/
    └── artifacts/

Interactive Onboarding

forge onboard

The onboarding wizard will:

1. Create a starter PRD.md (Product Requirements Document)
2. Set up project structure
3. Configure tool preferences
4. Guide you through first workflow

sequenceDiagram
    participant U as User
    participant CLI as forge CLI
    participant WZ as Onboarding Wizard

    U->>CLI: forge onboard
    CLI->>WZ: Launch wizard
    WZ->>U: What type of project?
    U->>WZ: IoT Device
    WZ->>U: Project name?
    U->>WZ: Smart Sensor
    WZ->>CLI: Create PRD.md
    WZ->>CLI: Setup structure
    CLI->>U: ✅ Project ready!

Run Your First Workflow

1. Start the Gateway

Open a new terminal and start the MetaForge gateway service:

forge gateway

Expected output:

🔥 MetaForge Gateway v0.1.0
📡 Listening on http://localhost:3000
✅ Ready for commands

2. Edit Your PRD

Open PRD.md and describe your hardware project:

# Smart Temperature Sensor

## Overview
A battery-powered IoT temperature sensor with WiFi connectivity.

## Requirements
- Temperature range: -40°C to 125°C
- Accuracy: ±0.5°C
- Battery life: 1 year (1 reading/minute)
- WiFi: 2.4GHz 802.11n
- Size: < 50mm x 50mm
- Cost target: < $15 BOM

## Constraints
- Single-sided PCB
- No fine-pitch components (> 0.5mm pitch)
- Standard parts only

3. Run Requirements Agent

forge run spec

What happens:

flowchart TD
    A[PRD.md] --> B[Requirements Agent]
    B --> C{Process & Validate}
    C --> D[constraints.json]
    C --> E[assumptions.md]

    D --> F[Review Changes]
    E --> F
    F --> G{Approve?}
    G -->|Yes| H[Write Files]
    G -->|No| I[Discard]

    style A fill:#E67E22,color:#fff
    style B fill:#9b59b6,color:#fff
    style H fill:#27ae60,color:#fff

The agent will:

1. Read your PRD.md
2. Extract technical constraints
3. Generate constraints.json
4. Create assumptions.md with design decisions
5. Show you a diff for approval

Example output:

📖 Reading PRD.md...
🤖 Running requirements agent...
✅ Generated constraints.json (2.3KB)
✅ Generated assumptions.md (1.8KB)

📝 Review changes:
  + constraints.json
  + assumptions.md

Approve changes? (yes/no):

4. Approve Changes

yes

Or use:

forge approve

Next Steps

Run Architecture Agent

forge run architecture

This will:

• Read constraints.json
• Select appropriate components
• Generate architecture.md with block diagram
• Create initial component list

Explore Generated Files

my-hardware-project/
├── PRD.md                    ← Your requirements
├── constraints.json          ← Generated constraints
├── assumptions.md            ← Design assumptions
├── architecture.md           ← System architecture
└── .forge/
    └── sessions/
        └── [session-id]/     ← Execution traces

View Session History

forge status

Output:

📊 MetaForge Status

Recent Sessions:
  ✅ spec (2 min ago)         - constraints.json, assumptions.md
  ✅ architecture (1 min ago) - architecture.md

Pending Approvals: None

Next Steps:
  → forge run schematic-plan
  → forge run bom

Common Commands

Complete Workflow

flowchart TD
    A[forge setup] --> B[forge onboard]
    B --> C[Write PRD.md]
    C --> D[forge run spec]
    D --> E[forge run architecture]
    E --> F[forge run schematic-plan]
    F --> G[forge run bom]
    G --> H[forge run dfm]
    H --> I[Manufacturing Files ✅]

    style A fill:#3498db,color:#fff
    style C fill:#E67E22,color:#fff
    style I fill:#27ae60,color:#fff

Troubleshooting

Gateway Not Starting

Problem: forge gateway fails to start

Solution:

# Check if port 3000 is in use
lsof -i :3000

# Use a different port
forge gateway --port 4000

Agent Execution Fails

Problem: forge run spec hangs or fails

Solution:

# Check gateway is running
curl http://localhost:3000/api/v1/health

# View detailed logs
forge run spec --verbose

# Check session traces
cat .forge/sessions/*/trace.jsonl

Permission Denied

Problem: Cannot write files

Solution:

# Check workspace permissions
ls -la .forge/

# Reinitialize if needed
rm -rf .forge/
forge setup

What’s Next?

• Installation Guide - Detailed setup instructions
• First Project - Complete walkthrough
• Architecture - System internals
• Examples - Real-world projects

← Home • Installation →