Installation

This page explains the local development setup for AgentHub Desktop, Local Edge, Hub Server, Web, and runtime adapters. Use it before the Quickstart when a machine has not run AgentHub before.

Supported Setup

AgentHub is developed as a multi-surface product. A complete local workstation usually needs:

Area	Requirement	Why it matters
Source	Git	Clone the AgentHub repository and inspect branches
Desktop/Web/Mobile	Node.js 20+ and pnpm	Install frontend dependencies and run local previews for all three clients
Edge/Hub	Go 1.25+	Run local Edge and Hub services
Runtime	Mock runtime first, then Claude Code, Codex, or OpenCode	Validate UI before real provider credentials
Browser	Chromium, Edge, or Chrome	Test Desktop/Web preview and docs pages

Use the mock runtime for first setup. Real runtimes can add unrelated CLI login, provider quota, shell, and workspace-policy failures, so they should be introduced only after the mock path is healthy.

Clone And Bootstrap

Clone the source repository and run the repository setup script:

git clone https://github.com/TokenDanceLab/AgentHub.git
cd AgentHub
.\scripts\setup.ps1

If the setup script changes, follow the AgentHub repository README. This public website describes the expected shape without duplicating every fast-moving local command.

After setup, inspect the repository layout:

Path	Role
app/desktop	Tauri 2 Desktop UI, connects to Local Edge
app/web	Hub-backed Web workbench (port 5174), shares workbench UI with Desktop
app/mobile	Expo React Native mobile client (port 5177)
app/shared	Shared workbench UI components used by Desktop and Web
edge-server	Local execution, adapter registry, event log, diffs, results, approvals
hub-server	OIDC PKCE sessions, projects, messages, agent collaboration, routing, audit
api	Public contract vocabulary and OpenAPI/event references

Runtime CLI Preparation

Runtime adapters wrap existing coding-agent tools. Prepare only the runtime you plan to test:

Runtime	Preparation
Mock	No provider credentials; best first validation target
Claude Code	Install and authenticate the local CLI in the user shell
Codex	Install and authenticate the local CLI in the user shell
OpenCode	Install and authenticate the local CLI in the user shell
Custom	Provide a local adapter implementation and safe profile

Real keys belong in the local shell environment or a server-side secret store.

Ports And Processes

Recommended local ports:

Process	Default shape	Notes
Local Edge	127.0.0.1:3210	Bind to loopback for local execution
Desktop dev server	Vite-assigned, default localhost:5173	Tauri 2 native client; port 5173 for dev
Web dev server	Vite-assigned, default localhost:5174	Web shares workbench UI with Desktop; calls Hub, not Edge directly
Mobile Expo	Expo-assigned, default localhost:5177	Expo React Native; connects to Hub only
Hub Server	Repository-defined local port	Use only when testing sessions, projects, agent collaboration, audit, or routing

If a port is already occupied, choose another local port and update the matching client configuration.

Verify The Workstation

Before running a real task, verify:

git --version
go version
node --version
pnpm --version

Then start the mock Local Edge and run a health check:

cd edge-server
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile agenthub-runner-mock
curl.exe http://127.0.0.1:3210/health

The exact health endpoint may change while Edge is converging. The required behavior is stable: Local Edge should expose process state, runtime profile state, and workspace-policy state in a safe, inspectable way.

First Failure Triage

Symptom	First check
pnpm install fails	Confirm Node.js major version and package manager from package.json
Edge does not start	Check Go version, selected runtime profile, and occupied port
Desktop cannot connect	Confirm Desktop points at the same loopback Edge URL
Mock works, real runtime fails	Check the runtime CLI installation and local login
Browser shows old docs	Use a cache-busting URL and check the deployed sitemap.xml / llms.txt

Continue with Quickstart after the workstation can start Local Edge and Desktop.

Edit this page on GitHub