Desktop

Desktop is the recommended first entry point for DotCraft. It works as an AppServer client and provides a visual UI for workspaces, sessions, diffs, plans, model configuration, automation review, and runtime status.

For first-time setup, follow Getting Started for download, workspace selection, and model configuration. This page focuses on Desktop-specific panels and settings.

Installation

Use a Release

1. Download an installer from GitHub Releases.
2. Start DotCraft.
3. Choose a project folder as the workspace.

Run from Source

cd desktop
npm install
npm run dev

When running from source, Desktop looks for dotcraft on PATH. If it cannot find it, set the AppServer / dotcraft binary path in settings. Build installer artifacts with npm run dist; outputs land in desktop/dist/.

Startup Arguments

DotCraft --app-server /path/to/dotcraft
DotCraft --workspace /path/to/project

Desktop-Specific Settings

Section	Purpose
Settings → General	Current workspace path, AppServer binary path, language
Settings → Personalization	Long-term memory / Dreams switches, run-now, auto-update, reset memory
Settings → Model Providers	Personal providers, credentials, endpoints, workspace provider and model
Settings → Sub Agents	Reuse external CLI sessions (see SubAgents)
Settings → Connection	Switch between local Hub and remote AppServer

Personalization → Dreams

• Run now — trigger a Dreams consolidation immediately.
• Auto-update Dreams — off: new Dreams stay pending; on: future successful runs auto-apply as active.
• Manage Dreams — list of recent runs; each opens Dashboard for diff, trace, apply, discard, cancel, archive.
• Reset memory — clear MEMORY.md, HISTORY.md, .craft/dreams/, and derived caches in one click. It does not delete sessions, config, skills, or automations.

See Memory & Dreams for the full picture.

Model Providers

• Provider credentials and endpoints are written to personal ~/.craft/config.json, not the workspace.
• The workspace only stores ProviderId and Model, so shared workspace config never holds secrets.
• Desktop currently supports OpenAI and Anthropic providers.
• Use Test to check credential and model-list reachability. If a provider cannot list models, save it and type the model name manually.

Connection (Local vs Remote)

• Local (default): Desktop launches or discovers a workspace AppServer through Hub; multiple entries share the same process.
• Remote: connect to an existing WebSocket AppServer. Desktop does not restart the remote process, only tests and switches.
• Remote URL/token changes are first probed against a draft connection. Failures are not saved, so a bad URL never traps you on the next start.
• When Desktop is launched with --remote, the persistent connection switch in Settings is disabled.

What's New

After Desktop is upgraded, What's New appears once when you enter a ready workspace UI and highlights the current version's new capabilities. Animated previews are downloaded from the DotHarness resources repo, verified, and cached locally; the automatic prompt waits for previews, while manual reopen shows text and placeholders immediately. Reopen any time via Help → What's New or the version label at the bottom of the sidebar. The newest release is shown expanded; older releases are collapsed behind a Past releases toggle so you can review earlier highlights when you want them.

Updates

On startup, DotCraft checks GitHub Releases for a newer release tag. When a platform installer is available, a highlighted download button appears in the title bar. Select it to review the release, download the installer with progress, then DotCraft quits and opens the downloaded installer.

Usage Examples

Scenario	Desktop path
First-time setup	Choose workspace → configure model → create session
Inspect agent work	Open session detail, diff, trace, or Dashboard
Review automation tasks	Open Automations and inspect pending review items
Switch projects	Choose another workspace so config and tasks stay project-scoped
Take back SubAgent control	Settings → Sub Agents → disable reuse external CLI sessions

Advanced

• Desktop consumes the AppServer Wire Protocol, so it shares the same session core with TUI, ACP, and external channels.
• Image attachments live under .craft/attachments/images/ and survive restart.
• Markdown surfaces render fenced mermaid / mmd code blocks as Mermaid diagrams. If a diagram cannot be rendered, Desktop falls back to the source block.

Troubleshooting

No session is available after startup

Confirm a workspace is selected and the AppServer / dotcraft binary can run.

Settings changes do not apply

Provider and model selections take effect for new sessions. Existing provider-aware threads keep their captured provider and model unless you explicitly change the active thread's model. AppServer, port, and entry-point settings require restarting Desktop or the background host. See Settings Lifecycle.

The Automations panel is empty

Use Gateway or a host that loads Automations, and enable the relevant task source. See Automations.

Related

• Getting Started
• TUI
• Observability
• Settings Lifecycle