Documentation

Technical guide for the Forge Lab Brain ecosystem. Orchestrate AI agents, manage deployments, and understand our token-based economy.

Getting Started

Forge Lab Brain is a hybrid AI development platform that merges Large Language Models (LLMs) with a live, in-browser execution environment. For JavaScript/TypeScript/React/Vue and other Node.js-based projects, code runs directly via WebContainers. For Python, Java, Go, Rust, Ruby and 30+ other languages, code executes instantly via the built-in Judge0 engine, no setup, no local install, no limits.

Technical Requirement: Forge Lab uses SharedArrayBuffer for its in-browser terminal. This requires a modern browser (Chrome, Edge, Firefox) supporting Cross-Origin-Embedder-Policy headers.

Instant Environment

No localhost setup. The terminal runs entirely within your browser tab via WebAssembly.

Multi-Agent Architecture

Complex tasks are broken down and distributed to specialized agents (Coding, Debugging, Planning).

How Brain Mode Works

Brain Mode is the orchestration layer of Forge Lab. When you submit a request, it is not sent directly to a coding model. Instead, it passes through our cognitive pipeline:

// 1. User Input "Create a React dashboard with Supabase auth" // 2. Conductor Agent (routes via OpenRouter) analyzeRequest() -> "Complex Task detected" // 3. Architect Agent (plans only, writes no code) createPlan() -> ["Scaffold Vite", "Install Dependencies", "Setup Auth"] // 4. Execution (Senior Dev Agent) await executeStep("Scaffold Vite") // 5. Auto-Fix (Bug Hunter Agent) if (terminal.error) { fixError(terminal.logs) }
Availability: Brain Mode requires a Pro or BYOK plan. Free plan chat still has full access to every model, just without the multi-agent pipeline.

Agent Roles

Depending on your subscription tier, different models power these agents.

🚦 Conductor

Role: Orchestrator

Decides how to solve the problem and routes it to the right agent. It does not write code itself.

🧭 Architect

Role: Planner

Plans only, never writes code. Lists every file the project needs with full paths and groups related work into tasks before implementation starts.

💻 Senior Dev

Role: Implementation

Writes high-quality, typed code across 37+ languages: React, Vue, Python, Go, Rust, Java, Kotlin, Swift and more.

🐛 Bug Hunter

Role: QA & Fixer

Automatically reads terminal output. If a build fails, it intervenes without user prompt.

🔍 Bug Hunter FAST

Role: Pre-filter

A quicker first pass over terminal errors that maps out the problem before the full Bug Hunter writes the actual fix.

🔧 Audit Fixer

Role: Tool-use fixer

Powers the Audit Loop (Fix My Project): reads and edits files directly through tool calls until the build is clean.

⚡ Rapid Prototyper

Role: Fast draft

Optimized for working code fast over perfect code, useful for quick HTML/CSS/JS/Python prototypes.

🎓 Beginner Mentor

Role: Teaching

A patient, educational persona that explains every step and term in simple language, for users new to programming.

🔎 Holistic Reviewer

Role: Final review

A report-only final pass over the whole generated project, catching cross-file issues individual validators miss.

Multi-AI, Multi-Task

ForgeLab Brain does not send your request to a single AI model. Instead, it orchestrates multiple specialized agents running in parallel, each with a distinct role, working on different parts of your project simultaneously.

// Parallel execution: all at the same time parallel { Senior Dev Agent → writes src/App.jsx Senior Dev Agent → writes src/components/Header.jsx Bug Hunter Agent → validates completed files Architect Agent → plans next phase }

Conductor

Analyzes the request and routes it to the right agents, manages phase progression. Does not write code or plan files, it delegates.

Architect

Breaks your request into a structured plan: every file with a full path, grouped into tasks. Plans only, writes no code.

Senior Dev (×N)

Multiple instances can run in parallel, each generating a separate file. File locking prevents conflicts between agents writing to the same file.

Bug Hunter

Continuously validates completed files for import errors, syntax issues, and broken references. Auto-fixes what it can, escalates the rest.

Integrity Check

Final gate before the dev server starts. Validates every file, checks Vue/React plugin presence, detects truncated files, and runs stack-aware linting.

