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

> Install Goose on Linux easily with our CLI or desktop guide. Run the official installer script to get the Goose binary securely into your system.

- Repository: [goose/goose](https://github.com/aaif-goose/goose)
- Tags: how-to-guide
- Published: 2026-04-07

---

**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`](https://github.com/aaif-goose/goose/blob/main/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.

```bash
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`](https://github.com/aaif-goose/goose/blob/main/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:

```bash
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`](https://github.com/aaif-goose/goose/blob/main/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`:

```bash
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`:

```bash
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`:

```bash
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`](https://github.com/aaif-goose/goose/blob/main/LinuxDesktopInstallButtons.js) component and installation documentation, follow these steps:

```bash
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`](https://github.com/aaif-goose/goose/blob/main/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:

```bash
goose --version

```

For desktop installations, verify with:

```bash
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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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.