Installation

How to install OpenWaggle on macOS, Windows, or Linux.

Download an installer from GitHub Releases. Choose the version and platform you intend to use; prereleases are marked on GitHub. You do not need Node.js or a source checkout to run the installed app.

Released builds send anonymous usage statistics and error reports, from the first launch. Statistics never include prompts, code, file paths, or any identifier for you or your install. See Usage statistics and error reports for every field and how to turn them off.

Supported platforms

• macOS 13.4 (Ventura) or later, on Apple silicon or Intel
• Windows 10 or later, on x64
• Linux on x64 with glibc 2.35 or later

See System requirements for details.

Pre-built installers

After opening the app, follow Get started to connect a model and open a project.

Signing and first launch

macOS builds are signed with an Apple Developer ID and notarized by Apple, so macOS does not block them as coming from an unidentified developer. The first time you open one, macOS may still ask you to confirm opening an app downloaded from the internet. Builds before 1.0.0-beta.1 were unsigned. If you still run one of those, download the current version from GitHub Releases and replace the app in Applications once; an in-app update from an unsigned build may not install.

Windows installers are not signed yet, so SmartScreen may warn the first time you run one. If it does, check that you downloaded the installer from the official release page, then choose More info and Run anyway. The Linux AppImage is not signed.

Quick install (macOS / Linux)

If you prefer a terminal, this command downloads and runs the repository’s install script. Read the script first if you want to inspect what it changes.

curl -fsSL https://raw.githubusercontent.com/OpenWaggle/OpenWaggle/main/scripts/install.sh | bash

The script installs the app and verifies its SHA-256 checksum when the release includes a SHA256SUMS asset with an entry for the downloaded file. A mismatch stops installation; a missing checksum asset or entry does not. It selects the Stable channel by default. Until the first Stable release is published, it selects Beta instead, which also receives release candidates and, later, Stable releases.

• On macOS, it copies OpenWaggle.app to /Applications and removes its quarantine attribute.
• On Linux, it installs the AppImage under ~/.local/lib/openwaggle, installs the openwaggle command in ~/.local/bin, and creates a .desktop entry.

When it finishes, the script opens OpenWaggle. On macOS, if the OpenWaggle it replaces is already open, the script quits it first and opens the new version. An OpenWaggle opened from another location stays open. All installed copies share one Session Host, so if another copy is open when the script updates an existing install, the script stops and asks you to quit that copy first.

When it updates an existing install, the script first stops OpenWaggle’s background Session Host, as Restart to update does. If agent work is still running, it asks whether to wait for it, stop it, or cancel. Cancelling, or pressing Ctrl-C while it waits, leaves the installed version as it was and reopens the app if the script quit it. An installed version that predates this cannot ask, so the script waits up to 20 seconds for that work, then installs anyway. On Linux an open OpenWaggle keeps running with its Session Host: quit it, run openwaggle host stop --update, then open it to use the new version.

The script does not open the app over SSH, in CI, or on Linux without a display. To install without opening it, set OPENWAGGLE_NO_LAUNCH=1 or pass --no-launch:

curl -fsSL https://raw.githubusercontent.com/OpenWaggle/OpenWaggle/main/scripts/install.sh \
  | bash -s -- --no-launch

To opt into a prerelease channel, use the same installer:

# Alpha also receives Beta, release candidate, and Stable releases.
curl -fsSL https://raw.githubusercontent.com/OpenWaggle/OpenWaggle/main/scripts/install.sh \
  | OPENWAGGLE_CHANNEL=alpha bash

# Beta also receives release candidate and Stable releases.
curl -fsSL https://raw.githubusercontent.com/OpenWaggle/OpenWaggle/main/scripts/install.sh \
  | OPENWAGGLE_CHANNEL=beta bash

The installer saves the selected policy channel, not merely the channel label on the artifact it downloads. For example, an Alpha install remains on Alpha even when the newest eligible artifact happens to be a Beta or Stable build.

For a one-time exact-version install, set OPENWAGGLE_RELEASE_TAG instead. This does not change your saved channel. Tags look like v1.0.0, v1.0.0-rc.1, or v1.0.0-beta.25; replace the example below with a tag listed on GitHub Releases. Installing a version older than the one you have is a downgrade, which OpenWaggle does not support: an older version may not open data a newer one has already migrated.

# Example tag: v1.0.0 is published when OpenWaggle 1.0 ships.
curl -fsSL https://raw.githubusercontent.com/OpenWaggle/OpenWaggle/main/scripts/install.sh \
  | OPENWAGGLE_RELEASE_TAG=v1.0.0 bash

Command-line access

After installing the app, launching it installs or refreshes the managed openwaggle command on macOS or Linux; make sure ~/.local/bin is on your shell’s PATH. An unrelated command at that path is never replaced. Windows installers register the command automatically. Run openwaggle --help to list the commands. The CLI lets terminals and external coding agents run agents headlessly and control the same live Sessions shown in the app; see Command line and Hive CLI.

Choose an update channel

The app and CLI share one saved update channel. Change it from Settings → General → About & Updates, or from a terminal. Check availability first, then choose one channel or an exact version:

openwaggle update --check
openwaggle update --channel alpha
openwaggle update --channel beta
openwaggle update --channel stable
# Exact-version example; choose a version published on GitHub Releases.
# 1.0.0 is published when OpenWaggle 1.0 ships.
openwaggle update --version 1.0.0

--check reports availability without downloading, and it never changes a setting: --channel beta --check checks Beta without saving it. Without --check, openwaggle update downloads and installs the newest eligible release without opening the app. If OpenWaggle is already open, the command leaves the update to the app instead: open Settings → General → About & Updates, choose Check now, then Restart to update, so running agent work is not interrupted without asking. An exact --version install asks you to quit OpenWaggle first. Before it installs, the command stops OpenWaggle’s background Session Host as Restart to update does: if agent work is still running, it asks whether to wait for it, stop it, or cancel. Without a terminal to ask on, as on Windows, it waits for that work. Choosing --channel without --check is persistent; choosing --version is a one-time install and can target an exact Stable or prerelease version. --version refuses a version older than the installed one and exits with status 2, because downgrades are unsupported; the same version reinstalls it. Until the first Stable release is published, the Stable channel has nothing to install, so the app and openwaggle update report it as up to date rather than as a failed check. A release whose update files are still uploading is skipped until a later check. Release candidates (RC) are not a separate channel; Beta and Alpha receive them automatically. On a first launch with no saved preference, an Alpha or Beta build starts on its matching channel and a release candidate starts on Beta; Stable remains the default otherwise. The app confirms each switch into Alpha and checks a newly selected channel immediately. OpenWaggle never downgrades automatically when channels change, and Restart to update re-reads the shared channel before installing an already-downloaded release.

Released builds also check for updates a few seconds after launch and every 4 hours. These checks contact GitHub. See Update checks.

System requirements

On macOS 12 through 13.3, OpenWaggle still opens and keeps receiving updates, but those versions are not supported. Semantic Session search and voice input need macOS 13.4 and fail on older versions. Update macOS to use them.

On Linux, check your glibc version with ldd --version.

You also need:

• Access to an AI provider through an API key, sign-in, or another supported configuration. See Providers and models.
• An internet connection when using hosted models.

Building from source

To run a development checkout rather than an installer, see Building from source.