Custom Distributions

Create tailored versions of Goose for your organization

Goose’s architecture is designed for extensibility, allowing organizations to create custom distributions (sometimes called “white labeling”) tailored to specific needs—whether that’s preconfigured models, custom tools, branded interfaces, or entirely new user experiences.

Overview

Custom distributions enable you to:

• Preconfigure AI providers: Ship with a specific model (local or cloud) and API credentials
• Bundle custom tools: Include proprietary MCP extensions for internal data sources
• Customize the experience: Modify branding, UI, and default behaviors
• Target specific audiences: Create specialized versions for developers, legal teams, designers, etc.

Architecture

Goose separates concerns into distinct layers:

• User Interfaces: CLI (goose-cli), Desktop (Electron), or your custom UI
• Server Layer: goose-server (binary: goosed) provides REST API
• Core Logic: goose crate handles agents, providers, and extensions
• Customization Points: Providers, extensions, recipes, and configuration

Key Customization Points

What You Want	Where to Look	Complexity
Preconfigure a model/provider	config.yaml, environment variables	Low
Add custom AI providers	crates/goose/src/providers/	Low-Medium
Bundle custom MCP extensions	config.yaml, ui/desktop/src/built-in-extensions.json	Medium
Modify system prompts	crates/goose/src/prompts/	Low
Customize desktop branding	ui/desktop/ (icons, names, colors)	Medium
Build a new UI (web, mobile)	Integrate with goose-server REST API or ACP	High
Create guided workflows	Recipes (YAML-based task definitions)	Low

Getting Started

1. Fork and Clone

git clone https://github.com/YOUR_ORG/goose.git
cd goose

2. Choose Your Strategy

Configuration-only: Modify config files and environment variables (no code changes)

# init-config.yaml - Applied on first run
GOOSE_PROVIDER: anthropic
GOOSE_MODEL: claude-sonnet-4-20250514

Extension-based: Add custom MCP servers for your tools (minimal core changes)

{
  "id": "internal-data",
  "name": "Internal Data Lake",
  "type": "stdio",
  "cmd": "python",
  "args": ["/path/to/internal_mcp.py"]
}

Deep customization: Modify core behavior, UI, or add new providers (requires Rust knowledge)

3. Build and Distribute

See the main repository documentation:

• Linux: BUILDING_LINUX.md
• Docker: BUILDING_DOCKER.md
• Desktop: ui/desktop/README.md

Common Distribution Scenarios

Local Model Distribution

Ship Goose preconfigured to use a local Ollama model:

# init-config.yaml
GOOSE_PROVIDER: ollama
GOOSE_MODEL: qwen3-coder:latest

# Environment defaults in launcher
export GOOSE_PROVIDER=ollama
export GOOSE_MODEL=qwen3-coder:latest
export OLLAMA_HOST=http://localhost:11434

Corporate Distribution with Managed Keys

Distribute internally with pre-provisioned API keys:

# config.yaml
GOOSE_PROVIDER: anthropic
GOOSE_MODEL: claude-sonnet-4-20250514

# Inject secrets at install time via MDM
goose configure set-secret ANTHROPIC_API_KEY "your-corporate-key"

Secrets are stored in system keyring by default, with file-based fallback available via GOOSE_DISABLE_KEYRING=1.

Custom Branding

Rebrand the desktop application:

1. Replace visual assets in ui/desktop/src/images/:

• icon.png, icon.ico, icon.icns

2. Modify application metadata in ui/desktop/forge.config.ts:

module.exports = {
  packagerConfig: {
    name: 'YourCompany AI Assistant',
    executableName: 'yourcompany-ai',
    icon: 'src/images/your-icon',
  },
};

3. Update system prompt in crates/goose/src/prompts/system.md:

You are an AI assistant called [YourName], created by [YourCompany].

4. Set environment variables consistently:

export GITHUB_OWNER="your-org"
export GITHUB_REPO="your-goose-fork"
export GOOSE_BUNDLE_NAME="YourProduct-goose"

Adding Custom Tools

Create MCP extensions for internal systems:

# internal_data_mcp.py
from mcp.server import Server

server = Server("internal-data")

@server.tool()
async def query_data_lake(query: str) -> str:
    """Query the corporate data lake."""
    # Your implementation
    return results

Bundle as a built-in extension in ui/desktop/src/built-in-extensions.json:

{
  "id": "internal-data",
  "name": "Internal Data Lake",
  "enabled": true,
  "type": "stdio",
  "cmd": "python",
  "args": ["/opt/corp-goose/internal_data_mcp.py"]
}

Audience-Specific Distributions

Create specialized versions using recipes:

# legal-assistant.yaml
title: Legal Research Assistant
description: AI assistant for legal professionals

instructions: |
  You are a legal research assistant. You help lawyers with:
  - Case law research
  - Document review and summarization
  - Contract analysis
  
  Always cite sources. Flag when uncertain.

extensions:
  - type: builtin
    name: developer
  - type: stdio
    name: legal-database
    cmd: python
    args: ["/opt/legal-goose/legal_db_mcp.py"]

settings:
  goose_provider: anthropic
  goose_model: claude-sonnet-4-20250514

Important Considerations

Licensing

Goose is licensed under Apache License 2.0 (ASL v2). Custom distributions must:

• Include the original license and copyright notices
• Clearly indicate any modifications made
• Not use “Goose” trademarks in ways that imply official endorsement

See the Apache License FAQ for compliance guidance.

Contributing Back

While you’re free to maintain private forks, contributing improvements upstream benefits everyone—including your distribution. Private forks that diverge significantly:

• Become expensive to maintain
• Miss out on security updates and new features
• Require manual merging of upstream changes

Consider upstreaming generic improvements while keeping only organization-specific customizations private.

Telemetry

Goose includes optional telemetry. For custom distributions:

# Disable telemetry completely
export GOOSE_DISABLE_TELEMETRY=1

Or modify crates/goose/src/posthog.rs to point to your own PostHog instance.

Staying Current

To benefit from upstream improvements:

1. Regularly sync your fork with the main repository
2. Keep customizations isolated in config files or separate extension repos
3. Use recipes for workflow customization rather than code changes
4. Subscribe to release announcements for breaking changes

Configuration Precedence

Goose loads configuration in this order (later sources override earlier ones):

1. Built-in defaults
2. init-config.yaml (first run only)
3. ~/.config/goose/config.yaml
4. Environment variables (highest priority)

File Locations

File	Location	Purpose
Config	~/.config/goose/config.yaml	User settings
Secrets	System keyring or ~/.config/goose/secrets.yaml	API keys
Sessions	~/.local/share/goose/sessions/	Conversation history
Custom providers	~/.config/goose/custom_providers/	Declarative providers

Resources

• Full guide: CUSTOM_DISTROS.md in source repository
• Build instructions: BUILDING_LINUX.md, BUILDING_DOCKER.md
• Desktop UI: ui/desktop/README.md
• Provider implementation: crates/goose/src/providers/base.rs
• Extension config: crates/goose/src/agents/extension.rs