Why it matters: Sequential AI tools write one file, then the next. ForgeLab writes all files simultaneously: a 10-file React project that takes 2 minutes sequentially finishes in under 40 seconds with parallel agents.

Languages & In-Browser Execution

ForgeLab supports 37+ programming languages across two execution backends depending on the stack type.

WebContainer (Node.js-based)

These run natively in the browser via WebAssembly. Live preview, HMR, and terminal access included.

Frontend Frameworks

React, Vue 3, Svelte, Next.js, Angular, Astro, static HTML/CSS/JS

Backend (Node.js)

Express, Fastify, Node.js scripts, TypeScript via ts-node

Full-stack projects: a project with a separate client/ and server/ folder, each with its own package.json, is detected automatically. Both start together, Preview shows the real frontend (not the API's raw response), and the frontend's API calls are proxied to the backend behind the scenes.

Judge0 Engine (All other languages)

For compiled and scripting languages, code executes instantly via the integrated Judge0 sandboxed engine. Multi-file projects are supported: all project files are bundled and sent together.

// Supported via Judge0 (select file → click ▶ Run) Python 3.8 │ Go 1.13 │ Rust 1.40 Java 13 │ Kotlin 1.3 │ Scala 2.13 C (GCC 9.2) │ C++ (GCC 9.2) │ C# (Mono 6.6) Ruby 2.7 │ PHP 7.4 │ Swift 5.2 TypeScript 3.7 │ JavaScript │ Lua 5.3 R 4.0 │ Haskell 8.8 │ Elixir 1.9 Erlang OTP 22 │ Bash 5.0 │ Perl 5.28 SQL (SQLite) │ Pascal │ Assembly (NASM) Clojure 1.10 │ OCaml 4.09 │ F# (.NET Core) Groovy 3.0 │ Fortran │ COBOL
Multi-file support: When you click Run, ForgeLab automatically bundles all related project files (e.g. all .py files) and sends them together, so from config import X works out of the box.

Fix My Project

The Audit Loop lets you import an existing project and have ForgeLab automatically detect and fix all errors, without generating anything from scratch. It uses the same multi-agent infrastructure as Brain Mode, but skips the generation phases and goes straight to validation and repair.

How to use it

  1. Upload your project files to the Virtual File System (VFS). Drag & drop them onto the file tree, or use the Upload Files button.
  2. Enable the Audit Loop toggle (shield icon, amber color) in the toolbar. A card will appear in the chat.
  3. Click ▶ Start Audit on the card. Alternatively, type fix my project in the chat at any time.
  4. The Brain Monitor opens and the audit loop runs automatically: build check → ESLint → TypeScript → cross-validation → fix.
  5. When all errors are resolved, deploy your fixed project with one click.

Stack Auto-Detection

ForgeLab reads your package.json and automatically detects whether your project is React, Next.js, Vue, Svelte, Node.js, or static HTML. No configuration needed.

Iterative Fix Loop

The audit runs up to 5 rounds. Each round: find errors → create fix tasks → apply fixes → re-validate. It stops as soon as the project is clean.

Full Audit Pipeline

Every iteration runs: npm build (compiler errors), ESLint (lint errors), TypeScript (type errors), and cross-validation (prop mismatches, missing imports).

Chat Trigger

Type fix my project in the chat at any time. ForgeLab will enable the Audit Loop and show the setup card automatically.

Tip: The Audit Loop works on any project already in the VFS, whether you uploaded it, generated it with Brain Mode, or built it manually. It does not clear your files or start over.
Availability: since the Audit Loop runs on the Brain Mode engine, it requires a Pro or BYOK plan, same as Brain Mode itself.

Deploy

ForgeLab can deploy your project to Cloudflare Pages with a single click, directly from the browser, no Git setup required.

One-Click Deploy

Click the 🚀 Deploy button. ForgeLab builds your project (npm run build), zips the output, and pushes it to Cloudflare Pages automatically.

Live URL in ~60s

Your site goes live on a *.pages.dev subdomain within about 60 seconds of clicking deploy.

Deployment History

All deployments are saved with timestamp and live URL. Revisit or share previous versions at any time.

Clean Deploys

Each deploy creates a fresh branch: no stale cache, no leftover files from previous builds.

Note: Deploy is available for WebContainer-based projects (React, Vue, Next.js, static HTML). Python, Java, and other Judge0-based projects generate downloadable source files instead. A Next.js project built in "Full backend (SSR)" mode (see Backend & Database below) is the one exception, it needs a real server and can't be Published, only previewed.

Backend & Database NEW

Generated projects run entirely in your browser by default, no server, no database. For apps that need one (accounts, saved records, a dashboard backed by real data), ForgeLab can detect that need and connect it to a real Postgres database in your own Supabase project.

Automatic Data Model Detection

While planning your project, the architect agent recognizes when your request implies persisted data and works out which tables and columns it would need.

Connect Your Own Supabase Project

Same BYOK pattern as GitHub: paste your project URL, anon key, and connection string (from Supabase Project Settings). Nothing is shared beyond your own project.

One-Click Table Provisioning

Once connected, ForgeLab creates the detected tables directly in your Supabase project via a direct database connection, not a broad account-level API.

Row-Level Security by Default

Every table gets RLS enabled automatically, with policies scoped to each user's own rows. No manual setup, and no separate step you can forget.

Real Code, Not Just Tables

Once connected, generated React, Vue, Svelte, and Next.js projects write real Supabase calls (and real Supabase Auth for login/registration) instead of mock data. Nothing changes for projects that don't connect a database.

Current state: React, Vue, Svelte, and Next.js projects all use the real database and Supabase Auth once connected. If you don't connect Supabase, every stack still works with local/mock data exactly as before.

Next.js: two backend modes

Next.js can run as a fully static site or as a real server, and those two modes need different code. When you connect Supabase to a Next.js project, the plan review screen asks which one you want before building starts.

Static export

Client-side Supabase Auth and data calls, the same pattern React/Vue projects use. next.config.js keeps output: 'export', so the build stays a plain static site. Works in Preview, and can be shipped with ForgeLab's own Publish button.

Full backend (SSR)

Real server-side session handling via @supabase/ssr: a middleware.js that refreshes the session on every request, and separate client/server Supabase helpers so Server Components can read who's logged in directly. output: 'export' is removed, so API routes and Server Actions are allowed too.

Important tradeoff: "Full backend" works completely inside ForgeLab's Preview, but it needs a real Node server to run, so the Publish button (Netlify/Cloudflare, static files only) is disabled for that project. To put it online, deploy the codebase yourself to a Node-capable host such as Vercel. If you want a project you can Publish directly from ForgeLab, pick "Static export" instead.

Brain Knowledge

Brain Knowledge is our persistent memory system (RAG - Retrieval Augmented Generation). It allows the agents to "remember" your project context, preferences, and documentation across different sessions.

Privacy & Security: Knowledge data is stored in a vector database linked strictly to your User ID. We do not train our public models on your private code snippets.

What it remembers:

  • Tech Stack: "User prefers Tailwind over CSS modules."
  • Project Structure: Where you keep your components vs. pages.
  • API Keys: (Stored encrypted) To facilitate auto-connection to 3rd party services.

Image & Speech Generation

Beyond writing code, Brain Mode's chat can generate images and spoken audio directly in the conversation. Toggle the mode you want with the buttons next to the message box, describe what you want, and send.

Image Generation

Turn on Image mode, describe the image, and get it generated inline in the chat with download and edit options. Useful for hero images, icons, and mockups for the app you're building.

Text to Speech

Turn on Speech mode and type the text you want read aloud. Choose from 5 voice models with different quality and price tiers, right in the model picker under the "Voice" category.

Model picker categories: the model picker groups models into Coding, Voice, and Image Generation, so a voice or image model never gets picked by mistake as your main coding model.
Availability: both features run on your token balance, so they're available on any plan, including Free, as long as you have tokens left.

Plans

ForgeLab offers two access models and optional Token Packs for additional credits.

Free $0/mo

400,000 tokens per month, full model access, persistent knowledge, and auto-deployment all included. Brain Mode (and Fix My Project, which runs on it) requires Pro or BYOK. Upgrading only happens when you choose to purchase tokens.

BYOK $7.99/mo

Connect your own OpenRouter API key. Unlimited Brain workflows, Brain Knowledge (RAG), 1-click deployment, 7-day free trial. You pay ForgeLab for the platform and OpenRouter directly for AI usage.

Token Packs one-time

One-time FLT credit purchases (5M, 10M, 27.5M, 60M, 130M FLT). Unused packs are refundable within 14 days. Partially used packs are non-refundable.

Billing & Tokens

Forge Lab uses a flexible hybrid billing system designed for developers. We utilize Stripe for secure payment processing.

1. FLT (Forge Lab Tokens)

To handle micro-transactions for various AI models (GPT, Claude, Gemini and more via OpenRouter), we convert currency into FLT.

1 USD = 1,000,000 FLT (Forge Lab Tokens)

This allows for granular billing. For example, a simple chat message might cost 500 FLT, a complex image generation might cost 40,000 FLT, and speech generation is billed per character of input text (or per token for the one model billed that way), scaling with how much text you ask it to read aloud.

2. Refund Policy

  • Subscriptions (BYOK): Refundable within the first 7 days if the service has not been utilized significantly.
  • Token Packs: Unused token packs are refundable within 14 days. Partially used packs are non-refundable.

Two-Factor Authentication

Two-factor authentication (2FA) adds a second step to logging in, so a leaked or guessed password alone isn't enough to access your account. It's optional and off by default. Enable it any time from Settings → Account.

1. Choose a method

  • Authenticator App (TOTP): Works with Google Authenticator, Authy, 1Password, or any standard authenticator app. During setup you'll get a key to add manually (scanning a QR code isn't supported yet). After that, the app generates a new 6-digit code every 30 seconds.
  • Email Code: A 6-digit code is sent to your account email each time you log in. Simpler to set up, but only as secure as your email inbox.

