AI Integration in Bluefin#

AI Integration in Bluefin represents a strategic approach to incorporating local, open-source AI tools and standardized protocols into the desktop environment. The project, known internally as "Bluespeed," focuses on delivering community-driven AI capabilities while maintaining user privacy and control. Unlike traditional cloud-dependent AI solutions, Bluefin's implementation emphasizes local-first execution with opt-in functionality, utilizing the Model Context Protocol (MCP) as a standardization layer for connecting AI agents to system data and knowledge bases.

The integration is built on curated Homebrew bundles distributed through the ujust bbrew command, with Goose serving as the primary AI agent platform and RamaLama providing container-based local LLM management. This architecture distinguishes itself from standard development environments by maintaining Bluefin's core principle of system immutability while providing flexible, reproducible AI tooling through layered package management.

Architecture and Design Philosophy#

Strategic Vision: Bluespeed#

The Bluespeed initiative drives open-source AI adoption through several core principles:

Local-First Architecture: AI capabilities are designed as "local AI controlled by the user" with opt-in functionality rather than mandatory background services. The endpoint is local-only by default, ensuring privacy and user control.

Open Source Commitment: The project explicitly focuses on open-source-first implementations, avoiding proprietary solutions and prioritizing community-driven tools.

API-Driven Approach: Rather than building standalone products, the approach enables APIs through RamaLama, offering an AI API layer for application developers.

Standardization Through MCP: The Model Context Protocol (MCP) serves as "USB-C for AI", standardizing how AI agents connect to system resources and knowledge bases. This aligns with Red Hat's broader AI standardization initiatives.

Three-Layer Package Management#

Bluefin's AI integration leverages the three-layer package management strategy: immutable system base, Flatpak applications, and Homebrew CLI tools. AI tools are distributed primarily through curated Brewfiles in the projectbluefin/common repository, ensuring they don't compromise system immutability while remaining fully accessible to users.

Safety Model#

The implementation distinguishes between read-only diagnostics for introspection (safe by default) and "agentic" or "power mode" capabilities that can make system changes. Read-only MCP tools are safe by default, while any agentic functionality requires explicit user consent as a "power mode."

Core Components#

Goose AI Agent#

Goose is an open-source, local-first AI agent developed by Block that serves as Bluefin's primary AI interface. Available as both desktop application and command-line interface, Goose operates using three main components:

1. Interface - Desktop app or CLI collecting user input and displaying output
2. Agent - Core logic managing the interactive loop between user, LLM, and extensions
3. Extensions - MCP-based components providing specific tools and capabilities

Key Capabilities#

• Local-first execution with full development environment access
• Multi-provider LLM support (OpenAI, Anthropic, Google, Ollama, and more)
• Extensible architecture via MCP servers
• Context engineering through .goosehints, Skills, and Recipes
• MIT licensed and community-driven

Built-in Extensions#

Goose includes several built-in extensions:

• Developer - Shell commands, file editing, code analysis
• Computer Controller - System automation, web scraping
• Memory - Persistent storage across sessions
• Todo - Task management within sessions
• Extension Manager - Enable/disable extensions dynamically
• Chat Recall - Search and reference past conversations

Installation in Bluefin#

Goose is available through multiple installation methods:

• CLI: Included in ai-tools.Brewfile as block-goose-cli
• Desktop: Available as goose-linux cask
• Both interfaces share core configurations stored in ~/.config/goose/config.yaml

OpenCode AI Agent#

OpenCode is an open source AI coding agent with over 100,000 GitHub stars and 2.5M monthly developers, available as an alternative to Goose. It provides:

• Terminal-first design with TUI (Terminal User Interface)
• Multiple specialized agents (Build, Plan, General, Explore)
• First-class MCP support with OAuth authentication
• Privacy-first design storing no code or context data
• LSP server integration for code intelligence

OpenCode vs. Goose#

Installation in Bluefin#

OpenCode desktop is available as opencode-desktop-linux from the experimental tap.

RamaLama#

RamaLama is a container-based runtime for managing local LLMs, chosen over Ollama because it hardware-accelerates transparently via containers and handles CUDA/ROCm updates through existing update tools.

Key advantages:

• Transparent hardware acceleration (NVIDIA CUDA, AMD ROCm)
• Container-based isolation
• Integration with existing system update mechanisms
• OpenAI-compatible API endpoints

Installation#

RamaLama is included in ai-tools.Brewfile and installed via:

ujust bbrew # Select ai-tools bundle
# or
brew install ramalama

Usage#

# Start local LLM server
ramalama serve --runtime-args="--jinja" ollama://phi-4

