### Install and Run Bluefin Docs

Source: https://github.com/projectbluefin/documentation/blob/main/AGENTS.md

Install project dependencies and start the development server for hot-reloading. Use 'build' for production builds and 'typecheck'/'lint' for code quality checks.

```bash
# Install dependencies
npm install

# Start dev server (fetches data automatically, hot-reload)
npm run start

# Full production build
npm run build

# Type check
npm run typecheck

# Lint
npm run lint
```

--------------------------------

### Install Dependencies and Start Development Server

Source: https://github.com/projectbluefin/documentation/blob/main/README.md

Install project dependencies using npm with legacy peer dependencies and start the development server. The `--legacy-peer-deps` flag is crucial for resolving peer dependency conflicts.

```bash
npm install --legacy-peer-deps
npm run start
```

--------------------------------

### Develop Bluefin Documentation Site Locally

Source: https://context7.com/projectbluefin/documentation/llms.txt

Clone the documentation repository, install Node.js dependencies, and start the development server using 'npm' or 'just' commands. Includes commands for fast development, production build, testing, and formatting.

```bash
# Clone the documentation repository
git clone https://github.com/projectbluefin/documentation.git
cd documentation
```

```bash
# Install dependencies (requires Node.js 20+)
npm install --legacy-peer-deps
```

```bash
# Start development server (fetches data and serves)
npm run start
# Or use just:
just serve
```

```bash
# Fast development mode (skips data fetch, uses cached data)
just dev
```

```bash
# Build for production
npm run build
# Or:
just build
```

```bash
# Run end-to-end tests
npm run test:e2e
# Or:
just test
```

```bash
# Format code with Prettier
npm run prettier
```

```bash
# Alternative: Run via Docker
docker compose up
```

--------------------------------

### Install Alternate Shells

Source: https://github.com/projectbluefin/documentation/blob/main/docs/command-line.md

Before changing your default shell, install the desired shell using Homebrew. This example shows installing zsh and fish.

```bash
brew install zsh
brew install fish
```

--------------------------------

### Install and Start Linux MCP Server for AI Troubleshooting

Source: https://context7.com/projectbluefin/documentation/llms.txt

Install the Linux MCP server using Homebrew and start a Goose session for AI-powered system diagnostics. Configuration details for Goose are provided.

```bash
# Install the Linux MCP server
brew install ublue-os/tap/linux-mcp-server
```

```bash
# Start a Goose session
goose session start
```

--------------------------------

### Install Neovim and Devcontainer

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

Installs Neovim and the devcontainer tool using Homebrew. Follow the provided link for devcontainer setup instructions.

```bash
brew install neovim devcontainer
```

--------------------------------

### Add Just Recipe

Source: https://github.com/projectbluefin/documentation/blob/main/docs/contributing.md

Create or edit a '.just' file in the 'just/' directory to add custom recipes. This example shows how to install a custom tool using 'toolbox run'.

```make
# Install custom development tool
install-custom-tool:
    #!/usr/bin/env bash
    set -euxo pipefail
    echo "Installing custom tool..."
    toolbox run sudo dnf install -y custom-tool
```

--------------------------------

### Install and Run Bold Brew

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-07-15-bold-brew.md

Use this command to install Bold Brew via Homebrew and then launch the tool. Ensure Homebrew is installed on your system.

```bash
brew install Valkyrie00/homebrew-bbrew/bbrew
bbrew
```

--------------------------------

### Install Dev Container CLI with npm

Source: https://github.com/projectbluefin/documentation/blob/main/docs/devcontainers.md

Install the Dev Container CLI globally using npm. Ensure Node.js and npm are installed on your system.

```bash
npm install -g @devcontainers/cli
```

--------------------------------

### Install Kubernetes Tools with `ujust`

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-10-28-bluefin-autumn.md

Execute this command to install essential Kubernetes tools. A comprehensive list of tools is available in the Kubernetes documentation.

```bash
ujust bluefin-k8s
```

--------------------------------

### Example of Verified Download

Source: https://github.com/projectbluefin/documentation/blob/main/docs/downloads-testing.md

