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

> Learn to build Goose from source on Linux. Follow our guide to install dependencies, compile the Rust backend, and package the Electron UI for your project.

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

---

**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`](https://github.com/aaif-goose/goose/blob/main/Cargo.toml)) and bundling the TypeScript frontend into a distributable Electron application. This guide follows the official build instructions maintained in [`BUILDING_LINUX.md`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/BUILDING_LINUX.md) at the repository root.

### Rust and Node.js Toolchains

Install Rust via **rustup**:

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

```

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

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

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

```

The workspace configuration in [`Cargo.toml`](https://github.com/aaif-goose/goose/blob/main/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:

```bash
cargo build --release -p goose-server

```

This produces `target/release/goosed`. The entry point is [`crates/goose-server/src/main.rs`](https://github.com/aaif-goose/goose/blob/main/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

```bash
cd ui/desktop
pnpm install

```

### Copy the Server Binary

Create the expected directory and copy the compiled binary:

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

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

```

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

**DEB (Debian/Ubuntu):**

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

```bash
./out/goose-linux-x64/goose

```

Or install the DEB package system-wide:

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

```

## Alternative: Docker Build

For isolated builds, use the provided Dockerfile:

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