> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/block/goose/llms.txt
> Use this file to discover all available pages before exploring further.

# Development Setup

> Set up your development environment for contributing to Goose

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](https://cashapp.github.io/hermit/) to manage development dependencies (Rust, Node, npm, just, etc.).

Activate Hermit when entering the project:

```bash theme={null}
source bin/activate-hermit
```

Or add [shell hook auto-activation](https://cashapp.github.io/hermit/usage/shell/#shell-hooks) so Hermit activates automatically when you `cd` into the project (recommended).

### WSL Users (Windows)

For WSL users, install additional dependencies:

```bash theme={null}
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

```bash theme={null}
cd goose
source ./bin/activate-hermit
cargo build
```

Debug builds are available in `./target/debug/`:

```bash theme={null}
./target/debug/goose --help
```

### First-Time Configuration

Configure a provider connection:

```bash theme={null}
./target/debug/goose configure
```

Start a session:

```bash theme={null}
./target/debug/goose session
```

### Development Commands

```bash theme={null}
# 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

```bash theme={null}
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:

```bash theme={null}
just run-ui-only
```

### Debug Build UI

Run the UI with debug Rust binaries (faster compilation):

```bash theme={null}
just run-dev
```

### UI Testing

```bash theme={null}
cd ui/desktop
npm test
```

## Working with the Server

### Debugging the Server

To debug the Goose server, run it from an IDE with:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
# 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:

```bash theme={null}
# 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](https://github.com/casey/just) as a command runner. See all available commands:

```bash theme={null}
just --list
```

Commonly used commands:

```bash theme={null}
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](https://langfuse.com/self-hosting/docker-compose)
2. Create organization, project, and API credentials
3. Set environment variables:

```bash theme={null}
export LANGFUSE_INIT_PROJECT_PUBLIC_KEY=publickey-local
export LANGFUSE_INIT_PROJECT_SECRET_KEY=secretkey-local
```

4. View traces at [http://localhost:3000](http://localhost:3000)

## Next Steps

* Learn about [Architecture](/development/architecture)
* Understand [Testing](/development/testing)
* Build [Extensions](/development/extension-development)
* Create [Providers](/development/provider-interface)