Installation

Deployment Options

Option 1: Docker Compose (Recommended)

git clone <your-repo-url> forgexa
cd forgexa
docker compose up -d

This starts:

Service	Port	Description
api	8000	FastAPI backend
web	3000	React frontend (Nginx)
postgres	5432	PostgreSQL 16 + pgvector
redis	6379	Redis 7 (event bus)
minio	9000/9001	MinIO (artifact storage)
pgadmin	5050	pgAdmin (optional)

Option 2: Host Mode

For development, run the backend and frontend directly on your host:

# Backend
cd backend
pip install -e ".[dev]"
uvicorn app.main:app --reload --port 8000

# Frontend
cd frontend
npm install
npm run dev

Runtime Daemon Setup

The daemon runs on any machine where AI agents are installed.

Prerequisites

Install at least one AI coding agent:

# Claude Code (recommended)
npm install -g @anthropic-ai/claude-code

# Or Codex
npm install -g @openai/codex

# Or OpenCode
go install github.com/opencode-ai/opencode@latest

Start the Daemon

# Required environment variables for local/self-hosted server
export DAEMON_SERVER_URL=http://your-server:8000
export DAEMON_API_TOKEN=your-api-token

# Optional
export DAEMON_MAX_CONCURRENT=5         # Max parallel tasks
export DAEMON_POLL_INTERVAL=3          # Poll interval (seconds)
export DAEMON_WORKSPACES_ROOT=~/.ai-factory/workspaces

# Start
forgexa daemon start

Multi-Server Mode

A single daemon can connect to multiple API servers:

export DAEMON_SERVER_URLS=http://server1:8000,http://server2:8000
forgexa daemon start

CLI Installation

Install the standalone CLI package:

pip install forgexa-cli

# Login
forgexa login --server http://localhost:8000 --email admin@example.com --password admin123

# Check daemon status
forgexa daemon status

Environment Variables

API Server

Variable	Default	Description
DATABASE_URL	postgresql+asyncpg://...	PostgreSQL connection
REDIS_URL	redis://localhost:6379	Redis connection
SECRET_KEY	(required)	JWT signing key
LITELLM_MODEL	claude-sonnet-4-20250514	Model for AI analysis

Daemon

Variable	Default	Description
DAEMON_SERVER_URL	https://api.forgexa.net	API server URL
DAEMON_API_TOKEN	(optional)	Authentication token (auto-read from CLI login config when available)
DAEMON_MAX_CONCURRENT	5	Max parallel tasks
DAEMON_POLL_INTERVAL	3	Poll interval (seconds)
DAEMON_ID	hostname	Unique daemon identifier
FACTORY_CLAUDE_MODEL	(none)	Override Claude model