Troubleshooting

info

This does not exist yet, it's here to document how we expect the feature to work. This is also only documented the tooling we're shipping, not a general troubleshooting guide.

Bluefin AI page - gives this page more context on our plans for Bluespeed

In the menu select "Ask Bluefin" to use the chat agent.

"Ask Bluefin", is a custom operating system agent. For you new users, a system designed to help you learn Linux, without the toil of digging through the internet or being told that you installed the wrong Linux distribution. "Ask Bluefin" is trained on the operating system and its documentation, so it's always learning from the source of truth and tweaked by the community. For you Linux veterans, a power diagnostic tool for your local PC, with built in integration to your servers and cluster ...

Ctrl-Alt-Shift- g will invoke a quicklaunch so that you can invoke the help agent with one keystroke:

Installation

Linux
macOS

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

This installs linux-mcp-server + the goose client + our config, follow the instructions in the terminal. TODO:

onboarding process
"Bring your own LLM": Select whatever combo of commercial and local AI they can via goose's providers
Local setup goes to:
- Ramalama config and service unit
- Choice of local model
A docs2db setup preloaded with Bluefin's documentation

Configuration

info

You need to install and configure the MCP servers to use this. Pull requests to automate this welcome!

linux-mcp-server

Provides system diagnostics and monitoring tools:

System information (OS, kernel, hardware)
Process management
Service monitoring (systemd)
Log access (journalctl)
Network diagnostics
File system inspection

Repository: ublue-os/linux-mcp-server

dosu-mcp

Connects your agent to Bluefin documentation and knowledge bases:

Search documentation sources
Replicates ask.projectbluefin.io on your system

Repository: dosubot/dosu-mcp

MCP Configuration

The configuration process differs depending on which AI client you're using:

Goose
OpenCode

Goose Configuration

Goose stores MCP server configurations in ~/.config/goose/profiles.yaml.

Step 1: Install MCP Servers

# Install linux-mcp-server
brew install ublue-os/tap/linux-mcp-server

**Step 2: Configure Goose**

Edit `~/.config/goose/profiles.yaml` and add the MCP servers under the `mcp_servers` section:

```yaml
provider: google-gemini
processor: gemini-2.0-flash-exp
accelerator: gemini-2.0-flash-exp
moderator: passive

mcp_servers:
  linux-mcp-server:
    command: /home/linuxbrew/.linuxbrew/bin/linux-mcp-server
    env:
      LOG_LEVEL: info

  dosu:
    command: uvx
    args:
      - dosu-mcp
    env:
      DOSU_DEPLOYMENT_SLUG: 018da525-51f8-75ec-befc-c36a5f27ce5c

Authentication: When you first start Goose with Google Gemini, it will open your browser to authenticate with your Google account. No API key configuration required.

Step 3: Restart Goose

Restart Goose to load the MCP servers:

# Exit Goose (Ctrl+D or /exit)
# Start Goose again
goose session start

Note on Dosu Configuration: The Bluefin documentation deployment UUID shown above can be shared amongst all Bluefin users - no API key required for read-only access to the documentation knowledge base.

OpenCode Configuration

OpenCode stores MCP server configurations in ~/.config/opencode/config.json.

Step 1: Install MCP Servers

# Install linux-mcp-server
brew install ublue-os/tap/linux-mcp-server

# Install dosu-mcp (requires uv)
brew install uv

Step 2: Configure OpenCode

Edit ~/.config/opencode/config.json and add the MCP servers:

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "linux-mcp-server",
      "args": [],
      "env": {
        "LOG_LEVEL": "info"
      }
    },
    "dosu": {
      "command": "uvx",
      "args": ["dosu-mcp"],
      "env": {
        "DOSU_DEPLOYMENT_SLUG": "018da525-51f8-75ec-befc-c36a5f27ce5c"
      }
    }
  }
}

Step 3: Restart OpenCode

Close and reopen OpenCode to load the MCP servers. You can verify they're loaded by asking:

"What MCP servers are available?"

Security Considerations

MCP servers run with your user permissions
Only install MCP servers from trusted sources
Review server documentation for required permissions
Use environment variables for sensitive credentials (don't hardcode in config)
Regularly update MCP servers to get security patches

Automated Troubleshooting

You can ask the tool things about your system using natural language:

Top CPU usage

System Health

Note: these are taken from the linux-server-mcp page but you get the idea:

I want to check...	Use this tool	Example Prompt
OS / Kernel	`get_system_information`	"What OS version is this?"
CPU Load	`get_cpu_information`	"Is the CPU overloaded?"
Memory / RAM	`get_memory_information`	"How much free RAM do I have?"
Disk Space	`get_disk_usage`	"Are any disks full?"
Hardware	`get_hardware_information`	"List the PCI devices."