FAQ

This page answers common product, setup, identity, runtime, and documentation questions.

Product

Is AgentHub a CLI replacement?

No. AgentHub can use CLIs such as Claude Code, Codex, and OpenCode through runtime adapters, but the product goal is a visible workflow across Desktop, Web, Hub, Edge, review surfaces, approvals, integrations, and audit.

Is AgentHub production-ready?

The public website and docs are live. Desktop + Local Edge local preview paths and the product architecture are actively developed. Feishu/Lark production integration, Remote/Cloud Edge, full Web + Hub + Edge routing, and stable public Adapter SDK packaging are still in development.

What is the smallest useful AgentHub demo?

Use Desktop connected to Local Edge with the mock runtime first. It should show a task, structured run events, chat output, file or diff state, approval affordances, theme/language behavior, and a clear success or failure state. Once that works, switch one runtime adapter to a real CLI.

Why does the website show a Desktop mock?

The mock communicates the intended Desktop UI model: chat, files, diff, preview, terminal, runtime selector, theme, language, and approvals. It is not a fake standalone product. It should stay aligned with the current AgentHub Desktop design.

Which operating systems are supported?

Public docs focus on local development and preview on Windows, macOS, and Linux. The examples call out platform differences where they matter, especially PowerShell curl.exe, port checks, shell profile differences, and loopback networking. Packaged end-user installers are not yet a general-availability claim.

Setup

Which page should I read first?

Read Installation for workstation setup, then Quickstart for the smallest Desktop -> Local Edge -> Runtime Adapter run.

Should I start with Claude Code or Codex?

Start with the mock runtime. Once Desktop, Edge, events, and diff panels are healthy, switch to one real runtime whose CLI is already installed and authenticated in your local shell.

Why does Desktop not connect?

Check the Local Edge URL, port, health endpoint, workspace allowlist, and runtime profile. Desktop and Edge use different ports; do not confuse the UI dev-server port with the Edge API port.

What should I do if a port is already occupied?

Identify the process first, then either stop the conflicting process or move the AgentHub component to a different port and update dependent URLs. Do not assume the homepage dev-server port is the Local Edge API port. On Windows, start with netstat -ano | findstr :3210; on macOS/Linux, use lsof -i :3210 or ss -ltnp.

How many processes does a local preview need?

The smallest path usually needs two processes: Local Edge and the Desktop dev server. The real runtime CLI is launched or called by the Edge adapter. Start Hub Server and Web only when testing Hub/Web collaboration. Starting every service at once makes failures harder to isolate.

Why start with the mock runtime?

The mock runtime removes provider credentials, CLI login, quota, network, and runtime-output-format variables. Once mock runs reliably show events, diffs, artifacts, and approvals, real-runtime failures become much easier to attribute.

Why can a docs page build locally but look stale online?

Static export, CDN/browser cache, language route normalization, and stale deployment directories can all cause this. Verify the cache-busting URL, rendered keyword, sitemap entry, llms.txt entry, and deployed artifact version before assuming the source branch is wrong.

Identity

No. TokenDance ID is the identity authority. Third-party provider OAuth and account linking belong in TokenDance ID. AgentHub consumes TokenDance ID identity and applies product-local authorization.

Can TokenDance API keys log in to AgentHub?

No. TokenDance API keys authenticate model API calls through TokenDance Gateway. AgentHub browser login uses TokenDance ID and AgentHub product sessions.

No. The public website login is low-risk product-site personalization. Hub API authorization must be enforced by Hub Server with TokenDance ID-backed sessions and product permissions. Read Identity And Login for callback, browser state, return path, UI, and authorization boundary details.

Runtime

What is an Agent Profile?

An Agent Profile is the product-facing definition of a coding agent: label, icon, capability, target, approval policy, and adapter. The adapter still owns real runtime execution.

Why does a real runtime fail when the mock works?

Treat that as a local CLI, authentication, provider quota, workspace policy, or adapter-profile issue first. Do not move provider keys into the browser or public docs.

Does data leave my machine during local preview?

Desktop + Local Edge is the local-first path. Local workspace reads, runtime execution, diffs, and artifacts stay within the local Edge boundary unless you explicitly connect a provider/runtime or Hub-backed workflow that sends data elsewhere. Public docs and screenshots should still use synthetic paths and redacted content.

Can Web start a local CLI directly?

No. Web is Hub-backed. It should create or inspect Hub state and route through authorized Edge targets. Direct local file and CLI access belongs to Desktop + Local Edge.

Are runtime adapters a stable public SDK today?

Not yet. The adapter contract, capability vocabulary, run lifecycle, event envelope, and examples are taking shape, but third-party packaging and submission rules are not stable enough to market as a public ecosystem.

Why separate Agent Profiles from runtime adapters?

Profiles are product-facing choices: label, icon, capability, approval policy, and default behavior. Adapters are execution boundaries that parse output from runtimes such as Claude Code, Codex, and OpenCode. Keeping them separate lets teams discuss "which agent" and "how execution works" without mixing permissions, UI, and CLI implementation.

Integrations

No. Feishu/Lark is a collaboration entry: bot events, cards, H5/workbench, and task context. TokenDance ID remains the login and account-binding authority.

Why do card callbacks need to respond quickly?

Feishu/Lark card callbacks should respond within 3 seconds. Slow AgentHub work should be queued and processed asynchronously.

Can a Feishu/Lark message contain a full AgentHub task context?

No. IM payloads should carry compact ids, action names, and safe summaries. Full prompts, provider credentials, private file content, and local paths must stay out of card payloads and public logs.

Gateway is live, so why do AgentHub docs say model API keys do not belong to AgentHub?

They are different credential planes. TokenDance Gateway owns model API keys, provider routing, quota, and model access. AgentHub owns product sessions, workspaces, runs, approvals, and collaboration audit. AgentHub may let a runtime use locally or server-side configured provider credentials, but a TokenDance API key is not an AgentHub login credential.

Docs And Releases

Why do docs use cautious status wording?

Because public docs must not turn preview or in-development capabilities into launch claims. Use live, preview-ready, contract-shaped, in progress, or in development according to evidence.

What must change when a new docs page is added?

Add the English and Chinese MDX pages, route registration, navigation, TOC headings, metadata, search text, sitemap links, llms.txt, README route inventory, changelog, and tests where useful.

Why do docs say "in development" so often?

That is intentional. AgentHub is still converging Desktop, Edge, Hub, Web, IM, and runtime adapters into one product contract. Public docs should keep boundaries narrow rather than presenting capabilities without E2E, screenshot, smoke, or failure-state evidence as launched.

Why is there no "Edit this page on GitHub" link?

The public docs are maintained in this repository, but the site should not send readers into an undesigned edit flow. Contributions go through Contributing, GitHub issues/PRs, and the public route inventory.

Where do private deployment details belong?

Private deployment paths, SSH aliases, web roots, backup names, rollback commands, provider keys, and admin tokens belong in the private server workspace, not this public docs site.

Where should users report issues?

Use the public GitHub repository for bugs, docs gaps, and feature requests that do not include secrets or private infrastructure. Include route, language, browser or OS, expected behavior, actual behavior, redacted error code, and reproduction steps. Keep provider keys, raw prompts, private file content, local absolute paths, and callback payloads out of issues.

FAQ