This example demonstrates the expected output when both the generated checksum and the official checksum match, indicating a successful and verified download.

```bash
# Generate checksum of downloaded file
$ sha256sum bluefin-stable-x86_64.iso
a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456  bluefin-stable-x86_64.iso

# Check official checksum
$ cat bluefin-stable-x86_64.iso-CHECKSUM
a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456  bluefin-stable-x86_64.iso

# 🦖 Rawr! Your download is verified
```

--------------------------------

### Simple Git Commit

Source: https://github.com/projectbluefin/documentation/blob/main/docs/contributing.md

Use the 'fix' type for bug fixes. This example removes unused setup functions.

```bash
git commit -m "fix: remove cockpit and brew setup functions"
```

--------------------------------

### Install Virt-Manager and QEMU Extension

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

Installs the virt-manager application and its QEMU extension using Flatpak. This is necessary for virtualization on Bluefin LTS.

```bash
flatpak install flathub org.virt_manager.virt_manager org.virt_manager.virt_manager.Extension.Qemu 
```

--------------------------------

### Install Fcitx5 via Flatpak

Source: https://github.com/projectbluefin/documentation/blob/main/docs/FAQ.md

Use this command to install the Fcitx5 Input Method Editor framework. This is a prerequisite for using various input methods.

```bash
flatpak install org.fcitx.Fcitx5
```

--------------------------------

### Install JetBrains Toolbox

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

Fetches and installs the JetBrains Toolbox application for managing JetBrains products. This application is installed in your home directory.

```bash
ujust jetbrains-toolbox
```

--------------------------------

### Run Documentation in Docker

Source: https://github.com/projectbluefin/documentation/blob/main/README.md

Start the documentation development environment using Docker Compose.

```bash
docker compose up
```

--------------------------------

### k3sup K3s Installation

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

A light-weight utility to install k3s on any local or remote VM.

```bash
k3sup
```

--------------------------------

### Basic devcontainer.json Example

Source: https://github.com/projectbluefin/documentation/blob/main/docs/devcontainers.md

A fundamental devcontainer.json configuration for a Node.js environment. It specifies the base image, includes Git features, lists VS Code extensions to install, defines ports to forward, and sets a post-creation command to install npm packages.

```json
{
  "name": "Node.js",
  "image": "mcr.microsoft.com/devcontainers/javascript-node:20",
  "features": {
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "extensions": ["ms-vscode.vscode-typescript-next"],
  "forwardPorts": [3000],
  "postCreateCommand": "npm install"
}
```

--------------------------------

### Install All AI Tools

Source: https://github.com/projectbluefin/documentation/blob/main/docs/ai.md

Use this command to install all available AI-focused command-line tools via homebrew.

```bash
ujust bbrew
```

--------------------------------

### Install Bluefin CLI Tools with `ujust`

Source: https://github.com/projectbluefin/documentation/blob/main/docs/administration.md

Use this command to install a comprehensive set of modern CLI tools, including atuin, bat, chezmoi, direnv, eza, fd, gh, glab, ripgrep, starship, tealdeer, television, zoxide, and more. This command installs tools via Homebrew.

```bash
ujust bluefin-cli
```

--------------------------------

### Install AI & Machine Learning Tools with `ujust`

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-10-28-bluefin-autumn.md

Run this command to install a suite of AI and Machine Learning tools. Refer to the AI and Machine Learning documentation for more details.

```bash
ujust bluefin-ai
```

--------------------------------

### Install Chinese Add-ons for Fcitx5

Source: https://github.com/projectbluefin/documentation/blob/main/docs/FAQ.md

Install the necessary add-ons for Fcitx5 to support Chinese input methods. This command installs the Chinese addons for Fcitx5.

```bash
flatpak install org.fcitx.Fcitx5.Addon.ChineseAddons
```

--------------------------------

### Build Bluefin Images Locally with Just

Source: https://context7.com/projectbluefin/documentation/llms.txt

Build custom Bluefin container images and installation ISOs using the Just task runner. Clone the repository, then use `just build` for images or `just build-iso` for installation media, specifying variants like DX or Nvidia.