2. Backup codes

When you enable 2FA, you'll get a set of one-time backup codes. Each one works exactly once and can replace your authenticator app or email code if you ever lose access to them. Store them somewhere safe: they're only shown once, at setup time.

3. Disabling 2FA

You can turn 2FA off, or generate a fresh set of backup codes, from the same Settings panel. Both actions require re-entering your current password.

BYOK (Bring Your Own Key)

For power users who already have an account with OpenRouter, we offer the BYOK model.

Direct Connection

You input your OpenRouter API Key in Account Settings. Usage is billed directly to your OpenRouter account.

Platform Fee

Forge Lab charges a small monthly subscription ($7.99/mo) to access the UI and Orchestration tools (Conductor).

Security: Your API keys are encrypted at rest using AES-256 and are never exposed to the frontend client.

Local Model BYOK

BYOK subscribers can connect their own locally running Ollama instance to Forge Lab. When enabled, all chat requests are routed to your local model. No API costs, full privacy, your hardware.

Zero API Cost

Inference runs entirely on your GPU. No tokens consumed, no charges. As many messages as you want.

Compatible Modes

Works with Single Chat and the Audit Loop. Brain Mode is automatically disabled when Local Model is active.

Any Ollama Model

Pull any model from the Ollama library: qwen3:8b, llama3.2, mistral, gemma3, and many more.

