How to Build the Goose Project from Source: Complete Linux Guide

To build Goose from source, install Rust and Node.js, compile the Rust backend with cargo build --release -p goose-server, then package the Electron UI using pnpm run make after copying the binary to ui/desktop/src/bin/.

Goose is an AI-agent framework written in Rust that provides a CLI, MCP server, and Electron desktop UI. Building the Goose project from source involves compiling the Rust workspace (defined in Cargo.toml) and bundling the TypeScript frontend into a distributable Electron application. This guide follows the official build instructions maintained in BUILDING_LINUX.md within the aaif-goose/goose repository.

Prerequisites

You must install system build tools, the Rust toolchain, and Node.js before compiling. The exact package names vary by distribution.

System Dependencies

Install platform-specific packages:

• Debian/Ubuntu: sudo apt install dpkg fakeroot build-essential libxcb1-dev libxcb-util-dev protobuf-compiler
• Arch/Manjaro: sudo pacman -S dpkg fakeroot base-devel
• Fedora/RHEL: sudo dnf install dpkg-dev fakeroot gcc gcc-c++ make libxcb-devel

The complete prerequisite list is documented in BUILDING_LINUX.md at the repository root.

Rust and Node.js Toolchains

Install Rust via rustup:

curl https://sh.rustup.rs -sSf | sh

Install Node.js (≥ 22.9) and pnpm (≥ 10):

nvm install 22
npm i -g pnpm

Optionally, activate Hermit (source bin/activate-hermit) for reproducible toolchains, though manual installation is sufficient if versions match requirements.

Clone the Repository

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

The workspace configuration in Cargo.toml declares all crates under crates/ along with the bundled V8 vendor.

Build the Rust Backend

Compile the goosed server binary in release mode:

cargo build --release -p goose-server

This produces target/release/goosed. The entry point is crates/goose-server/src/main.rs, which initializes the agent server, MCP handlers, and CLI interface.

Package the Desktop Application

The Electron UI resides in ui/desktop/ and requires the Rust binary to be present before packaging.

Install Node Dependencies

cd ui/desktop
pnpm install

Copy the Server Binary

Create the expected directory and copy the compiled binary:

mkdir -p src/bin
cp ../../target/release/goosed src/bin/

The Electron application spawns src/bin/goosed when launching the desktop process.

Build Installable Packages

Choose ZIP for universal Linux distribution or DEB for Debian/Ubuntu systems:

ZIP (recommended):

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

Output location: out/make/zip/linux/x64/goose-linux-x64-<version>.zip

DEB (Debian/Ubuntu):

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

Output location: out/make/deb/x64/goose_<version>_amd64.deb

Run the Application

Execute directly from the build output:

./out/goose-linux-x64/goose

Or install the DEB package system-wide:

sudo dpkg -i out/make/deb/x64/goose_*.deb
goose  # Available in $PATH

Alternative: Docker Build

For isolated builds, use the provided Dockerfile:

docker build -t goose:local .
docker run --rm -it goose:local bash

# Inside the container, run the cargo and pnpm build steps

See BUILDING_DOCKER.md for complete Docker instructions and multi-arch builds.

Summary

• Install system dependencies (dpkg, fakeroot, build-essential, libxcb libraries, protobuf-compiler) and development toolchains (Rust, Node ≥ 22.9, pnpm ≥ 10)
• Build the Rust backend with cargo build --release -p goose-server, producing target/release/goosed
• Copy the goosed binary to ui/desktop/src/bin/ so the Electron app can spawn the server process
• Install frontend dependencies with pnpm install and package with pnpm run make --targets=@electron-forge/maker-zip (or --maker-deb)
• Execute the binary from out/goose-linux-x64/goose or install the generated DEB package

Frequently Asked Questions

What is the minimum Node.js version required to build Goose?

Node.js 22.9 or higher is required, along with pnpm 10 or newer. The Electron tooling and dependency resolution will fail with older versions according to the build specifications in ui/desktop/package.json.

Where does the build output place the final binaries?

The Rust compiler places the goosed server binary at target/release/goosed in the repository root. The Electron packager generates ZIP archives in ui/desktop/out/make/zip/linux/x64/ and DEB packages in ui/desktop/out/make/deb/x64/.

Can I use Just commands instead of running cargo and pnpm manually?

Yes. The repository includes a justfile with helper commands such as just release-binary that automate the Rust build and binary placement steps, streamlining the build process for frequent contributors.

Why does the UI build fail if I skip copying the server binary?

The Electron application hardcodes the path src/bin/goosed (relative to ui/desktop/) to spawn the agent backend process. Without this file present during pnpm run make or at runtime, the application cannot initialize the MCP server and will exit with a file-not-found error.

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