# Desktop app

Hoplite ships a native macOS app alongside the web app. It's the same cloud experience — projects, threads, sandboxes, pull requests — in a Dock-resident window with native menus, deep links, and notifications. It can also run your locally installed Codex or Claude Code sessions as **local-agent threads**, entirely on your machine.

<Callout type="info" title="Apple silicon only">
The macOS build is arm64-only. Intel Macs are outside this release.
</Callout>

## Install

Download the signed, notarized DMG and drag Hoplite into Applications. Sign in once with your existing Hoplite account — the desktop session is independent of your browser session, so you can be signed into both at once.

## What's different from the web app

- **Native shell** — Dock icon with unread-state badging, native app/context/keyboard-shortcut menus, and native completion notifications instead of browser notifications.
- **Deep links** — `hoplite://` links (for example from Slack or email) open directly in the installed app instead of a browser tab.
- **Persistent session and window placement** — the app remembers where you left off between launches.
- **Local-agent threads** — an optional local host for coding agents you already have installed, covered below.

Cloud-agent threads work exactly as they do on the web: the same projects, sandboxes, and pull requests, backed by the same GitHub App and Modal sandboxes described in [Sandboxes](/docs/sandboxes).

## 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` and don't require a cloud query or a signed-in session to create, read, or run. 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.

<Callout type="info" title="Not a replacement for cloud threads">
Local-agent threads don't get a Hoplite sandbox, GitHub App-brokered credentials, or the managed Preview and Terminal panels. Use a cloud thread (see [Threads](/docs/threads)) when you want Hoplite to run in an isolated environment and open the pull request for you.
</Callout>

## Credentials stay local

The renderer talks to the cloud API the same way the web app does; it never receives a native folder handle, a provider process handle, shell access, or provider credentials directly. Local execution, folder access, and provider supervision are owned by a separate native process, matching the sandbox credential boundary described in [Security and data handling](/docs/workspace/security).

## Updates

The desktop app checks for updates on launch, when it 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.

Desktop app

The native macOS client for Hoplite: cloud threads, and an optional local host for Codex and Claude Code

Hoplite ships a native macOS app alongside the web app. It's the same cloud experience — projects, threads, sandboxes, pull requests — in a Dock-resident window with native menus, deep links, and notifications. It can also run your locally installed Codex or Claude Code sessions as local-agent threads, entirely on your machine.

The macOS build is arm64-only. Intel Macs are outside this release.

Install

Download the signed, notarized DMG and drag Hoplite into Applications. Sign in once with your existing Hoplite account — the desktop session is independent of your browser session, so you can be signed into both at once.

What's different from the web app

Native shell — Dock icon with unread-state badging, native app/context/keyboard-shortcut menus, and native completion notifications instead of browser notifications.
Deep links — hoplite:// links (for example from Slack or email) open directly in the installed app instead of a browser tab.
Persistent session and window placement — the app remembers where you left off between launches.
Local-agent threads — an optional local host for coding agents you already have installed, covered below.

Cloud-agent threads work exactly as they do on the web: the same projects, sandboxes, and pull requests, backed by the same GitHub App and Modal sandboxes described in Sandboxes.

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 and don't require a cloud query or a signed-in session to create, read, or run. 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.

Local-agent threads don't get a Hoplite sandbox, GitHub App-brokered credentials, or the managed Preview and Terminal panels. Use a cloud thread (see Threads) when you want Hoplite to run in an isolated environment and open the pull request for you.

Credentials stay local

The renderer talks to the cloud API the same way the web app does; it never receives a native folder handle, a provider process handle, shell access, or provider credentials directly. Local execution, folder access, and provider supervision are owned by a separate native process, matching the sandbox credential boundary described in Security and data handling.

Updates

The desktop app checks for updates on launch, when it 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.