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
{
"id": "internal-data",
"name": "Internal Data Lake",
"type": "stdio",
"cmd": "python",
"args": ["/path/to/internal_mcp.py"]
}
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',
},
};
crates/goose/src/prompts/system.md:
You are an AI assistant called [YourName], created by [YourCompany].
export GITHUB_OWNER="your-org"
export GITHUB_REPO="your-goose-fork"
export GOOSE_BUNDLE_NAME="YourProduct-goose"
# 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
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
crates/goose/src/posthog.rs to point to your own PostHog instance.
Staying Current
To benefit from upstream improvements:
- Regularly sync your fork with the main repository
- Keep customizations isolated in config files or separate extension repos
- Use recipes for workflow customization rather than code changes
- Subscribe to release announcements for breaking changes
Configuration Precedence
Goose loads configuration in this order (later sources override earlier ones):
- Built-in defaults
init-config.yaml (first run only)~/.config/goose/config.yaml- 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
