AI Agent Installation Guide

Forgexa orchestrates 13 AI coding agent integrations, including the DeepSeek Harness developer preview. Platform support varies: Harness is gated on macOS, requires bubblewrap and local acceptance on Linux, and is not enabled in native Windows.

Install at least one agent per Runtime machine. Authentication remains local. Harness is an exception to user-managed runtime configuration: Forgexa owns an isolated runtime profile and may read an operator-approved credential file without copying or modifying its secrets. See Installation for daemon setup.

Supported Agents at a Glance

#	Agent	CLI Binary	Min Version	Routing	macOS	Linux	Windows
1	Claude Code	claude	2.0.0	Auto	Native	Native	Native / WSL2
2	OpenAI Codex	codex	0.147.0	Auto	Native	Native	WSL2 (recommended)
3	GitHub Copilot CLI	copilot	1.0.70	Auto	Native	Native	Native
4	Gemini CLI	gemini	—	Auto	Native	Native	Native
5	OpenCode	opencode	1.4.0	Auto	Native	Native	Native (npm) / WSL2
6	Kimi Code	kimi	0.18.0	Auto	Native	Native	WSL2
7	MiMo Code	mimo	0.1.14	Explicit	Native	Native	WSL2
8	Qwen Code	qwen	0.24.1	Explicit	Native	Native	Native (npm)
9	CodeBuddy Code	codebuddy	2.156.0	Explicit	Native	Native	Native (npm)
10	Qoder CLI	qoder	1.1.59	Explicit	Native	Native	WSL2
11	TraeCode CLI	traecli	—	Explicit	Native	Native	WSL2
12	ZCode	zcode	—	Explicit	Native	Native	WSL2
13	DeepSeek Harness	dsh	Exactly 0.2.0-rc.2	Explicit	Build acceptance	bubblewrap + local acceptance	Not enabled

Routing modes:

• Auto — the six standard candidates. Forgexa's RouterAgent can select them automatically and include them in fallback chains (e.g. when an agent hits a rate limit).
• Explicit — the last seven. They are excluded from automatic routing and default fallback chains. Harness is limited to Desktop and personal Runtimes; an explicit policy fallback entry counts as intentional selection.

Why these minimums? Each floor is set only where there is verified evidence that Forgexa's integration depends on a feature introduced by that version — not invented:

Agent	Floor	Verified Reason
Claude Code	2.0.0	Agent-mode design gate: the stream-json + --resume + permission-skipping stack is specified against Claude Code 2.x
Codex	0.147.0	Live-verified on 0.147.0; the 0.125.0 npm package ships an empty vendor dir and cannot run
Copilot CLI	1.0.70	Includes the one-shot auth persistence fixes required by the AgentHost
OpenCode	1.4.0	--dangerously-skip-permissions (headless runs must not block on interactive prompts) was added in v1.4.0; v1.2.27 is known broken with Forgexa
Kimi Code	0.18.0	Non-interactive auto-approval via bare -p (no --yolo) and the current on-disk auth/session layout both assume 0.18.0+
MiMo Code	0.1.14	mimo run --format json protocol and the non-interactive permission flag were introduced in 0.1.14
Qwen Code	0.24.1	Verified stream-json event envelope and native --resume support
CodeBuddy	2.156.0	Verified headless stream-json protocol, native --resume, and setting-source isolation
Qoder CLI	1.1.59	Verified headless stream-json protocol, native --resume, and setting-source isolation
Gemini CLI	—	No hard floor; L1 compatibility level
TraeCode CLI	—	No version floor; readiness is gated by the real-account live gate instead
ZCode	—	No version floor; readiness is gated by binary fingerprint approval + protocol acceptance instead
DeepSeek Harness	Exactly 0.2.0-rc.2	Matching CLI, headless, base, extension, Node and platform fingerprint acceptance required

Prerequisites (All Platforms)

• Node.js ≥ 18 (20 LTS recommended) — required by the npm-based agents (claude, codex, copilot, gemini, qwen, codebuddy, opencode). Check with node --version.
• Harness requires Node 22.19+ within 22.x, or Node 24+; Node 20 and 23 do not meet its requirement.
• A package manager where applicable: Homebrew (macOS), the system package manager (Linux), or npm.
• Network access to each agent's authentication endpoint (browser OAuth flows open a local browser).
• The user running the Forgexa daemon must be the same user that completed the agent login.

Windows: Native vs WSL2

Windows users have two viable paths:

1. Native (Windows 10+) — for npm-based agents that officially support Windows: Claude Code, GitHub Copilot CLI, Gemini CLI, OpenCode, Qwen Code, CodeBuddy Code. Install Node.js for Windows, then use the same npm install -g commands in PowerShell.
2. WSL2 — for script-based installers that target macOS/Linux (Codex, Kimi Code, MiMo Code, Qoder CLI, TraeCode CLI, ZCode). Install WSL2 with Ubuntu 22.04+, then follow the Linux instructions inside the WSL distro.