```bash
# Clone the Bluefin repository
git clone https://github.com/ublue-os/bluefin.git
cd bluefin

# Build default Bluefin image (latest tag)
just build bluefin

# Build stable Bluefin DX image
just build bluefin-dx stable

# Build Nvidia variant
just build bluefin stable nvidia

# Build beta Nvidia DX variant
just build bluefin-dx beta nvidia

# Run a container shell from the built image
just run bluefin stable

# Build an ISO for installation
just build-iso bluefin stable

# Run the ISO in a virtual machine
just run-iso bluefin stable

# Build ISO from GHCR (pre-built image)
just build-iso-ghcr bluefin stable

# Clean build artifacts
just clean
```

--------------------------------

### Install Bluefin CLI with Homebrew

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2026-03-13-bluefin-cli-mac-wsl.mdx

Install the Bluefin CLI on macOS using Homebrew. Ensure Homebrew is installed before running this command.

```bash
brew install ublue-os/experimental-tap/bluefin-cli
```

--------------------------------

### Install Bluefin Wallpapers Extra

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-12-14-huntress-holiday-wallpapers.md

Use this command to install the Huntress wallpaper and other extra Bluefin wallpapers through the ublue-os/homebrew tap.

```bash
brew install ublue-os/tap/bluefin-wallpapers-extra
```

--------------------------------

### Install JetBrains Toolbox and Configure Podman

Source: https://context7.com/projectbluefin/documentation/llms.txt

Install the JetBrains Toolbox application using 'ujust' and configure Podman integration within JetBrains IDEs by pointing to the Podman socket. Uninstall instructions are linked.

```bash
# Install JetBrains Toolbox
ujust jetbrains-toolbox
```

```bash
# Configure Podman integration in JetBrains IDE:
# Settings > Build, Execution, Deployment > Docker
# - Connect to Docker daemon with: unix:///run/user/1000/podman/podman.sock
# Or configure via IDE's built-in container support
```

```bash
# Uninstall Toolbox:
# See https://toolbox-support.jetbrains.com/hc/en-us/articles/115001313270
```

--------------------------------

### Install System Flatpaks

Source: https://github.com/projectbluefin/documentation/blob/main/docs/administration.md

Installs the default system Flatpak applications. This is particularly useful after rebasing your system.

```bash
ujust install-system-flatpaks
```

--------------------------------

### Install linux-mcp-server on Linux

Source: https://github.com/projectbluefin/documentation/blob/main/docs/troubleshooting.mdx

Use this command to install the linux-mcp-server on Linux systems via Homebrew.

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

--------------------------------

### Example Prompts for AI Troubleshooting

Source: https://context7.com/projectbluefin/documentation/llms.txt

Provides example natural language prompts to use with the Goose AI client for system diagnostics and troubleshooting.

```bash
# Example prompts for AI troubleshooting:
# "What OS version is this?"
# "Is the CPU overloaded?"
# "Show errors from the last hour"
# "What ports are open?"
# "Find the largest folders in /var"
# "Check CPU usage and show me the top 5 processes"
```

--------------------------------

### Install Flatpak Packages with Brew Bundle

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-12-04-flatpak-support-in-brewfiles.md

After adding Flatpak applications to your Brewfile, run 'brew bundle' to install them. This command handles both Homebrew formulae and Flatpak packages.

```bash
brew bundle
```

--------------------------------

### Install CNCF Tools

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

Installs a comprehensive collection of Cloud Native Computing Foundation (CNCF) tools using the 'ujust cncf' command. This includes a wide range of graduated, incubating, and sandbox projects.

```bash
ujust cncf
```

--------------------------------

### Flatpak Application Management in Bluefin

Source: https://context7.com/projectbluefin/documentation/llms.txt

Install graphical applications using Flatpak from Flathub. Use `flatpak` commands for installation, searching, listing, and updating applications. Flatseal is available for managing permissions.

```bash
# Install an application from Flathub
flatpak install flathub org.mozilla.firefox
```

