Quickstart

This guide helps you run the local preview path: Desktop connects to Local Edge, you add a runtime adapter, and optionally add Web. Mobile follows a separate path.

Prerequisites

You need:

• Git, Go 1.25+, Node.js 20+, and pnpm.
• The AgentHub source repository.
• One runtime you can run locally, such as Claude Code, Codex, OpenCode, or the mock runtime.
• Model provider credentials in your local environment when using a real runtime.

Keep model API keys in local environment variables or server-side secret storage. Do not place them in public docs, frontend code, Feishu card payloads, or browser storage.

Step 1: Clone AgentHub

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

On macOS or Linux, follow the setup script or README in the AgentHub repository for the equivalent local dependency setup.

After cloning, confirm which subsystem you are working in:

Path	Role	Needed for this guide
app/desktop	Desktop UI (Tauri 2) and main local execution entry	Yes
app/web	Hub-backed Web collaboration surface (port 5174)	Optional
app/shared	Shared workbench UI components used by Desktop and Web	Read
app/mobile	Expo React Native mobile client (port 5177)	Separate path
edge-server	Local Edge for workspaces, runs, adapter registry, and event log	Yes
hub-server	Hub API for sessions, projects, messages, agent collaboration, and audit	Optional
api/	OpenAPI, event vocabulary, and protocol conventions	Read

Step 2: Start Local Edge

From the AgentHub repository:

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

Use the mock runtime first if you only need to verify UI, events, and diff rendering. After the UI path is healthy, switch to a real runtime:

go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile claude-code --agent-default claude-code
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile codex --agent-default codex
go run ./cmd/agenthub-edge --addr 127.0.0.1:3210 --runner-profile opencode --agent-default opencode

--runner-profile selects the compatibility runtime preset. --agent-default selects the default adapter when a run does not specify agentId. The real CLI must already be installed and authenticated in the local shell.

Run a minimal health check after startup:

curl.exe http://127.0.0.1:3210/health
curl.exe http://127.0.0.1:3210/v1/health

If one endpoint is not implemented yet, follow the current AgentHub repository README or OpenAPI, but Local Edge needs to expose a health check that explains process, runtime, and workspace state.

Step 3: Start Desktop

In a second terminal:

cd app\desktop
pnpm install
pnpm dev

Open the Desktop preview at:

http://localhost:5173

Desktop should connect to Local Edge on 127.0.0.1:3210.

If 5173 is already occupied, the dev server may choose another port. Use the local URL printed by the terminal, and confirm that Desktop is configured with the Edge URL from the previous step.

Step 3b: Start Web (Optional)

Web shares the same workbench UI as Desktop. Start it in a third terminal:

cd app\web
pnpm install
pnpm dev

Open the Web preview at:

http://localhost:5174

Web connects to Hub Server for identity and collaboration state. It does not connect to Local Edge directly. For Web to show meaningful data, Hub Server must be running with a valid TokenDance ID session.

Step 3c: Mobile Expo RN (Separate Path)

Mobile is an Expo React Native client on port 5177. Start it from the AgentHub repository:

cd app\mobile
pnpm install
npx expo start

Mobile connects to Hub Server only, sharing the same IM-form workbench design as Desktop and Web. It does not access Local Edge or local files directly. Full transcript rendering, diff review, and runtime controls are not yet available on mobile.

Step 4: Run A First Local Task

Create or select a local workspace, then ask for a small task:

Review the README and suggest the smallest documentation improvement.

For the first run, prefer a low-risk read-only request. After the event stream, conversation, diff, and results preview are visible, move to write tasks and approval flows.

Expected first-run evidence:

Surface	What to verify
Edge health	Loopback health check succeeds and lists runtime/adapter state
Desktop connection	Desktop shows the selected Local Edge as online
Conversation	The user task and agent response render without layout overflow
Events	Run start, message blocks, tool state, and terminal state are visible
Results	Diffs, file previews, and artifact panels stay read-only until the user approves write actions

If the mock runtime works but a real runtime fails, treat it as a local CLI or credential issue first.

