How to Install Goose on a Linux System: CLI and Desktop Guide

To install Goose on a Linux system, run the official installer script with curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash, which detects your architecture and places the binary in ~/.local/bin without requiring sudo.

Goose is an open-source AI-agent framework maintained in the aaif-goose/goose repository that ships a native CLI and optional desktop UI for Linux. The installation process relies on a self-contained Bash script called download_cli.sh that handles architecture detection, binary extraction, and optional post-install configuration. Whether you are running Ubuntu on x86_64 or a Raspberry Pi on aarch64, the installer automatically resolves the correct release asset from GitHub.

Installing the Goose CLI on Linux

One-Line Installation (Recommended)

The fastest way to install Goose on a Linux system uses the official installer. This method requires only curl and tar to be present on your system.

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

When executed, the script performs the following actions defined in download_cli.sh:

1. Dependency validation (lines 26-38): Verifies that curl and either tar or unzip are available.
2. Architecture detection (lines 90-166): Inspects $OSTYPE, /proc/version, and uname -m to determine if you are running x86_64 or aarch64.
3. Asset resolution (lines 178-194): Constructs the filename goose-$ARCH-unknown-linux-gnu.tar.bz2 and downloads it from the GitHub releases page.
4. Binary extraction (lines 195-215): Unpacks the goose binary into $HOME/.local/bin by default.
5. Configuration hook (lines 216-227): Runs goose configure to prompt for provider credentials unless disabled.

Installing a Specific Version

To install a particular release instead of the latest stable version, set the GOOSE_VERSION environment variable before executing the script:

export GOOSE_VERSION=v1.2.3
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

This logic is implemented in download_cli.sh at lines 76-88, where the script prioritizes the environment variable over the default stable tag.

Customizing the Installation Directory

By default, the installer places the binary in $HOME/.local/bin. To use a custom location, export GOOSE_BIN_DIR:

export GOOSE_BIN_DIR=$HOME/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | bash

Ensure the directory exists and is added to your PATH:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Disabling Automatic Configuration

The installer runs goose configure by default to set up AI provider credentials. To skip this interactive step, set CONFIGURE=false:

curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

Installing the Goose Desktop UI on Linux

For Debian-based distributions (Ubuntu, Mint, Pop!_OS), Goose provides a .deb package. According to the repository's LinuxDesktopInstallButtons.js component and installation documentation, follow these steps:

wget https://github.com/aaif-goose/goose/releases/download/stable/goose-desktop-linux-x64.deb
sudo dpkg -i goose-desktop-linux-x64.deb
sudo apt-get install -f

After installation, launch the application from your desktop menu or by running goose-desktop in your terminal.

How the Linux Installer Works

The download_cli.sh script functions as a self-extracting installer that never requires super-user privileges unless you choose a system-wide installation directory. The implementation follows this architecture:

• Variable setup (lines 54-75): Determines the target binary directory via GOOSE_BIN_DIR and selects the release channel (stable or canary when CANARY=true).
• OS detection: Uses $OSTYPE, $WINDIR, and /proc/version to confirm the system is Linux.
• Asset naming: Builds the download URL https://github.com/aaif-goose/goose/releases/download/<tag>/goose-<arch>-unknown-linux-gnu.tar.bz2.
• Privilege separation: The script runs entirely in user space, writing only to the directory specified in GOOSE_BIN_DIR.

Verifying Your Installation

Confirm the CLI installed correctly by checking its version:

goose --version

For desktop installations, verify with:

goose-desktop --version

If you receive a "command not found" error, verify that your installation directory is in your shell's PATH environment variable.

Summary

• Install Goose on a Linux system by piping the official download_cli.sh script to Bash, which auto-detects x86_64 or aarch64 architectures and downloads the appropriate tarball.
• The default installation requires no root privileges, placing the binary in $HOME/.local/bin.
• Customize behavior using environment variables: GOOSE_VERSION for specific releases, GOOSE_BIN_DIR for alternative paths, and CONFIGURE=false to skip credential setup.
• Debian-based users can install the Desktop UI via the .deb package available in GitHub releases.
• The installer logic resides entirely in download_cli.sh and handles dependency verification, OS/architecture mapping, and extraction automatically.

Frequently Asked Questions

Does Goose require root privileges to install on Linux?

No. The standard CLI installation places the binary in $HOME/.local/bin by default, which is user-writable according to the default variable setup in download_cli.sh (lines 54-75). You only need sudo if you explicitly set GOOSE_BIN_DIR to a system directory like /usr/local/bin.

What architectures does Goose support on Linux?

The installer supports x86_64 and aarch64 (ARM64) architectures. The detection logic in download_cli.sh (lines 90-166) uses uname -m to identify the CPU type and maps it to release assets named goose-x86_64-unknown-linux-gnu.tar.bz2 or goose-aarch64-unknown-linux-gnu.tar.bz2.

How do I uninstall Goose from my Linux system?

Since the CLI is distributed as a single static binary, simply delete it from your installation directory: rm $HOME/.local/bin/goose. For the Desktop UI, use your package manager: sudo apt remove goose-desktop.

Can I install Goose on Alpine Linux or other musl-based distributions?

The official installer downloads GNU toolchain binaries. While these typically work on musl systems with compatibility layers, you may encounter issues on pure musl environments. In such cases, you should build Goose from source or verify binary compatibility with your specific libc implementation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}