Desktop Guide

AgentHub Desktop is the Tauri 2 native local workbench for running, reviewing, and approving agent work. It shares the same workbench UI with Web and Mobile, showing the conversation as chat messages and diffs, files, and results in dedicated panels.

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 (port 5174) when the task is already Hub-backed and does not need direct access to local processes. Web shares the same workbench UI as Desktop, accessing collaboration state through Hub rather than connecting directly to Local Edge.

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

1. Start Local Edge and verify health.
2. Open Desktop and confirm the displayed Edge URL matches the Local Edge URL.
3. Select a small workspace.
4. Use the mock runtime for the first run.
5. Send a read-only task.
6. Confirm the conversation, run events, file previews, and final state render without overflow.
7. 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 separate from UI copy
Timeout and cancellation	Makes hung runtime states recoverable

If a real runtime fails but mock succeeds, debug local CLI installation, authentication, provider key, and adapter logs first.

Diff And File Review

The Desktop review flow keeps things safe:

1. Runtime streams messages and tool state.
2. Edge normalizes file, diff, and result events.
3. Desktop renders the proposed changes read-only.
4. User approves apply, reject, continue, or escalate.
5. Edge records the approval and resulting state.
6. Hub syncs review and audit facts after authorization.

Approval is an explicit product event — preview and approval are two different things.

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.

Edit this page on GitHub