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 on Intel or Apple silicon
• Windows on x64
• Linux on x64

Pre-built installers

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

macOS Gatekeeper note

The release workflow produces unsigned builds. macOS may block the first launch. Only allow the app after checking that you downloaded it from the official release page. Depending on your macOS version, use right-click Open or the blocked-app controls in System Settings > Privacy & Security.

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, or falls back to Alpha when no Stable release is available in the release list.

• 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 OpenWaggle is already open, the script quits it first and opens the new version.

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. Replace the example tag below with an existing release tag:

curl -fsSL https://raw.githubusercontent.com/OpenWaggle/OpenWaggle/main/scripts/install.sh \
  | OPENWAGGLE_RELEASE_TAG=v0.4.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 Sessions 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.
openwaggle update --version 0.4.0

--check reports availability without downloading. 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 is persistent; choosing --version is a one-time install and can target an exact Stable or prerelease version. 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

• A modern operating system, such as macOS, Windows 10+, or a recent Linux distribution.
• 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.