```bash
# Search for applications
flatpak search gimp
```

```bash
# List installed applications
flatpak list --app
```

```bash
# Update all Flatpak applications
flatpak update
```

```bash
# Install Fcitx5 input method editor for CJK languages
flatpak install org.fcitx.Fcitx5
flatpak install org.fcitx.Fcitx5.Addon.ChineseAddons
```

```bash
# Manage Flatpak permissions with Flatseal (pre-installed)
```

--------------------------------

### Install and Configure Alternative Shells in Ptyxis

Source: https://context7.com/projectbluefin/documentation/llms.txt

Install zsh and fish via Homebrew and configure them as custom commands in Ptyxis Terminal preferences. Enable bluefin-cli for these shells using the SHELL environment variable.

```bash
# Install alternative shells via Homebrew
brew install zsh fish
```

```bash
# Enable bluefin-cli for alternative shells
ujust bluefin-cli              # For bash (default)
SHELL=fish ujust bluefin-cli   # For fish
SHELL=zsh ujust bluefin-cli    # For zsh
```

```bash
# Or enable all at once
ujust bluefin-cli && SHELL=fish ujust bluefin-cli && SHELL=zsh ujust bluefin-cli
```

```bash
# Toggle message of the day in terminal
ujust toggle-user-motd
```

--------------------------------

### Verify Container Runtime

Source: https://github.com/projectbluefin/documentation/blob/main/docs/devcontainers.md

Check if Podman or Docker is installed and running on your system. Podman is the default on Bluefin.

```bash
# For Podman (default on Bluefin)
podman --version
```

```bash
# For Docker
docker --version
```

--------------------------------

### Serve Documentation Locally

Source: https://github.com/projectbluefin/documentation/blob/main/README.md

Use the 'just serve' command to build and serve the documentation locally for previewing changes.

```bash
just serve
```

--------------------------------

### Build Documentation

Source: https://github.com/projectbluefin/documentation/blob/main/README.md

Use the 'just build' command to generate the documentation.

```bash
just build
```

--------------------------------

### Build Bluefin ISO

Source: https://github.com/projectbluefin/documentation/blob/main/docs/local.md

Create a bootable ISO image of Bluefin using the 'just' build system.

```bash
just build-iso bluefin stable
```

--------------------------------

### Git Commit for Feature Addition

Source: https://github.com/projectbluefin/documentation/blob/main/docs/contributing.md

Use the 'feat' type for new features. This example adds a Flatpak to the default installation.

```bash
git commit -m "feat: add bazaar flatpak to default installation"
```

--------------------------------

### Run Bluefin ISO

Source: https://github.com/projectbluefin/documentation/blob/main/docs/local.md

Launch a virtual machine to run a previously built Bluefin ISO image.

```bash
just run-iso bluefin stable
```

--------------------------------

### Run ISO in Virtual Environment

Source: https://github.com/projectbluefin/documentation/blob/main/docs/local.md

Launch a virtual machine to run a Bluefin ISO image. This task finds an available port and starts the VM using Podman.

```bash
just run-iso <image> <tag> <flavor>
```

--------------------------------

### Enable Developer Mode in Bluefin

Source: https://github.com/projectbluefin/documentation/blob/main/docs/installation.md

Enables developer mode on Bluefin. Follow the on-screen prompts to complete the setup. This may install additional tools and configurations for development.

```bash
ujust devmode
```

--------------------------------

### Install T2-Specific Packages

Source: https://github.com/projectbluefin/documentation/blob/main/docs/t2-mac.md

Installs the necessary T2-specific packages for fan control, touchbar management, and audio support. A reboot is required after installation.

```bash
sudo dnf install t2fanrd rust-tiny-dfr t2linux-audio
```

--------------------------------

### Install Dev Container CLI with Homebrew

Source: https://github.com/projectbluefin/documentation/blob/main/docs/devcontainers.md

Install the Dev Container CLI on macOS or Linux using Homebrew. This command installs the CLI globally for command-line access.

```bash
brew install devcontainer
```

--------------------------------

### Install DSP Audio Dependencies

