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

# Or MiMo Code (explicit selection, v0.1.14+)
curl -fsSL https://mimo.xiaomi.com/install | bash
mimo --version

# Or Qwen Code (explicit Runtime selection, v0.24.1+)
npm install -g @qwen-code/qwen-code
qwen --version
qwen sandbox --sandbox

# Or CodeBuddy (explicit Runtime selection, v2.156.0+)
npm install -g @tencent-ai/codebuddy-code
codebuddy --version

# Or Qoder CLI (explicit Runtime selection, v1.1.59+)
curl -fsSL https://qoder.com/install | bash
qoder --version

# Or TraeCode CLI (explicit Runtime selection; complete the official login first)
sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"
traecli --version

# Or ZCode (explicit Runtime selection; uses the app-server protocol)
zcode --version
# Build approval (recommended): one command writes the installed binary's fingerprint
# into the persistent allowlist (~/.forgexa/zcode-allowed-sha256, visible to
# GUI-launched desktop/daemons, no restart needed):
forgexa zcode approve-build
# Alternative: only effective for processes that can read this export:
export FORGEXA_ZCODE_ALLOWED_SHA256="<approved-zcode-sha256>"
# Optional: point Forgexa's ZCode protocol profile at a dedicated directory
export FORGEXA_ZCODE_HOME="$HOME/.forgexa/zcode"
# First use requires one official login in the Forgexa-dedicated profile (browser OAuth; desktop credentials are not shared):
HOME="$HOME/.forgexa/zcode" zcode login
# If that profile has no persisted default model, set ZCode's picker-format selection:
export FACTORY_ZCODE_MODEL="<providerId/modelId>"

Tip: on macOS, an app launched from Dock/Finder does not inherit shell exports. Launch the app once from Terminal, or run launchctl setenv FORGEXA_ZCODE_ALLOWED_SHA256 "<approved-zcode-sha256>" (must be re-applied after reboot) before starting it.

The daemon discovers thirteen integrations: Claude Code, Codex, GitHub Copilot, Gemini CLI, OpenCode, Kimi Code, MiMo Code, Qwen Code, CodeBuddy, Qoder CLI, TraeCode CLI, ZCode, and DeepSeek Harness. Six are standard automatic candidates; seven require explicit selection. The other local CLIs retain user-managed authentication/settings; Harness instead owns a managed runtime home with a read-only external credential reference. TraeCode CLI and ZCode retain their existing readiness gates.

For the Harness developer preview, install globally with npm i -g @deepseek-ai/dsh@0.2.0-rc.2, use Node 22.19+ within 22.x or Node 24+, then complete exact-build start/resume/cancel/isolation acceptance before forgexa agent approve-live deepseek. Desktop/personal Runtimes only; macOS requires sandbox-exec, Linux requires working bwrap, and native Windows/shared pools are not enabled. See the Harness setup and limits.

For per-agent platform-specific install and authorization guides (macOS / Linux / Windows, official links, minimum versions), see AI Agent Installation Guide.

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

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