---
title: "Desktop app"
description: "Work with cloud agents and local Codex or Claude Code sessions in the Hoplite macOS app."
canonical_url: "https://hoplite.sh/docs/desktop"
markdown_url: "https://hoplite.sh/docs/desktop.md"
---

# Desktop app
URL: /docs/desktop
LLM index: /llms.txt
Description: Work with cloud agents and local Codex or Claude Code sessions in the Hoplite macOS app.
Related: /docs/threads, /docs/cli, /docs/workspace/security

# Desktop app

Use the Hoplite macOS app to work with cloud threads and local Codex or Claude Code sessions in one place. Choose managed cloud execution or run against a folder on your machine. The current build requires Apple silicon.

## Install

Download the current signed, notarized **Release** DMG from [Hoplite's stable download endpoint](https://api.hoplite.sh/api/desktop/release/download), then drag Hoplite into Applications. Sign in once with your existing Hoplite account — social sign-in opens in your system browser and returns to the app automatically, while the desktop session remains independent of your browser session so you can be signed into both at once.

## Cloud and local execution

| | Cloud thread | Local thread |
| --- | --- | --- |
| Files | Managed sandbox workspace | Local folder or per-thread Git worktree |
| Agent provider | Hoplite-managed execution | Installed Codex or Claude Code CLI |
| Credentials | Project and workspace configuration | Local provider login and configuration |
| Managed Preview and Terminal | Available for cloud workspaces | Unavailable |
| Persistence | Hoplite services and workspace lifecycle | Local SQLite state under `~/.hoplite`, with cloud sync on reconnect |

Cloud threads use the same backend as the web app. Local execution is supervised by the desktop app on your machine.

Links that leave Hoplite open in your system browser, including a preview or terminal opened in a new tab, a pull request, and sign-in to an MCP server. Links to Hoplite itself open in the app window. For an MCP server, finish signing in in the browser, then return to Hoplite: a **Finish signing in…** notice waits for the connection, with **Cancel** to stop waiting, and gives up after 10 minutes.

## Start a local thread

1. Install and sign in to Codex or Claude Code on your Mac. Hoplite uses that provider's existing login.
2. In the desktop app, open **Settings → Account → Local agents** and select **Add folder**. Choose the repository folder you want the agent to use.
3. Create a thread for the local project. In the composer's execution picker, choose **Local** to work directly in that folder, or **Worktree** for a separate Git worktree. Worktree placement requires a Git repository.
4. Select an available local provider and model, then send the task. If the provider is unavailable, check its installation and login in **Local agents**.

Open **Views → Diff** to inspect the changes. Local threads do not provide the managed Preview or Terminal panels; use your local tools to run and inspect the application.

## Local-agent threads

The desktop app can bind a local folder — either directly, or as a per-thread Git worktree — and supervise your installed **Codex** or **Claude Code** CLI against it. These local-agent threads run without a cloud sandbox: the provider process, its file access, and its approvals stay on your machine.

- **Codex** runs through its `app-server` protocol and keeps its own configured approval policy.
- **Claude Code** runs through Anthropic's Agent SDK against your installed `claude` executable, so it uses your existing subscription and configuration (`CLAUDE.md`, hooks, skills, MCP servers, and permission rules) rather than a separate API key. Availability requires both the CLI and an authenticated session reported by that CLI. Claude sessions start in the SDK's `auto` permission mode; explicit `ask` rules and tools that require interaction still raise an approval in the thread, same as a cloud thread.

Local-agent threads, their messages, runs, and approvals are stored in a local SQLite database under `~/.hoplite`. When you're signed in, new local projects publish their threads to your organization by default: teammates and your other devices can see the thread, send messages, approve tools, and stop runs while the desktop host remains responsible for execution. Older local-only projects move to this default on first launch and queue their existing threads for publication. You can unshare an individual thread from its header menu. Signing out or losing connectivity doesn't stop or roll back a turn that's already running locally — cloud sync catches up when the app reconnects.

## Credentials and process access

Local providers use their existing authentication and configuration. Folder access, provider execution, and local approvals are handled by the desktop's native process. The renderer does not directly receive provider credentials or shell access.

## Updates

The Release channel checks its stable update feed on launch, when the app regains focus after being idle, and hourly while running. Updates download automatically and prompt you to restart and install them, preserving your signed-in session and window placement across the restart.

## Sitemap

Sitemap discovery is not enabled for this deployment.