Source: https://github.com/projectbluefin/documentation/blob/main/docs/t2-mac.md

Install necessary dependencies for the tuned software DSP audio enhancement on T2 Linux. This command is for manual installations; T2-Atomic images typically have these pre-installed.

```bash
sudo dnf install calf libspatialaudio lsp-plugins-lv2 lv2-calf-plugins ladspa-swh-plugins pipewire-module-filter-chain-lv2
```

--------------------------------

### Build Bluefin LTS Locally

Source: https://github.com/projectbluefin/documentation/blob/main/docs/lts.mdx

Clone the Bluefin LTS repository and use `just` commands to build the system or a qcow2 image. The default username and password for the qcow2 image are 'centos'/'centos'.

```bash
git clone https://github.com/ublue-os/bluefin-lts
cd bluefin-lts
just build
just build-qcow2 ghcr.io/ublue-os/bluefin:lts
```

--------------------------------

### Install Extra System Flatpaks

Source: https://github.com/projectbluefin/documentation/blob/main/docs/administration.md

Installs additional recommended Flatpak applications beyond the default system set.

```bash
ujust install-system-flatpaks-extra
```

--------------------------------

### Install Developer Fonts with `ujust`

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-10-28-bluefin-autumn.md

Use this command to install developer-focused monospace fonts. Ensure you are in developer mode.

```bash
ujust bluefin-fonts
```

--------------------------------

### Build Bluefin Images with Just

Source: https://github.com/projectbluefin/documentation/blob/main/docs/local.md

Use the 'just' command to build various Bluefin images. Specify the image name, tag, and flavor as needed.

```bash
just build bluefin
```

```bash
just build bluefin-dx stable
```

```bash
just build bluefin-dx beta nvidia
```

```bash
just build bluefin stable nvidia
```

--------------------------------

### Dagger CLI

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

A portable devkit for CI/CD pipelines.

```bash
dagger
```

--------------------------------

### Install Aurora Artwork Wallpapers

Source: https://github.com/projectbluefin/documentation/blob/main/blog/2025-12-14-huntress-holiday-wallpapers.md

Use this command to install the Aurora artwork wallpapers, including 'Holiday Blues', through the ublue-os/homebrew tap.

```bash
brew install ublue-os/tap/aurora-wallpapers
```

--------------------------------

### Run System Upgrade

Source: https://github.com/projectbluefin/documentation/blob/main/docs/installation.md

Manually initiate a system update and reboot. Use `ujust changelogs` to view incoming changes.

```bash
ujust update
```

```bash
ujust changelogs
```

```bash
ujust bios
```

--------------------------------

### Developer Mode Setup for Bluefin

Source: https://context7.com/projectbluefin/documentation/llms.txt

Enable developer experience (bluefin-dx) for tools like Docker, Podman, and virtualization. This requires a reboot and adding your user to specific groups.

```bash
# Enable developer mode (requires reboot)
ujust devmode
```

```bash
# Add your user to required groups (docker, incus-admin, libvirt, dialout)
ujust dx-group
```

```bash
# Verify container runtimes are available
docker --version
podman --version
```

```bash
# Check Docker service status
systemctl --user status docker
```

```bash
# Check Podman socket for rootless containers
systemctl --user status podman.socket
```

--------------------------------

### Run Container from Built Image

Source: https://github.com/projectbluefin/documentation/blob/main/docs/local.md

Start a container from a Bluefin image. This task ensures the image is built if it doesn't exist locally and then runs it interactively.

```bash
just run <image> <tag> <flavor>
```

--------------------------------

### Install Homebrew Package Manager

Source: https://github.com/projectbluefin/documentation/blob/main/docs/installation.md

Installs the Homebrew package manager, commonly used for command-line tools on macOS and Linux. Ensure you have the necessary permissions.

```bash
brew install chezmoi
```

--------------------------------

### k0sctl Cluster Management

Source: https://github.com/projectbluefin/documentation/blob/main/docs/bluefin-dx.md

A command-line tool for bootstrapping and managing k0s Kubernetes clusters.

```bash
k0sctl
```