Quick Start

Get Forgexa running in under 5 minutes.

Prerequisites

• Docker & Docker Compose
• Git
• One of: Claude Code CLI, Codex CLI, or OpenCode CLI installed

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, opencode, gemini)
2. Register with the API server
3. Start polling for tasks

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