Install & First Launch

Download or build Cordy Desktop, and get past the unsigned-app warnings on Windows, macOS, and Linux.

This guide covers getting Cordy Desktop running on Windows, macOS, and Linux — the current source-only build path, and how to get past the first-launch security warnings that appear because builds are not yet code-signed.

Read this first. Cordy is early software (version 0.1.2, pre-1.0):

  • Builds are unsigned, so your OS will warn on first launch. The steps to proceed are below.
  • The 0.1.x releases are source-only — the packaging pipeline is paused, so you build from a checkout. See Build from source.
  • There is no auto-update. Download newer versions yourself from GitHub Releases.

System requirements

Cordy runs on Windows, macOS, and Linux. Formal minimum OS versions and hardware requirements are not published yet; the practical baseline is:

  • A 64-bit (x64) operating system. The Windows installer and the Linux packages are built for x64.
  • Git installed and on your PATH — Cordy works on local Git repositories and uses Git worktrees.
  • Each CLI agent you intend to use, installed and authenticated separately (see Agents). Cordy launches agents; it does not bundle them.

Development and release verification happen most on Windows and macOS; the Linux packages have had the least real-world testing.

Packaged installer, or source build?

There are two ways to get Cordy, and which one applies depends on the release:

  • Packaged installers (.exe, .dmg / .zip, .AppImage / .deb) — when a release has them attached, download and run as described in Install a packaged build.
  • Source build — the current 0.1.x releases are source-only (no installers attached). Build from a checkout as described in Build from source.

Both are published from the project's GitHub Releases page; the release notes for your version state which artifacts are attached.

Install a packaged build

When installers are attached to a release, download the artifact for your platform, then follow the first-launch steps to get past the unsigned-app warning.

Windows (NSIS installer)

  1. Download cordy-Setup-<version>.exe from the release.
  2. Run it. Because the build is unsigned, Windows SmartScreen may show "Windows protected your PC."
  3. Click More info, then Run anyway.
  4. The installer is a normal wizard — you can change the installation directory. It installs an app named Cordy and creates Start Menu and desktop shortcuts.

The Windows installer targets x64.

macOS (dmg or zip)

  1. Download the .dmg (disk image) or .zip for your Mac.
  2. From the .dmg, drag Cordy into Applications. From the .zip, unzip it and move Cordy.app into Applications.
  3. Because the build is unsigned and un-notarized, Gatekeeper will block a normal double-click (for example "Cordy can't be opened because it is from an unidentified developer").
  4. Right-click (or Control-click) the app → Open, then click Open in the dialog. You only need to do this once per install.

If macOS still refuses after a right-click → Open, see Troubleshooting.

Linux (AppImage or deb)

AppImage (portable, no installation):

  1. Download the .AppImage.
  2. Make it executable: chmod +x Cordy-*.AppImage.
  3. Run it: ./Cordy-*.AppImage.

deb (Debian / Ubuntu):

  1. Download the .deb.
  2. Install it: sudo apt install ./cordy_*.deb (or sudo dpkg -i cordy_*.deb).
  3. Launch Cordy from your application menu.

The Linux packages target x64 and are the least-tested of the three platforms.

Build from source

The 0.1.x releases are source-only, so this is the current primary path. You end up either running the app in development mode or producing a packaged installer yourself.

Prerequisites

  • Git.
  • Node.js 22.x and pnpm 9.x. This repo uses pnpm, and a pnpm-lock.yaml is committed; matching these majors avoids lockfile churn.
  • Rust 1.85.0 via rustup. The repo pins the toolchain in rust-toolchain.toml (with the rustfmt and clippy components), so rustup selects the right version automatically. Rust is required to build the cordy-runtime binary.
  • Windows only, for packaging: Visual Studio Build Tools with the Desktop development with C++ workload (including the Spectre-mitigated libraries) and a Python install discoverable by node-gyp.

Clone and install

git clone https://github.com/DS-Studio/cordy-desktop.git
cd cordy-desktop
pnpm install

Run in development mode

This is the fastest way to try Cordy. Build the Rust runtime once, then start the app:

pnpm runtime:build   # compile the cordy-runtime binary (debug)
pnpm dev             # start Vite + Electron in dev mode

If you skip pnpm runtime:build, the app still launches, but the runtime status shows binary-missing with a hint to build it — terminals and agents will not work until the binary exists. See Runtime.

Produce a packaged app

To build an installer for your current OS — this also compiles the release runtime and bundles it — run one of:

pnpm dist            # package for the current OS
pnpm dist:win        # Windows NSIS installer (x64)
pnpm dist:mac        # macOS dmg + zip
pnpm dist:linux      # Linux AppImage + deb
pnpm dist:dir        # unpacked app directory (no installer)

The finished installers and the unpacked app are written to the dist/ directory. Installers you build this way are also unsigned, so the first-launch steps above still apply.

Updating

Cordy does not update itself. To move to a newer version, download it from GitHub Releases (or pull the repo and rebuild), then install over your existing copy. Your projects, workspaces, notes, and settings live in a separate user-data directory (see Privacy) and are not affected by replacing the app.

  • Runtime — the cordy-runtime binary and its environment overrides.
  • Agents — installing and authenticating your CLI agents.
  • Troubleshooting — first-launch and runtime issues.