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 Configuration

Step 1: Install linux-mcp-server

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

Step 2: Configure Goose

Run the setup script that ships with linux-mcp-server. If a config already exists it prints the snippet to add manually instead:

goose-mcp-setup

This creates ~/.config/goose/config.yaml with the linux-tools extension pre-configured:

extensions:
  linux-tools:
    enabled: true
    type: stdio
    name: linux-tools
    description: Linux system administration and diagnostics
    cmd: /home/linuxbrew/.linuxbrew/bin/linux-mcp-server
    envs:
      LINUX_MCP_USER: <your-username>
      LINUX_MCP_LOG_LEVEL: INFO
      LINUX_MCP_SSH_KEY_PATH: ~/.ssh/id_ed25519
    timeout: 30
    bundled: null
    available_tools: []
    args: []

Step 3: Configure your LLM

For most providers — Anthropic, OpenAI, Gemini, etc. — run goose configure and follow the prompts to enter your API key.

For local models, Ramalama is the recommended option. It manages models as containers and serves an OpenAI-compatible endpoint that Goose reaches via the ollama provider:

brew install ramalama
ramalama serve qwen3:8b

Then run goose configure, select Ollama, and set OLLAMA_HOST to http://localhost:8080.

LM Studio (brew install ublue-os/tap/lm-studio-linux) is a graphical alternative — launch it, load a model, enable the local server, then select LM Studio in goose configure.

On the local network? Use Ghost.

Ghost is a shared local inference server running Qwen3-35B. No API key, no model download required. After goose-mcp-setup, run this to switch Goose over:

python3 -c "
import re, pathlib
p = pathlib.Path.home() / '.config/goose/config.yaml'
c = p.read_text()
c = re.sub(r'^GEMINI_CLI_COMMAND:.*\n', '', c, flags=re.MULTILINE)
c = re.sub(r'^GOOSE_PROVIDER:.*', 'GOOSE_PROVIDER: openai', c, flags=re.MULTILINE)
c = re.sub(r'^GOOSE_MODEL:.*', 'GOOSE_MODEL: unsloth/Qwen3.6-35B-A3B-GGUF', c, flags=re.MULTILINE)
if 'OPENAI_HOST' not in c:
    c = 'OPENAI_HOST: http://ghost.localdomain:8080\nOPENAI_API_KEY: not-needed\n' + c
p.write_text(c); print('Done — Goose is now pointing at Ghost.')
"

Step 4: Start Goose

goose session

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