Skip to main content
This guide walks you through setting up a local development environment for Goose.

​
Prerequisites

Goose includes Rust binaries alongside an Electron app for the GUI.

​
Hermit

We use Hermit to manage development dependencies (Rust, Node, npm, just, etc.). Activate Hermit when entering the project: 
source bin/activate-hermit
Or add shell hook auto-activation so Hermit activates automatically when you cd into the project (recommended).

​
WSL Users (Windows)

For WSL users, install additional dependencies: 
sudo apt update
sudo apt install build-essential  # Core build tools
sudo apt install libxcb1-dev       # X C Binding library

​
Building the Rust CLI

​
First Build

cd goose
source ./bin/activate-hermit
cargo build
Debug builds are available in ./target/debug/: 
./target/debug/goose --help

​
First-Time Configuration

Configure a provider connection: 
./target/debug/goose configure
Start a session: 
./target/debug/goose session

​
Development Commands

# Verify changes compile
cargo check

# Run tests
cargo test
cargo test -p goose          # specific crate

# Format code
cargo fmt

# Run linter
cargo clippy --all-targets -- -D warnings

# Quick iteration
cargo run -p goose-cli -- session

​
Building the Desktop UI

​
Running the UI

just run-ui
This command:
  1. Builds a release build of Rust (cargo build -r)
  2. Starts the Electron process
  3. Opens a window for first-time setup
Make GUI changes in ui/desktop.

​
UI-Only Development

If you’re only working on the UI and don’t need to rebuild Rust: 
just run-ui-only

​
Debug Build UI

Run the UI with debug Rust binaries (faster compilation): 
just run-dev

​
UI Testing

cd ui/desktop
npm test

​
Working with the Server

​
Debugging the Server

To debug the Goose server, run it from an IDE with: 
export GOOSE_SERVER__SECRET_KEY=test
cargo run --package goose-server --bin goosed -- agent
# OR
just run-server
The server listens on port 3000 by default. Change with GOOSE_PORT environment variable. Connect the UI to your running server: 
just debug-ui
This allows breakpoints and stepping through server code while interacting with the UI.

​
Regenerating OpenAPI Schema

The file ui/desktop/openapi.json is automatically generated. After making server API changes: 
just generate-openapi
This regenerates openapi.json and rebuilds the TypeScript client. Never edit ui/desktop/openapi.json manually. Make changes in crates/goose-server/src/.

​
Environment Variables

​
Provider Configuration

Change provider without reconfiguring: 
export GOOSE_PROVIDER=openai
# With API key
export OPENAI_API_KEY=sk-...
Supported provider env vars:
  • ANTHROPIC_API_KEY
  • OPENAI_API_KEY
  • DATABRICKS_HOST
  • GOOGLE_API_KEY
  • etc.

​
Isolating Test Environments

Use GOOSE_PATH_ROOT to isolate test data: 
# Test with clean environment
export GOOSE_PATH_ROOT="/tmp/goose-test"
./target/debug/goose session

# Or for a single command
GOOSE_PATH_ROOT="/tmp/goose-dev" cargo run -p goose-cli -- session
This creates isolated config/, data/, and state/ directories, preventing test sessions from affecting your main installation.

​
Development Loop

Typical workflow when making changes: 
# 1. Activate hermit (if not auto-activated)
source bin/activate-hermit

# 2. Make your changes

# 3. Format code
cargo fmt

# 4. Build
cargo build

# 5. Test
cargo test -p <crate>

# 6. Lint
cargo clippy --all-targets -- -D warnings

# 7. If server changes, regenerate OpenAPI
just generate-openapi

​
Useful Just Commands

We use just as a command runner. See all available commands: 
just --list
Commonly used commands: 
just release-binary       # Release build + OpenAPI
just run-ui               # Build and run UI
just run-server           # Run server
just generate-openapi     # Regenerate OpenAPI schema
just check-everything     # Run all style checks

​
Enabling Traces with Langfuse

For local tracing:
  1. Start local Langfuse
  2. Create organization, project, and API credentials
  3. Set environment variables:
export LANGFUSE_INIT_PROJECT_PUBLIC_KEY=publickey-local
export LANGFUSE_INIT_PROJECT_SECRET_KEY=secretkey-local
  1. View traces at http://localhost:3000

​
Next Steps

Build docs developers (and LLMs) love

Get started for freeTalk to us