> ## 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.

# 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

```mermaid theme={null}
graph TB
    UI[User Interfaces] --> Server[goose-server]
    UI --> CLI[goose-cli]
    UI --> Custom[Custom UI]
    
    Server --> Core[Core goose crate]
    CLI --> Core
    Custom --> Core
    
    Core --> Providers[AI Providers]
    Core --> Extensions[MCP Extensions]
    Core --> Config[Config & Recipes]
```

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

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

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

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

```yaml theme={null}
# init-config.yaml
GOOSE_PROVIDER: ollama
GOOSE_MODEL: qwen3-coder:latest
```

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

```yaml theme={null}
# config.yaml
GOOSE_PROVIDER: anthropic
GOOSE_MODEL: claude-sonnet-4-20250514
```

```bash theme={null}
# Inject secrets at install time via MDM
goose configure set-secret ANTHROPIC_API_KEY "your-corporate-key"
```

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

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

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

```markdown theme={null}
You are an AI assistant called [YourName], created by [YourCompany].
```

**4. Set environment variables consistently**:

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

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

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

```yaml theme={null}
# 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](https://www.apache.org/foundation/license-faq.html) 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

<Tip>
  Consider upstreaming generic improvements while keeping only organization-specific customizations private.
</Tip>

### Telemetry

Goose includes optional telemetry. For custom distributions:

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