Tunnel Support

Use a Cloudflare tunnel to expose your local Ollama to the internet. The URL is configurable in Settings.

Setup Steps

1. Install Ollama
Download from https://ollama.com/download (Windows, macOS, Linux).

2. Pull a model

ollama pull qwen3:8b

3. Start Ollama with external access

# Windows
set OLLAMA_ORIGINS=*
set OLLAMA_HOST=0.0.0.0
ollama serve

# macOS / Linux
export OLLAMA_ORIGINS=*
export OLLAMA_HOST=0.0.0.0
ollama serve

4. Create a public tunnel (only needed if Ollama is on a different machine than your browser)

Download cloudflared from GitHub releases: https://github.com/cloudflare/cloudflared/releases/latest
Windows: get cloudflared-windows-amd64.exe (not the .pkg, that's macOS). Place it e.g. in C:\cloudflared\, then run:

C:\cloudflared\cloudflared-windows-amd64.exe tunnel --url http://localhost:11434

Copy the https://xxx.trycloudflare.com URL. It changes every time you restart cloudflared, so update it in Settings accordingly.

5. Configure in Settings
Go to Settings → Local Model, enter the tunnel URL and model name, save, then enable the toggle. Use Test Connection to verify.

Important: Brain Mode is not compatible with Local Model and will be automatically disabled when Local Model is active.