Desktop Guide
AgentHub Desktop is the local workbench for running, reviewing, and approving agent work. Use it when a task touches local files, local tools, terminals, or credentials that must not be exposed to the Web surface.
Scope
This page documents the intended Desktop + Local Edge experience. Exact menu labels may shift while the Desktop app is under active development, but the responsibility boundary stays stable.
When To Use Desktop
Use Desktop when:
- the workspace is on your machine;
- a runtime needs local CLI login, local shell access, or local filesystem context;
- you need to inspect diffs, files, previews, or terminal output before approving a write;
- the task should later sync to Hub for audit, review, or team visibility.
Use Web when the task is already Hub-backed and does not need direct local process access. Web must not bypass Hub to reach Local Edge or local files.## Surface Map
| Surface | Owner | Purpose |
|---|---|---|
| Workspace picker | Desktop | Select a local workspace and show whether it is allowed by Local Edge |
| Edge selector | Desktop | Choose the loopback Local Edge or an authorized remote target |
| Chat stream | Desktop | Show user instructions, agent replies, tool progress, and run state |
| Files panel | Desktop + Edge | Show changed files, read-only previews, and selected artifacts |
| Diff panel | Desktop + Edge | Review proposed changes before apply, commit, or publish |
| Terminal panel | Desktop + Edge | Show command state without hiding exit code, cwd, or approval context |
| Approval controls | Desktop | Require explicit approval for writes, shell, network, and publish actions |
First Session Checklist
Before running a real task:
- Start Local Edge and verify health.
- Open Desktop and confirm the displayed Edge URL matches the Local Edge URL.
- Select a small allowlisted workspace.
- Use the mock runtime for the first run.
- Send a read-only task.
- Confirm transcript, run events, file preview, and final state render without overflow.
- Switch to Claude Code, Codex, OpenCode, or a custom adapter only after the mock path is healthy.
curl.exe http://127.0.0.1:3210/health
curl.exe http://127.0.0.1:3210/v1/health
Runtime Controls
Desktop makes the selected runtime visible before a run starts. A useful run record includes:
| Field | Why it matters |
|---|---|
| Runtime adapter | Distinguishes mock, Claude Code, Codex, OpenCode, and custom engines |
| Workspace | Prevents accidental work outside the selected project |
| Approval policy | Explains whether the agent can read, write, run shell, or publish |
| Model/provider boundary | Keeps provider credentials out of the website and UI copy |
| Timeout and cancellation | Makes hung runtime states recoverable |
If a real runtime fails but the mock succeeds, debug local CLI installation, authentication, provider key, and adapter logs first.
Diff And File Review
The Desktop review loop is conservative:
- Runtime streams messages and tool state.
- Edge normalizes file, diff, and artifact events.
- Desktop renders the proposed changes read-only.
- User approves apply, reject, continue, or escalate.
- Edge records the approval and resulting state.
- Hub syncs review and audit facts only after authorization.
Never treat a pretty preview as approval. Approval is an explicit product event.
Theme And Language
Desktop and the public website share the same product vocabulary and visual direction:
- TokenDance Blue is the primary accent.
- Light-first glass surfaces are the default.
- Runtime logos use canonical brand icons where available.
- zh/en copy describes the same capability and status.
- Theme changes in the website mock represent how Desktop surfaces react to theme changes.
Evidence To Capture
For a useful Desktop QA note, capture:| Evidence | Example | |---|---| | Edge health | loopback URL and 2xx result | | Runtime | mock, Claude Code, Codex, OpenCode, or custom adapter | | Workspace | redacted path or project alias | | Run state | started, streaming, awaiting approval, completed, failed, or cancelled | | Review state | files changed, diff visible, approval requested, approval resolved | | UI state | desktop and mobile website mock remain readable after theme/language switch |
Do not put private workspace paths, real provider keys, private logs, or full model output into public screenshots.