Hub And Edge
AgentHub splits collaboration from execution. Hub owns identity, projects, routing, and audit. Edge owns local workspaces, runs, runtime adapters, diffs, artifacts, and approvals.
Responsibility Split
| Capability | Hub Server | Edge Server |
|---|---|---|
| TokenDance ID login | Consumes OIDC result and creates product session | Does not own user login |
| Project membership | Owns project, member, role, and route policy | Receives authorized target decisions |
| Device and target routing | Authorizes which Desktop/Web/integration entry may reach which Edge | Advertises health, target, and workspace capabilities |
| Workspace access | Stores policy and audit state | Enforces allowlist near the filesystem |
| Runtime execution | Tracks task and run metadata | Starts, cancels, and observes runtime adapters |
| Files, diffs, artifacts | Stores shareable audit/review facts | Produces local facts and approval events |
| Secrets | Keeps product signing and integration secrets server-side | Uses local/runtime secrets from controlled local environment |
Local Edge Mode
Local Edge is the default development and personal execution mode. It runs on loopback, sits near the workspace, and should be reachable by Desktop only through a configured local URL.
Local Edge should enforce:
- workspace allowlists;
- approval policy for writes, shell, network, and publish actions;
- runtime adapter availability;
- run lifecycle and cancellation;
- local artifact and diff boundaries;
- safe event streaming to Desktop.
Hub-Backed Web Mode
Web is a Hub-backed collaboration surface. It can show projects, tasks, session history, review state, and audit facts, but it should not directly start local CLI processes or read local files.
The correct path is:
- User signs in through TokenDance ID.
- Hub creates an AgentHub product session.
- Web asks Hub for project and task state.
- Hub authorizes a target Edge when a task needs execution.
- Edge streams events and artifacts back through the authorized route.
- Hub stores the reviewable and auditable summary.
Remote And Cloud Edge
Remote/Cloud Edge is still in development. Do not document it as generally available until these facts are proven:
| Requirement | Expected proof |
|---|---|
| Device identity | Edge registration, key rotation, and revoke path |
| Target authorization | Hub policy decides who can route to the Edge |
| Workspace policy | Allowlist and tenant/project boundaries are enforced |
| Relay behavior | Failure modes are explicit and observable |
| Audit trail | User, project, run, target, approval, and artifact state are recorded |
| Degraded state | Web/Desktop show unavailable, unauthorized, timed out, and cancelled states clearly |
Integration Entries
Feishu/Lark, future IM entries, and automation triggers should enter through an Integration Gateway or Hub API, not directly into Edge.
Integration entries must:
- verify webhook signatures or app credentials;
- resolve TokenDance ID binding;
- create Hub tasks asynchronously when work is slow;
- avoid storing provider secrets or workspace paths in cards;
- route to Edge only after Hub authorization.
Event Contract
Edge should normalize runtime output into stable product events. Minimum useful groups:
| Group | Examples |
|---|---|
| Run lifecycle | run.started, run.completed, run.failed, run.cancelled |
| Messages | run.message.delta, run.message.completed |
| Tools | run.tool.call, run.tool.result, run.tool.failed |
| Review | run.diff.ready, run.artifact.ready, run.approval.requested, run.approval.resolved |
| Runtime state | runtime.unavailable, runtime.timeout, schema.validation_failed |
Events should carry enough IDs to correlate user, project, run, agent, sequence, timestamp, and versioned payload without leaking local secrets.
Debugging Boundary
When a workflow fails, identify the owner before changing code:
| Symptom | Likely owner |
|---|---|
| Login succeeds but API is unauthorized | Hub session or product authorization |
| Web cannot read local files | Expected boundary; use Desktop + Edge |
| Desktop cannot connect | Local Edge health, port, or URL |
| Runtime produces no events | Edge adapter, local CLI, provider credential, or event schema |
| Feishu card times out | Integration Gateway ack/queue path |
| Remote target unavailable | Hub route policy, Edge registration, or relay state |