Quick Start

Get Forgexa running in under 5 minutes.

Prerequisites

• Docker & Docker Compose
• Git
• One supported AI agent CLI: Claude Code, Codex, GitHub Copilot, Gemini CLI, OpenCode, Kimi Code, MiMo Code, Qwen Code, CodeBuddy, Qoder CLI, TraeCode CLI, ZCode, or the gated DeepSeek Harness preview

MiMo Code (mimo, v0.1.14+), Qwen Code (qwen, v0.24.1+), CodeBuddy (codebuddy, v2.156.0+), Qoder CLI (qoder, v1.1.59+), TraeCode CLI (trae), and ZCode (zcode) are explicit Runtime and AgentHost integrations. Configure authentication, endpoint, and model selection in their local CLI profiles on the machine that runs them; Forgexa never stores or overrides those settings. They are never selected by automatic routing or the default fallback chain. CodeBuddy and Qoder completed their local AgentHost start/resume gates; TraeCode CLI and ZCode remain gated pending real live acceptance.

DeepSeek Harness (deepseek, exactly 0.2.0-rc.2) is the seventh explicit integration for Desktop/personal Runtimes. It uses a managed home and read-only external credentials, with fixed-build/Node/platform acceptance. It is not automatically routed; native Windows and shared pools stay blocked. Follow Harness installation before choosing it.

1. Clone and Start

git clone <your-repo-url> forgexa
cd forgexa

# Start all services (API, Web, PostgreSQL, Redis, MinIO)
docker compose up -d

The web UI will be available at http://localhost:3000 and the API at http://localhost:8000.

2. Login

Default admin credentials:

• Email: admin@example.com
• Password: admin123

# Via Forgexa CLI (recommended)
forgexa login --server http://localhost:8000 --email admin@example.com --password admin123

3. Create an Organization

After logging in, create an organization to manage your team:

1. Click the organization selector (top-left)
2. Click Create Organization
3. Enter an organization name (e.g., "My Team")
4. You're now the organization Owner

TIP

An organization is the top-level container. You'll create workspaces inside it to organize projects.

4. Start a Daemon

The daemon runs on your host machine and executes AI agent tasks:

# Set environment variables
export DAEMON_SERVER_URL=http://localhost:8000
export DAEMON_API_TOKEN=<your-token>

# Start the daemon
forgexa daemon start

The daemon will:

1. Discover installed agent CLIs (claude, codex, copilot, gemini, opencode, kimi, mimo, qwen, codebuddy, qoder, trae, zcode, and deepseek)
2. Register with the API server
3. Start polling for tasks

MiMo Code (mimo, v0.1.14+), Qwen Code (qwen, v0.24.1+), CodeBuddy (codebuddy, v2.156.0+), Qoder CLI (qoder, v1.1.59+), TraeCode CLI (trae), and ZCode (zcode) are selected explicitly when needed; automatic routing and default fallback chains use the other six standard candidates.

Configure each explicit local CLI on the Runtime or AgentHost machine before assigning it to a node, execution, or workflow policy. Authentication, endpoint, and model remain local to that CLI profile; Forgexa does not transfer those settings through the platform. CodeBuddy and Qoder run with empty settings sources, strict MCP, and a fixed tool policy. Generic LLM Integrations remain separate and serve application features such as requirement preprocessing and knowledge Q&A.

5. Create a Project

1. Open the Web UI → select your workspace → Projects → New Project
2. Fill in project details:
   • Name, project key
   • Tech stack (e.g., ["python", "fastapi"])
   • Git repository URL (optional)
3. Save

6. Submit a Requirement

1. Navigate to your project → Requirements → New Requirement
2. Enter a natural language requirement:

   "Create a REST API endpoint for user registration with email validation and password hashing"

3. Click Analyze — AI will generate a structured specification
4. Review and Approve the requirement

7. Generate and Run a Plan

1. After requirement approval, click Generate Plan
2. Review the generated plan (work items, execution nodes)
3. Click Approve Plan — this confirms the plan for execution
4. The execution will start automatically if a daemon is online

8. Monitor Execution

• Executions page — watch the pipeline progress (design → coding → testing → review)
• Board page — track work items across Kanban columns
• Gates page — review and approve quality gates when prompted

What's Next

• Organization Management — manage teams, invitations, budgets
• Installation Guide — detailed deployment options
• Basic Workflow — deep dive into the development lifecycle
• WORKFLOW.md Configuration — customize agent behavior