Same-side principle

The agent must run in the same environment as the Forgexa daemon and the workspace it operates on. If your workspace lives in WSL, the daemon and agents must also run inside that WSL distro — a Windows-side agent cannot see WSL-side workspaces (and vice versa). This matters for Desktop users enabling WSL workspaces: install the agents inside the distro, not on the Windows side.

macOS GUI note

On macOS, an app launched from Dock/Finder does not inherit shell exports. If an agent needs an environment variable, launch the Desktop app once from Terminal, or persist it with launchctl setenv <VAR> "<value>" (re-apply after reboot).

---

Claude Code (Anthropic)

Anthropic's agentic coding tool that lives in your terminal.

• Website: https://claude.com/product/claude-code
• Docs: https://code.claude.com/docs
• Repository: https://github.com/anthropics/claude-code

macOS / Linux

# Native installer (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# Or via npm
npm install -g @anthropic-ai/claude-code

Windows

# Native installer (PowerShell)
irm https://claude.ai/install.ps1 | iex

# Or via npm (requires Git for Windows for the Bash tool)
npm install -g @anthropic-ai/claude-code

WSL2 is also officially supported — follow the Linux instructions inside the distro.

Authorization

claude

The first run opens a browser to sign in with a Claude account (Pro/Max subscription) or Anthropic Console account. For server/daemon machines without a browser, generate a long-lived token first:

claude setup-token   # creates a CLAUDE_CODE_OAUTH_TOKEN for headless use

Alternatively set ANTHROPIC_API_KEY (Console billing) as an environment variable.

Verify

claude --version    # Forgexa requires >= 2.0.0

---

OpenAI Codex

OpenAI's open-source coding agent.

• Website: https://developers.openai.com/codex
• Repository: https://github.com/openai/codex

macOS

brew install codex
# or
npm install -g @openai/codex

Linux

npm install -g @openai/codex

Windows

Official documentation recommends WSL2: install Codex inside the distro using the Linux command above. Check the GitHub releases page for native Windows builds if you prefer a non-WSL setup.

Authorization

codex login

Signs in with a ChatGPT account (Plus, Pro, Team, or Enterprise) via browser OAuth. For API-billing setups instead:

codex login --api-key   # or export OPENAI_API_KEY

Verify

codex --version    # Forgexa requires >= 0.147.0

---

GitHub Copilot CLI

GitHub's official Copilot agent for the terminal, billed through your Copilot subscription.

• Website: https://github.com/features/copilot/cli
• Docs: https://docs.github.com/en/copilot

macOS / Linux / Windows

npm install -g @github/copilot

Windows PowerShell works natively — no WSL needed.

Authorization

copilot

The first run starts a GitHub device-code sign-in in the browser. An active Copilot subscription (Pro, Business, Enterprise, or free tier with limits) is required on the account.

Verify

copilot --version    # Forgexa requires >= 1.0.70 (auth persistence fixes)

---

Gemini CLI (Google)

Google's open-source AI agent for the terminal, powered by Gemini models.

• Website: https://google-gemini.github.io/gemini-cli
• Repository: https://github.com/google-gemini/gemini-cli

macOS / Linux / Windows

npm install -g @google/gemini-cli

macOS also: brew install gemini-cli. Windows PowerShell works natively.

Authorization

gemini

The first run prompts a Google account sign-in (browser OAuth). A personal Google account includes a free usage tier. For API-billing setups, export GEMINI_API_KEY from Google AI Studio; Vertex AI is also supported via its own settings.

Verify

gemini --version

---

OpenCode

Open-source AI coding agent (provider-agnostic — bring your own model provider).

• Website: https://opencode.ai
• Repository: https://github.com/sst/opencode

macOS / Linux

curl -fsSL https://opencode.ai/install | bash
# or
npm install -g opencode-ai
# macOS also: brew install sst/tap/opencode

Windows

npm install -g opencode-ai

Native npm works; WSL2 is a solid alternative if you prefer the script installer.

Authorization

opencode auth login

Select your provider (Anthropic, OpenAI, Google, etc.) and complete the browser OAuth or paste an API key. OpenCode supports multiple providers in one profile.

Verify

opencode --version    # Forgexa requires >= 1.4.0

---

Kimi Code (Moonshot)

Moonshot AI's terminal coding agent powered by Kimi models.

• Website: https://code.kimi.com

macOS / Linux

curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash

Windows

Use WSL2 — run the Linux installer inside the distro. Check the official site for native Windows availability.

Authorization

kimi

The first run opens a browser to sign in with a Kimi account. API-key configuration (Moonshot OpenAPI) is available in the CLI settings for headless machines.

