Troubleshooting

info

This feature is in Alpha. The menu feature doesn't exist yet.

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

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/config.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/config.yaml and add the MCP servers under the extensions section:

extensions:
  linuxtools:
    enabled: true
    type: stdio
    name: linuxtools
    description: Linux system diagnostics
    cmd: /home/linuxbrew/.linuxbrew/bin/linux-mcp-server
    args: []
    envs: {}
    timeout: 300

  dosu:
    enabled: true
    type: streamable_http
    name: Dosu
    description: Dosu AI documentation assistant
    uri: https://api.dosu.dev/v1/mcp
    headers:
      X-Deployment-ID: 83775020-c22e-485a-a222-987b2f5a3823

Step 3: Restart Goose

Restart Goose to load the MCP servers:

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

Goose will prompt you to authenticate with Dosu the first time it tries to use the extension. Follow the browser prompt to complete sign-in.

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/opencode.json.

Step 1: Install MCP Servers

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

Step 2: Configure OpenCode

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

{
  "mcp": {
    "linux-mcp-server": {
      "type": "local",
      "command": ["/home/linuxbrew/.linuxbrew/bin/linux-mcp-server"],
      "enabled": true,
      "environment": {
        "LOG_LEVEL": "info"
      }
    },
    "dosu": {
      "type": "remote",
      "url": "https://api.dosu.dev/v1/mcp",
      "enabled": true,
      "headers": {
        "X-Deployment-ID": "83775020-c22e-485a-a222-987b2f5a3823"
      }
    }
  }
}

Step 3: Authenticate with Dosu

Dosu requires a one-time OAuth login. Run:

opencode mcp auth dosu

This opens your browser to complete the sign-in. After authorizing, OpenCode stores the token automatically — you won't need to repeat this step.

Step 4: 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."