# Expose OpenAI-compatible endpoint
# Applications can connect to local endpoint instead of cloud APIs

Model Context Protocol (MCP)#

MCP is an open standard developed by Anthropic that enables interoperability between AI agents and external systems. In Bluefin, MCP serves as the integration layer between AI agents (Goose, OpenCode) and system resources.

linux-mcp-server#

The linux-mcp-server provides Linux system administration and diagnostics capabilities through MCP. The server works 100% plug-and-play on Bluefin with no modifications needed, using standard systemd/POSIX commands.

Installation:

brew install ublue-os/tap/linux-mcp-server
goose-mcp-setup # Configures Goose integration

The linux-mcp-server formula includes a goose-mcp-setup script that automatically:

1. Creates ~/.config/goose/config.yaml
2. Configures the linux-tools MCP extension
3. Sets up Gemini CLI integration with environment variables

MCP Ecosystem#

Both Goose and OpenCode support access to 3000+ MCP servers including:

• Filesystem tools for code analysis and file management
• Database connectors (PostgreSQL, MySQL, etc.)
• Knowledge graph memory for persistent storage
• Cloud provider integrations (GitHub, GitLab, etc.)
• Documentation search (Context7, Grep by Vercel)

Additional AI Tools#

The ai-tools.Brewfile includes multiple complementary tools:

CLI Tools:

• aichat - AI chat interface
• gemini-cli - Google Gemini CLI
• llm - LLM command line tool
• mods - AI-powered shell commands
• whisper-cpp - Speech recognition

Desktop Applications:

• LM Studio - Local LLM management with GUI
• Antigravity 1.20.6 - AI-powered IDE
• Jan AI (Flatpak) - AI application platform

Installation and Configuration#

Installing AI Tools#

The primary method for installing AI tools is through the ujust bbrew command:

ujust bbrew
# Select "ai-tools" from interactive menu

This command:

1. Checks if Bold Brew (bbrew) is installed
2. Presents an interactive menu using gum choose
3. Executes the selected Brewfile (e.g., ai-tools.Brewfile)

Configuring Goose with MCP#

After installing AI tools, configure Goose to work with the MCP server:

brew install ublue-os/tap/linux-mcp-server
goose-mcp-setup

This creates ~/.config/goose/config.yaml with:

• Default Gemini CLI integration
• linux-tools extension configuration
• Environment variables for MCP server

Manual Configuration Example:

# ~/.config/goose/config.yaml

GOOSE_PROVIDER: "anthropic" # or "openai", "ollama" for local
GOOSE_MODEL: "claude-4.5-sonnet"
GOOSE_MODE: "smart_approve" # Balance between automation and safety

extensions:
  developer:
    bundled: true
    enabled: true
    type: builtin

  linux-tools:
    name: Linux Tools
    cmd: linux-mcp-server
    enabled: true
    type: stdio
    timeout: 300

Configuring OpenCode with MCP#

Create ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-5",
  "permission": {
    "*": "allow",
    "bash": "ask",
    "edit": "ask"
  },
  "mcp": {
    "linux-tools": {
      "type": "local",
      "command": ["linux-mcp-server"],
      "enabled": true
    }
  }
}

Setting Up Local LLMs#

For users preferring local, offline AI:

# Install RamaLama
brew install ramalama

# Pull a model
ramalama pull ollama://qwen2.5-coder:32b

# Start server with OpenAI-compatible API
ramalama serve ollama://qwen2.5-coder:32b

# Configure Goose to use local endpoint
# In ~/.config/goose/config.yaml:
GOOSE_PROVIDER: "ollama"
GOOSE_API_BASE: "http://localhost:11434"

Hardware Requirements for Local LLMs#

For running 30-32B parameter models locally:

• RAM: 64-128GB minimum
• VRAM: 24GB+ (NVIDIA RTX 4090 ideal; RTX 4080 Super 16GB workable with CPU offloading)
• Storage: Fast NVMe required

Recommended Models:

• Qwen2.5-Coder:32b - Specialized for coding tasks
• Nemotron 30B
• Qwen3-Coder-30B

Performance Expectations:

• Models fitting entirely in VRAM: 50-60 tokens/second on high-end hardware
• Framework 13 laptops can handle 7-14B models
• Desktops with discrete GPUs required for 30B+ models
• Set context window to 16K minimum, preferably 32K or higher

Usage Examples#

Using Goose for Code Analysis#

# Start interactive session
goose session

# One-off task
goose run -t "analyze this codebase for security issues"

# With specific extensions
goose session --with-builtin developer --with-extension linux-tools

Using OpenCode#

# Start TUI
opencode

# Run single command
opencode run "Explain how this code works"

