Installation

Install the Cusp desktop app or the cusp CLI on macOS, Windows or Linux.

Cusp ships as a desktop app and as a command-line tool. Both use the same runtime, so you can install either one, or both. Sessions you start in one are visible in the other when they share a data directory.

Cusp 0.1 is a preview. Installers and package names may change before 1.0. If something here doesn't match what you see, check the changelog.

Desktop app

Download the installer for your platform from cusp.run/download. The first releases are for macOS; Windows and Linux installers follow in a later release.

  1. Download Cusp-universal.dmg. It is a universal build for Apple silicon and Intel Macs.
  2. Open the disk image and drag Cusp to Applications.
  3. Open Terminal and run this once: 
    xattr -dr com.apple.quarantine /Applications/Cusp.app
  4. Open Cusp from Applications or Spotlight.

This preview isn't notarized by Apple yet. macOS won't open an app downloaded from the internet until its quarantine flag is cleared, and step 3 clears it for Cusp only. Updates install without it. Notarized builds will come with a later release.

Closing the window hides Cusp; the Dock icon brings it back. Press ⌘Q to quit.

What the desktop app installs

  • Cusp, the native shell. It hosts the workspace UI and handles the menu bar, tray, notifications, deep links and the keychain.
  • cusp-daemon, the agent runtime, as a sidecar next to the main executable. The app starts it, health-checks it every 10 seconds, and restarts it if it stops responding. It exits when the app exits.

The desktop app keeps its data in the platform's application data folder. On macOS that is ~/Library/Application Support/run.cusp.desktop/.

CLI

The cusp command gives you an interactive terminal UI and a headless mode for scripts.

Available with the first public release.

The CLI stores sessions, file checkpoints and worktrees in ~/.cusp by default. Use --data-dir or the CUSP_DATA_DIR environment variable to put them elsewhere.

Web app

The web app is coming soon. It will run sessions in cloud sandboxes and let you control the daemon on your own machine from a browser or phone.

System requirements

Minimum
macOSmacOS 12 Monterey or later, Apple silicon or Intel
WindowsWindows 10 or 11, x64, with WebView2
Linuxx86_64, glibc-based distribution with WebKitGTK 4.1 (desktop app only)
CLImacOS (Apple silicon or Intel), Linux with glibc (x64 or arm64), Windows x64; Node.js 18+ if you install with npm
NetworkAccess to at least one model provider, or a local model server

Optional tools that make the agent better at its job:

  • Git. Needed for worktree isolation, diffs and /review.
  • ripgrep (rg). The Grep tool uses it when present and falls back to a built-in engine with identical output.
  • Language servers. tsc or tsgo for TypeScript, and any stdio language server you have installed, power post-edit diagnostics.
  • bubblewrap (bwrap) on Linux. The sandbox is on by default, and without bwrap Cusp refuses shell commands rather than run them unsandboxed. macOS uses the built-in Seatbelt sandbox. See Sandbox.

Updating

The desktop app updates itself from signed releases once updates are switched on for public builds. Until then, download the new version and replace the app. To update the CLI, run its install command again, or update it with the package manager you installed it with.

Uninstalling

  • macOS: quit Cusp and move it from Applications to the Trash. To remove everything it stored, also delete:
    • ~/Library/Application Support/run.cusp.desktop/: settings, sessions and the daemon's data (daemon/)
    • ~/Library/Logs/run.cusp.desktop/: logs and crash records
    • ~/Library/Caches/run.cusp.desktop/ and ~/Library/WebKit/run.cusp.desktop/: web view caches
    • ~/Library/LaunchAgents/Cusp.plist: only there if you turned on Open at login
  • Windows: use Settings → Apps → Installed apps.
  • Linux: remove the package with your package manager, or delete the AppImage.
  • CLI: delete ~/.cusp/bin (shell installer), or uninstall it with the package manager you installed it with. Delete ~/.cusp to remove sessions, checkpoints and user settings.

Provider keys saved by the desktop app live in the OS keychain under the service run.cusp.desktop (run.cusp.desktop.dev for builds you made yourself). Remove them from Keychain Access, Credential Manager, or your Secret Service keyring.

Next

Introduction

Cusp is an agentic coding workspace for any model, tuned to each one.

Quickstart

Start your first Cusp session in the desktop app or the terminal.

On this page

Desktop appWhat the desktop app installsCLIWeb appSystem requirementsUpdatingUninstallingNext