Verify

kimi --version    # Forgexa requires >= 0.18.0

---

MiMo Code (Xiaomi)

Xiaomi's terminal coding agent. In Forgexa this integration is explicit-selection only (excluded from auto-routing and fallback chains).

• Website: https://mimo.xiaomi.com

macOS / Linux

curl -fsSL https://mimo.xiaomi.com/install | bash

Windows

Use WSL2 — run the Linux installer inside the distro. Check the official site for native Windows availability.

Authorization

mimo

Complete the first-run login flow with a MiMo account in the browser.

Verify

mimo --version    # Forgexa requires >= 0.1.14

---

Qwen Code (Alibaba)

Qwen's terminal coding agent, forked from the Gemini CLI architecture.

• Repository: https://github.com/QwenLM/qwen-code
• Docs: https://qwenlm.github.io/qwen-code-docs/

macOS / Linux / Windows

npm install -g @qwen-code/qwen-code

Windows PowerShell works natively.

Authorization

qwen

The first run offers Qwen OAuth sign-in (free tier via a chat.qwen.ai account). For API-billing, export OpenAI-compatible credentials pointed at Alibaba Cloud Model Studio / DashScope:

export OPENAI_API_KEY="<your-key>"
export OPENAI_BASE_URL="<compatible-endpoint>"

Optionally enable the sandbox for safer execution: qwen sandbox --sandbox.

Verify

qwen --version    # Forgexa requires >= 0.24.1

---

CodeBuddy Code (Tencent)

Tencent's terminal coding agent. Explicit-selection only in Forgexa.

• Website: https://www.codebuddy.ai

macOS / Linux / Windows

npm install -g @tencent-ai/codebuddy-code

Windows PowerShell works natively.

Authorization

codebuddy login

Signs in with a Tencent Cloud / CodeBuddy account via browser OAuth.

Verify

codebuddy --version    # Forgexa requires >= 2.156.0

---

Qoder CLI (Alibaba)

Agentic coding CLI from the Qoder team. Explicit-selection only in Forgexa.

• Website: https://qoder.com

macOS / Linux

curl -fsSL https://qoder.com/install | bash

Windows

Use WSL2 — run the Linux installer inside the distro, or check the official site for a native Windows installer.

Authorization

qoder

Complete the first-run browser login with a Qoder account.

Verify

qoder --version    # Forgexa requires >= 1.1.59

---

TraeCode CLI (Trae)

The Trae terminal coding agent (字节跳动 Trae 团队). Explicit-selection only in Forgexa.

• Website (CN): https://trae.cn
• Website (International): https://trae.ai

macOS / Linux

sh -c "$(curl -fsSL https://trae.cn/trae-cli/install_v2.sh)"

International users may use the corresponding installer on https://trae.ai.

Windows

Use WSL2 — run the Linux installer inside the distro, or check the official site for a native Windows installer.

Authorization

traecli login

Browser OAuth with a Trae account (CN or international, matching the installer source).

Forgexa readiness gate

Forgexa keeps TraeCode CLI not-ready until it passes the real-account live gate — after installing and logging in, confirm the Runtime page shows it ready before assigning tasks to it.

Verify

traecli --version

---

ZCode (Z.ai)

Z.ai's coding agent, integrated by Forgexa over the app-server protocol. Explicit-selection only.

• Website: https://z.ai
• Repository: https://github.com/zai-org/ZCode

macOS / Linux / Windows

Install from the GitHub releases page — pick the archive for your platform. On Windows without a native build, use WSL2.

Authorization

zcode login

Browser OAuth with a Z.ai account.

Forgexa-specific steps (recommended):

# Approve the installed binary's fingerprint into the persistent allowlist
# (visible to GUI-launched desktop/daemons, no restart needed)
forgexa zcode approve-build

# Alternative: environment variable (only effective for processes that can read it)
export FORGEXA_ZCODE_ALLOWED_SHA256="<approved-zcode-sha256>"

# Optional: give Forgexa a dedicated ZCode profile directory
export FORGEXA_ZCODE_HOME="$HOME/.forgexa/zcode"
HOME="$HOME/.forgexa/zcode" zcode login   # one login inside the dedicated profile

# Optional: pin the model if the profile has no persisted default
export FACTORY_ZCODE_MODEL="<providerId/modelId>"

Verify

zcode --version

---

DeepSeek Harness (Developer Preview)

• Website: https://www.deepseek.com/harness/
• Repository: https://github.com/deepseek-ai/deepseek-harness
• Agent ID: deepseek; binary: dsh. This is not a DeepSeek model for OpenCode or a generic LLM Integration.

