Quickstart

This guide starts the local preview path: AgentHub Desktop -> Local Edge -> Runtime Adapter. It is the smallest path to verify before testing Hub, Web, or Feishu/Lark integration.

Prerequisites

Prepare:

• 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:

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 your 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 must expose a health check that reports process, runtime, and workspace allowlist 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. Do not confuse the UI dev-server port with the Edge port.

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, transcript, diff, and artifact preview are visible, move on to write tasks and approval flows.

Expected first-run evidence:

If the mock runtime works but a real runtime fails, treat it as a local CLI or credential issue first. Do not move provider keys into the website, docs, or browser storage just to make the preview pass.

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: allowlisted 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. Public website pages and public docs should keep only redacted status notes.

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:

Common failures and first actions:

Step 5: Add Hub Or Web

After the local path works:

• Use Hub Server when you need identity sessions, projects, devices, sync, routing, and audit.
• Use Web when you need a Hub-backed collaboration preview surface.
• Do not make Web bypass Hub to access Local Edge or local files.
• Treat full Web + Hub + Edge routing as 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, project, device, 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 events, card actions, H5/workbench entry, and TokenDance ID binding. It is not the product login system.

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.

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.