Prerequisites for Running Goose: Desktop, CLI, and Docker Setup Guide

Running Goose requires the Rust toolchain for building from source, Node.js 18+ and pnpm 10+ for the desktop GUI, and Docker 20.10+ with Buildx for containerized deployment.

Goose is an open-source AI agent framework maintained by Block (aaif-goose/goose) that supports desktop, command-line, and containerized execution modes. Before you can build or execute the agent, you must install specific system-level dependencies based on your chosen deployment method.

Desktop Application Prerequisites

The desktop UI resides in ui/desktop and is built with Electron. The build process compiles the Rust backend (goose-server) and bundles it with the TypeScript frontend, requiring both ecosystems to be present on your system.

Required Development Tools

You need the following toolchain components regardless of your host operating system:

• Rust toolchain – Required to compile the backend server. The root README lists this under development prerequisites, and cargo build --release -p goose-server compiles the binary.
• Node.js ≥ 18 – The UI bundle uses modern ECMAScript features. According to ui/acp/README.md, Node.js 18+ is mandatory for the ACP client.
• pnpm ≥ 10 – The package manager drives the Electron build process. This is also specified in ui/acp/README.md under the prerequisites section.

Linux System Libraries

On Linux hosts, additional system packages are required for native module compilation and packaging. The BUILDING_LINUX.md file enumerates these for various distributions:

• Debian/Ubuntu: libxcb1-dev, libxcb-util-dev, protobuf-compiler, dpkg, fakeroot, build-essential
• Other distributions: Arch, Fedora, and openSUSE require equivalent XCB headers and packaging tools

These dependencies support the native windowing system integration and .deb package generation.

Development Environment Setup

The following script installs the core prerequisites on macOS or Linux:

# Install Rust

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

# Install Node.js 22 via nvm

nvm install 22
nvm use 22

# Install pnpm

corepack enable
corepack prepare pnpm@latest --activate

# Linux: install system dependencies

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

CLI-Only Prerequisites

If you only need the command-line tool without the desktop interface, you can reduce the dependency footprint while maintaining full agent functionality.

Building from Source

To compile the goose binary locally, you only need:

• Rust toolchain – Sufficient for cargo build of the CLI package
• Git – To clone the repository at github.com/aaif-goose/goose

You can skip Node.js and pnpm unless you plan to use the npm-distributed binary packages mentioned in ui/goose-binary/README.md.

Using Pre-Built Binaries

Goose publishes pre-compiled binaries on GitHub Releases that require no local build tools. These artifacts work on compatible operating systems and architectures without Rust or Node.js installed.

Download and install the latest stable release:

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

Docker-Based Execution

For isolated deployment or CI/CD pipelines, Goose provides a multi-stage Dockerfile that produces a minimal image containing only the goose binary.

Container Build Requirements

According to BUILDING_DOCKER.md, building the image requires:

• Docker Engine ≥ 20.10 – For building and running containers
• Docker Buildx – Enables multi-architecture builds (amd64 and arm64)
• Git – To clone the source repository before building

Building and Running Locally

Clone the repository and build the image:

git clone https://github.com/aaif-goose/goose.git
cd goose
docker build -t goose:local .

Run Goose in a container with your API keys:

docker run --rm \
  -e GOOSE_PROVIDER=openai \
  -e GOOSE_MODEL=gpt-4o \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  goose:local run -t "Explain the benefits of Docker"

You can also use the pre-built image from the GitHub Container Registry without local compilation:

docker pull ghcr.io/aaif-goose/goose:latest

Summary

• Desktop GUI: Requires Rust, Node.js ≥ 18, pnpm ≥ 10, and Linux system libraries (libxcb, protobuf-compiler, dpkg, fakeroot) as documented in BUILDING_LINUX.md and ui/acp/README.md.
• CLI from source: Needs only the Rust toolchain to run cargo build --release -p goose-server or compile the goose binary directly.
• Pre-built CLI: No prerequisites except a compatible operating system; install via the official download script.
• Docker deployment: Requires Docker Engine ≥ 20.10 and Buildx for multi-arch support, as specified in BUILDING_DOCKER.md.

Frequently Asked Questions

Do I need Node.js to run the Goose CLI?

No. Node.js is only required for building the desktop Electron application. The CLI binary compiled from Rust or downloaded from GitHub Releases runs independently without any JavaScript runtime.

Can I run Goose without installing Rust?

Yes. You can use the pre-built binaries available on GitHub Releases, which require no compilation tools. Alternatively, run the official Docker image from ghcr.io/aaif-goose/goose:latest to avoid installing any build dependencies locally.

What are the minimum Docker requirements for Goose?

You need Docker Engine version 20.10 or higher and Docker Buildx for multi-architecture builds. These requirements are documented in BUILDING_DOCKER.md at lines 28-34. Git is also required to clone the repository unless you are using a pre-built image.

Are the prerequisites different for Windows?

Windows requires the same core tools—Rust toolchain, Node.js ≥ 18, and pnpm ≥ 10—but does not need the Linux-specific system libraries like libxcb or dpkg. For Windows desktop builds, consult ui/desktop/README.md for platform-specific Electron packaging instructions.

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