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.
Scope
These steps describe a developer workstation. Public docs must not include private deployment hosts, SSH aliases, provider keys, or production rollback paths.
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 | Node.js 20+ and pnpm | Install frontend dependencies and run local previews |
| 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 introduce 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, not every private or fast-moving local command.
After setup, inspect the repository layout:
| Path | Role |
|---|---|
app/desktop | Desktop UI for local workspaces and Local Edge |
app/web | Hub-backed Web workbench |
edge-server | Local execution, runtime adapters, diffs, artifacts, approvals |
hub-server | TokenDance ID sessions, projects, devices, 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 |
Do not paste provider keys into the website, browser local storage, docs, issue comments, or Feishu/Lark card payloads. Real keys belong in the local shell environment or a server-side secret store, depending on the runtime owner.
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, often localhost:5173 | Use the terminal output if the port changes |
| Web dev server | Next/Vite-assigned | Web should call Hub, not Local Edge directly |
| Hub Server | Repository-defined local port | Use only when testing sessions, projects, devices, audit, or routing |
If a port is already occupied, choose another local port and update the matching client configuration. Do not change public docs to hard-code a private operator port.
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.