Record the first-run evidence in a small, repeatable shape:

edge:     http://127.0.0.1:3210 health ok
desktop:  dev server url + connected edge url
runtime:  mock / claude-code / codex / opencode
workspace: redacted path, not copied into public screenshots
run:      run id, terminal status, diff/artifact presence

This evidence can live in a private PR, internal issue, or local handoff.

Known-Good Mock Run

A mock-first preview should reliably produce these public-safe signals. Exact fields follow the current AgentHub repository implementation, but the semantics should stay stable:

{
  "ok": true,
  "service": "agenthub-edge",
  "mode": "local",
  "runtimes": [
    {
      "id": "agenthub-runner-mock",
      "state": "ready"
    }
  ]
}

After creating a read-only task, the event stream should express at least these stages:

{"type":"run.started","runId":"run_123","agentId":"agenthub-runner-mock"}
{"type":"run.message.delta","runId":"run_123","payload":{"text":"Reading README"}}
{"type":"run.artifact.ready","runId":"run_123","payload":{"kind":"summary"}}
{"type":"run.completed","runId":"run_123","payload":{"status":"completed"}}

Desktop should show:

Area	Known-good state
Edge selector	127.0.0.1:3210 is online and runtime is ready
Chat	User input and mock response render without browser-blue focus boxes
Files/Diff	Read-only task does not write directly; candidate diffs enter review first
Timeline	run started, message, artifact, completed are traceable in order
Theme/Language	Switching theme/language updates the mock UI without resetting run state

Common failures and first actions:

Symptom	Likely cause	First action
Edge health connection refused	Edge is not running or uses another port	Check the Edge terminal output for the actual listen address
Desktop shows offline	Desktop still points to an old port	Update the Desktop Edge URL; do not change the UI dev-server port
mock works but real runtime is silent	CLI install, login, quota, or adapter profile issue	Run codex --version or the matching CLI self-check in the same shell
workspace denied	Workspace is outside the allowed list	Use an allowed workspace or update local Edge policy
event order is broken	Adapter event schema or replay issue	Record run id and event id; triage adapter/schema first

Step 5: Add Hub Or Web

After the local path works:

• Use Hub Server when you need identity sessions (OIDC PKCE), projects, messages, agent collaboration, sync, routing, and audit.
• Use Web (port 5174) when you need a Hub-backed IM-form collaboration preview. Web shares the same workbench UI as Desktop.
• Use Mobile (port 5177) as a separate Expo RN path for on-the-go task review and creation.
• Web and Mobile access collaboration state through Hub, not by directly connecting to Local Edge or local files.
• Full Web + Hub + Edge routing is an integration path that is still being completed.

Recommended order:

1. Keep Desktop + Local Edge passing with the mock runtime.
2. Add one real runtime adapter and confirm the same UI surfaces still work.
3. Add Hub for session, agent collaboration, project, and audit boundaries.
4. Add Web only after Hub owns the collaboration state.
5. Add remote routing or IM entry points only after Hub can authorize the target Edge.

This order keeps local execution, product authorization, and collaboration surfaces from being mixed into one hard-to-debug failure.

Step 6: Plan Feishu/Lark Integration

Feishu/Lark is a collaboration entry: bot messages, event subscriptions, card callbacks, H5/workbench entry, and TokenDance ID binding.

Before implementing or deploying Feishu/Lark flows, read Feishu/Lark Integration and Security. Production ingress, async queues, card schema, and account binding are still in development.

Step 7: Mobile Path

Mobile (Expo React Native) is a Hub-backed client that renders the IM-form chat workbench on iOS and Android. It shares the same workbench design with Desktop and Web but is a separate development track. Start with npx expo start from app/mobile/ and connect through Hub Server. Full feature parity with Desktop is not yet available.

Next Steps

• Read Concepts for terms and delivery status.
• Read Architecture for Hub, Edge, Desktop, Web, and adapter boundaries.
• Read API And Events before building clients or integration gateways.

Edit this page on GitHub