System Architecture
AgentHub uses a modular, event-driven architecture that lets AI agents act as first-class collaborators across local, Web, Hub, Edge, and integration surfaces.
Delivery status
This page describes the target architecture and current component boundaries. Desktop, Local Edge, Hub, Web, and runtime adapter development paths are available for local work. Feishu/Lark production ingress, Remote/Cloud Edge, and full Web + Hub + Edge routing are still in development.
Target Topology
Data Flow
Core Components
Desktop
Desktop is the primary local execution entry point. It selects the workspace and Local Edge, renders multi-agent chat, run progress, diffs, files, and previews, and collects user approval before write, shell, or external-connection actions. When team collaboration is needed, it syncs session, device, and audit state to Hub.
Hub Server
Hub is the product collaboration and permission boundary. It consumes TokenDance ID OIDC login results, issues AgentHub product sessions, manages projects, members, devices, targets, and audit records, and decides whether Web, Desktop, or an integration entry may route work to an Edge. Hub does not hold local provider keys directly.
Web
Web is the Hub-backed collaboration surface. It shows Hub sessions, projects, and agent tasks, and uses Hub to inspect run state, review results, and coordinate team context. Web must not bypass Hub to reach Local Edge or local files directly.
Local Edge
Local Edge sits next to the filesystem and process boundary. It owns workspace allowlists, run lifecycle, runtime adapter startup/cancellation, normalized events, diffs, artifacts, file previews, the local approval bridge, and least-privilege policy. It streams local facts back to Desktop and can sync them to Hub after authorization.
Integration Gateway
Integration Gateway is the server-side boundary for Feishu/Lark and similar entries. It handles webhook challenge, signature verification, decryption, fast card.action.trigger acknowledgement, async queueing for slow AgentHub work, and minimal payload forwarding to Hub. It must not place secrets, workspace paths, or full model output into card payloads.
Agent Runtime Adapter
Each runtime is hosted through an Edge Server adapter. A runtime adapter is not the user-facing Agent Profile — it is the execution engine that profiles can bind to.
- Claude Code adapter: manages Claude Code CLI processes and structured output parsing.
- Codex adapter: integrates with Codex CLI and event streams.
- OpenCode adapter: supports provider and model routing through a unified runtime protocol.
- Custom adapter: built on the adapter SDK for team-specific engines.
Responsibility Matrix
Use this table when deciding where a feature, bug fix, or document belongs.
| Concern | Owning surface | Must not be owned by |
|---|---|---|
| Product login and account identity | TokenDance ID + Hub Server | Desktop, Web static client, Feishu/Lark OAuth directly |
| Product session, project membership, routing policy | Hub Server | Local Edge, runtime adapter, public website |
| Local workspace allowlist and process execution | Local Edge | Web browser, Hub-only pages, IM card payloads |
| Local UI for executing and approving agent work | AgentHub Desktop | Hub Server, public docs demo |
| Team-visible review, history, and routing state | Hub-backed Web | Direct browser-to-Edge calls |
| Runtime process parsing and event normalization | Runtime adapter inside Edge | Agent Profile metadata |
| Feishu/Lark webhook verification and queueing | Integration Gateway | Hub UI, Desktop, public frontend |
| Public product copy, docs, SEO, and visual QA | AgentHub Home | Private server state or live ops inventory |
When a change appears to need two owners, split the responsibility before implementing it. For example, Web can request a task through Hub, but Edge still owns filesystem access and runtime process execution. Feishu/Lark can create a Hub task, but it must not become a second login authority.
Data Ownership
AgentHub keeps data close to the component that can enforce the matching boundary.
| Data | Primary owner | Sharing rule |
|---|---|---|
| TokenDance ID subject, OIDC claims, account bindings | TokenDance ID | Hub consumes verified claims; products do not store provider OAuth secrets |
| Product session, organization, project, role, audit | Hub Server | Web/Desktop receive only authorized views |
| Workspace path, file preview, diff, artifact, terminal state | Local Edge | Public screenshots and docs use redacted or relative examples |
| Runtime CLI auth state and provider keys | Local machine or server-side secret store | Never move into browser storage, docs, IM payloads, or static bundles |
| Run event stream | Edge first, Hub sync after authorization | Unknown event fields stay versionable and clients ignore them safely |
| IM event id, tenant/user binding summary, card action id | Integration Gateway + Hub | Full prompt, secret, local path, and raw model output stay out of card payloads |
This ownership model is also the documentation model: public docs describe behavior and boundaries, while private server state records live host paths, backups, rollback commands, and credentials.
Operating Modes
AgentHub supports several operating modes, each with different evidence requirements.
| Mode | Components | Appropriate claim | Evidence before public wording |
|---|---|---|---|
| Local preview | Desktop + Local Edge + mock runtime | Preview-ready local workflow | Edge health, Desktop connection, run events, screenshot or artifact evidence |
| Real local runtime | Desktop + Local Edge + Claude Code/Codex/OpenCode | Runtime adapter path can be tested locally | CLI installed/authenticated, adapter emits events, failure states visible |
| Hub-backed collaboration | Hub + Web + Desktop/Edge sync | Team workflow in progress | TokenDance ID session, project membership, task/run sync, audit record |
| IM entry | Integration Gateway + Hub + Feishu/Lark | Collaboration entry in development | Signature verification, fast callback ack, async queue, binding state |
| Remote/Cloud Edge | Hub + target Edge + routing/relay | In development until proven | device identity, target authorization, workspace policy, degraded states, audit |
Design Principles
- Desktop-first local execution: Desktop + Local Edge owns local workspace and process boundaries first.
- Hub-owned collaboration: identity sessions, projects, devices, routing, and audit are owned by Hub.
- Loose coupling: Web, Desktop, Hub, Edge, integration entries, and runtime adapters connect through explicit interfaces and can be replaced independently.
- Observable by default: agent actions, tool calls, and decisions should be traceable.
- Graceful degradation: a failed agent should not block unrelated work.
- Provider-neutral: model backends remain replaceable behind provider abstractions.