# Web interface
opencode web --port 4096

Using RamaLama with AI Tools#

# List available models
ramalama list

# Serve a model
ramalama serve ollama://phi-4

# Use with applications expecting OpenAI API
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "phi-4", "messages": [{"role": "user", "content": "Hello"}]}'

System Administration with MCP#

When Goose is configured with linux-mcp-server:

goose run -t "check system logs for errors in the past hour"
goose run -t "analyze disk usage and suggest cleanup"
goose run -t "review systemd service status"

Integration with Bluefin Architecture#

Immutability and System Stability#

Bluefin's strict immutability via LockLayering=true prevents system degradation from AI tool installations. Unlike traditional Linux distributions, AI tools are installed via Homebrew in user space, preserving the immutable base while providing full functionality.

Container-Based Execution#

RamaLama runs LLMs within containers, isolating AI workloads from the host system. This approach:

• Provides transparent hardware acceleration (CUDA/ROCm)
• Enables reproducible LLM deployments
• Integrates with Bluefin's container-first philosophy
• Simplifies driver updates through container image layers

Automatic Updates#

System images check for updates every 6 hours with bootc, while Homebrew tools update via ujust update. This ensures AI tools stay current without manual intervention.

Development Container Integration#

Bluefin includes ublue-os/toolboxes for development environments, enabling AI agents to operate within isolated container contexts. Goose and OpenCode can both run inside Distrobox containers, providing project-specific AI configurations without affecting the host.

Troubleshooting#

Antigravity Authentication Issues#

If you experience authentication failures or the browser doesn't open Antigravity after authentication, manually register the URL scheme handler:

xdg-mime default antigravity-url-handler.desktop x-scheme-handler/antigravity
update-desktop-database ~/.local/share/applications

This issue can occur when the URL scheme handler isn't properly registered with your desktop environment. The commands above register the antigravity:// URL scheme so authentication callbacks work correctly.

Advanced Features#

Context Engineering with Goose#

Goose provides multiple ways to configure context:

1. .goosehints - Project-specific instructions placed in repository root
2. Skills - Reusable instruction sets with supporting files
3. Recipes - Shareable workflow configurations with parameters

Multi-Model Configuration#

Goose supports lead/worker configuration for cost optimization:

• Lead model (GPT-4) for planning
• Worker model (GPT-4o-mini) for execution
• Automatic fallback when worker struggles

Headless Automation#

Goose supports headless mode for CI/CD integration:

goose run --no-session -t "Analyze code changes and generate report"

Security Features#

Permission Controls:

• .gooseignore files to prevent access to sensitive files
• Tool permissions to control extension capabilities
• Permission modes (auto, approve, chat, smart_approve)

OpenCode Security:

• Granular permission patterns with wildcards
• External directory controls
• Per-agent permission overrides

Future Roadmap#

Desktop Integration#

The "Ask Bluefin…" chatbot will be added to the menu, exposing a RamaLama OpenAI endpoint so users can swap in an LLM of their choice. The system uses a GTK chat app (alpaca or similar), where the copilot key is bound if it exists, with F1 or another help shortcut as fallback.

Knowledge Base Integration#

The project plans to RAG in official docs, source code, Homebrew docs, Flathub, Bazaar, ramalama, podman, podman desktop, bootc, devcontainers, vscode, etc., likely as a separate deliverable called "bluefin-knowledge".

Standardization Goals#

The final goal is to propose AI endpoints to major desktops (GNOME, KDE, etc.) for standardization.

Organizational Templates#

The pattern can be templated for Universal Blue custom images — organizations could fork it, ingest their own documentation/data, and have a versioned local AI agent. Example: "A Corporate team forks it, ingests their private Wiki, and ships a versioned 'Ask our Docs' agent that never touches the cloud."

Related Code Files#

Related Topics#

• Homebrew on Bluefin - Package management system for AI tools
• Container Development - Distrobox and devcontainer integration with AI agents
• System Architecture - Immutability and bootc update mechanism
• Universal Blue - Parent project providing custom image framework

External Documentation#

• Goose Documentation - Official Goose documentation
• OpenCode Documentation - OpenCode user guide
• Model Context Protocol - MCP specification
• MCP Server Directory - 3000+ available MCP servers
• Bluefin Troubleshooting Guide - Official AI integration documentation

References#

This article synthesizes information from:

• GitHub Issue #100: Bluespeed AI
• GitHub Issue #206: Ship a preconfigured bluefin setup
• GitHub Issue #205: Add dosu mcp server
• Bluefin Newsletter
• Bluefin OS Documentation
• Hardware Requirements Discussion
• Goose Official Documentation
• OpenCode Official Documentation