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

> Learn the prerequisites for running Goose. Discover setup requirements for desktop, CLI, and Docker, including Rust, Node.js, pnpm, and Docker versions.

- Repository: [goose/goose](https://github.com/aaif-goose/goose)
- Tags: getting-started
- Published: 2026-04-07

---

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

```bash

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

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

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

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

```bash
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`](https://github.com/aaif-goose/goose/blob/main/BUILDING_LINUX.md) and [`ui/acp/README.md`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/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`](https://github.com/aaif-goose/goose/blob/main/ui/desktop/README.md) for platform-specific Electron packaging instructions.