Skip to content

BUILDING_LINUX.md

Latest commit

 

History

History
218 lines (162 loc) · 5.54 KB

BUILDING_LINUX.md

File metadata and controls

218 lines (162 loc) · 5.54 KB
Raw

Building goose Desktop on Linux

This guide covers building the goose Desktop application from source on various Linux distributions.

Prerequisites

System Dependencies

Debian/Ubuntu:

sudo apt update
sudo apt install -y dpkg fakeroot build-essential clang libxcb1-dev libxcb-util-dev protobuf-compiler libvulkan-dev libvulkan1 glslc

Arch/Manjaro:

sudo pacman -S --needed dpkg fakeroot base-devel vulkan-headers vulkan-icd-loader shaderc

Fedora/RHEL/CentOS:

sudo dnf install dpkg-dev fakeroot gcc gcc-c++ make libxcb-devel vulkan-headers vulkan-loader glslc

openSUSE:

sudo zypper install dpkg fakeroot gcc gcc-c++ make vulkan-headers vulkan-loader glslc

Android / Termux:

The download_cli.sh installer detects Termux and automatically selects the musl portable build (GOOSE_LINUX_VARIANT=musl). To install:

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

To build from source in Termux:

pkg install rust cmake protobuf clang build-essential
cargo build --release -p goose-cli --bin goose --no-default-features --features portable-default

Note: The musl/portable build disables local-inference (V8) and system-keyring (D-Bus SecretService) since neither is available on Android.

Original PR: aaif-goose#3890

Development Tools

  • Rust: Install via rustup
  • Node.js: Version 22.9.0 or later (use nvm for version management)
  • pnpm: Version 10 or later (managed via Hermit, or install globally)
  • just: Install via cargo install just after Rust is installed. More info

Build Process

1. Clone and Setup

git clone https://github.com/aaif-goose/goose.git
cd goose

2. Build

Build Goose CLI:

cargo build --release -p goose-cli --bin goose

This command should give you a list of possible packages in the workspace:

cargo test -p

3. Prepare the Desktop Application

cd ui/desktop
pnpm install

# Copy the goose binary to the expected location
mkdir -p src/bin
cp ../../target/release/goose src/bin/

4. Build the Application

Option A: ZIP Distribution (Recommended)

Works on all Linux distributions:

pnpm run make --targets=@electron-forge/maker-zip

Output: out/make/zip/linux/x64/goose-linux-x64-{version}.zip

Option B: DEB Package

For Debian/Ubuntu systems:

pnpm run make --targets=@electron-forge/maker-deb

Output: out/make/deb/x64/goose_{version}_amd64.deb

Option C: Both Formats

pnpm run make

5. Run the Application

From Build Directory

./out/goose-linux-x64/goose

Install DEB Package (if built)

sudo dpkg -i out/make/deb/x64/goose_*.deb

Troubleshooting

Common Issues

Missing System Dependencies

If you see errors about missing dpkg, fakeroot, Vulkan headers, or glslc:

# Install the missing packages for your distribution (see Prerequisites above)

GLib Warnings

You may see warnings like:

GLib-GObject: instance has no handler with id

These are harmless and don't affect functionality. To suppress them, create a launcher script:

#!/bin/bash
cd /path/to/goose/ui/desktop/out/goose-linux-x64
./goose 2>&1 | grep -v "GLib-GObject" | grep -v "browser_main_loop"

Goose Binary Not Found

If you see "Goose binary not found", ensure you've:

  1. Built the Rust binary: cargo build --release -p goose-cli --bin goose
  2. Copied it to the right location: cp ../../target/release/goose src/bin/
  3. Rebuilt the application: pnpm run make

Distribution-Specific Notes

Arch/Manjaro

  • The RPM maker is disabled by default as it's not compatible with Arch-based systems
  • Use the ZIP distribution method for maximum compatibility

Flatpak

Flatpak builds are supported via CI. To build locally:

# Install flatpak and flatpak-builder
sudo apt install flatpak flatpak-builder

# Add Flathub remote
flatpak remote-add --if-not-exists --user flathub https://dl.flathub.org/repo/flathub.flatpakrepo

# Build with Electron Forge
pnpm run make --targets=@electron-forge/maker-flatpak

Output: out/make/flatpak/x86_64/*.flatpak

Snap

Building as Snap packages is not currently supported but may be added in the future.

Development Workflow

For active development:

  1. Backend changes: Rebuild with cargo build --release -p goose-cli --bin goose and copy the binary
  2. Frontend changes: Use pnpm run start for hot reload during development
  3. Full rebuild: Run the complete build process above

Creating System Integration

Desktop Entry

Create ~/.local/share/applications/goose.desktop:

[Desktop Entry]
Name=goose AI Agent
Comment=Local AI agent for development tasks
Exec=/path/to/goose/ui/desktop/out/goose-linux-x64/goose %U
Icon=/path/to/goose/ui/desktop/out/goose-linux-x64/resources/app.asar.unpacked/src/images/icon.png
Terminal=false
Type=Application
Categories=Development;Utility;
StartupNotify=true
MimeType=x-scheme-handler/goose

System-wide Installation

To install system-wide:

sudo cp -r out/goose-linux-x64 /opt/goose
sudo ln -s /opt/goose/goose /usr/local/bin/goose-gui

Contributing

When contributing changes that affect the Linux build process, please:

  1. Test on multiple distributions if possible
  2. Update this documentation
  3. Update ui/desktop/README.md if needed
  4. Consider CI/CD implications for automated builds