deepseek is the canonical ID. The previous deepseek-harness ID remains an input compatibility alias for CLI, workflow, API and Desktop sessions; new selections and responses use deepseek. Existing deepseek-harness home/approval paths, FACTORY_DEEPSEEK_HARNESS_* variables and native handles remain unchanged. Upgrade/restart the server and the runtime or Desktop to load the renamed integration; the server preserves the reported legacy wire ID when dispatching to an older daemon.

Global installation is recommended for PATH-based discovery:

node --version
npm i -g @deepseek-ai/dsh@0.2.0-rc.2
dsh --version

Alternatively use an isolated tools directory, not business-project dependencies:

npm install --prefix "$HOME/.forgexa/tools/deepseek-harness" --save-exact @deepseek-ai/dsh@0.2.0-rc.2
export FACTORY_DEEPSEEK_HARNESS_PATH="$HOME/.forgexa/tools/deepseek-harness/node_modules/.bin/dsh"

Discovery never downloads through npx. macOS uses /usr/bin/sandbox-exec; Linux needs working bwrap, including user-namespace permissions. WSL follows the same-distro Linux path and still needs local acceptance, not a native Windows guarantee.

Complete official Harness authentication locally. Forgexa reads DEEPSEEK_API_KEY or an external credential file, defaulting to $DSH_HOME/.credentials.yaml or ~/.dsh/.credentials.yaml. When no key is present, an operator-configured DeepSeek account grant is supported. No failed request silently switches providers. FACTORY_DEEPSEEK_HARNESS_CREDENTIALS selects an absolute credential file path; FACTORY_DEEPSEEK_HARNESS_MODEL selects a supported model ID (default deepseek-flash). The Messages endpoint is fixed to https://api.deepseek.com/anthropic, not an arbitrary OpenAI-compatible endpoint. Renew expired credentials through the official CLI outside a task.

Each canonical workspace owns ~/.forgexa/agents/deepseek-harness/<workspace-hash>, a serialized profile lock and a private run overlay. Personal patches/plugins are not imported. The sole preset is workspace-write + never: escalation is rejected, not automatically approved. Outer supervision denies writes outside the workspace/managed state and to Git metadata, session bindings and the credential file. This is not same-UID secret-read or network isolation; use trusted workspaces or a dedicated OS account/VM for untrusted input.

Session-log upload, plugin inventory upload and OTel extensions are separately disabled. Ordinary model requests still send prompts and selected code to DeepSeek; this is not total network silence.

After live start/resume/cancel/isolation acceptance for the exact build:

forgexa agent approve-live deepseek
forgexa check --agent deepseek --quick
forgexa check --agent deepseek

Approval records an operator attestation, not an automatic test. --quick makes no model call; normal check runs a potentially billable minimal task, not the full acceptance checklist. Build, OS/Node and runtime-policy changes invalidate approval. A changed build/provider/model/composition rejects native resume; start a new session. Only a proven missing log before turn start can cause one fresh-session retry.

Harness emits committed JSONL blocks, not token deltas. Success requires session/turn-end/final plus exit 0; cancellation/timeout wins over native exit 0. The supervisor enforces a 4 MiB output budget. Image, native fork, read-only review and parallel flags remain disabled. Shared pools and automatic routing are not enabled.

Verify Your Installation

Run through the agents you installed — each command must exit 0 and print a version:

claude --version
codex --version
copilot --version
gemini --version
opencode --version
kimi --version
mimo --version
qwen --version
codebuddy --version
qoder --version
traecli --version
zcode --version
dsh --version

Then restart the Forgexa daemon (or the Desktop app) so it re-discovers agents, and check Runtimes in the web console: each installed agent should appear under the runtime's agent list. See Installation → Start the Daemon for daemon startup and Runtimes & Agents API for programmatic checks.

Troubleshooting

Symptom	Likely Cause	Fix
Agent not listed on the Runtime page	Installed after daemon start	Restart the daemon so it re-scans PATH
command not found from daemon tasks	Agent installed under a different user / non-login shell	Install with the same user that runs the daemon; ensure the binary is on that user's PATH
macOS tasks fail to see export vars	GUI-launched app doesn't inherit shell env	Use launchctl setenv (see tip above) or launch from Terminal
Auth errors mid-execution (401)	Token expired / login done under another user	Re-run the agent's login command as the daemon user on the runtime machine
TraeCode CLI stays not-ready	Real-account live gate not passed	Complete login, then re-check the Runtime page
ZCode rejected on start	Binary fingerprint not approved	Run forgexa zcode approve-build
Harness installed but not ready	Unknown build/platform or acceptance pending	Use exactly 0.2.0-rc.2 and attest the verified build; native Windows stays blocked
Harness native resume rejected	Changed composition or unowned session	Start a new session; do not delete logs or reuse personal sessions
Windows agent can't see WSL workspace	Same-side principle violated	Install the agent inside the WSL distro (see above)