Playbooks Reference

Complete catalog of available features and how to use them.

Quick Navigation

Just installed? Start with Optional Playbooks to see what you can add.

Creating your own? See Creating Custom Playbooks for templates.

Common tasks:

Install Docker - Rootless Docker setup
Set up Distrobox - Seamless dev environments
Python development - pyenv and PDM

Core Playbooks (Automatically Run)

These playbooks are executed automatically by playbook-main.yml during initial installation:

play-AA-preflight-sanity.yml

Purpose: Validates system requirements
Actions:

Verifies Ansible version >= 2.9.9
Confirms Fedora distribution and version
Ensures system matches target in vars/fedora-version.yml

play-basic-configs.yml

Purpose: Essential system configuration
Actions:

Installs basic packages (vim, wget, bash-completion, htop, etc.)
Configures passwordless sudo for user
Sets up Vim with Deus colorscheme
Configures bash environment and custom PS1 prompt
Copies SSH keys to root user
Installs YQ binary
Optimizes DNF with parallel downloads
Configures hardware settings

play-nvm-install.yml

Purpose: Node.js environment setup
Actions:

Installs Node Version Manager (NVM)
Installs Node.js version 20
Sets up bash integration

play-claude-code.yml

Purpose: Claude Code CLI installation
Actions:

Downloads and installs Claude Code binary
Configures system-wide access

play-git-configure-and-tools.yml

Purpose: Git environment configuration
Actions:

Configures git user name and email
Installs bash-git-prompt with Solarized theme
Sets up ripgrep for fast searching
Installs GitHub CLI (gh)
Note: SSH keys are generated by run.bash as ~/.ssh/id (Ed25519)
Configures SSH for LXC containers

play-lxc-install-config.yml

Purpose: Container support
Actions:

Installs LXC and LXD packages
Configures container networking
Sets up SSH configuration for containers
Configures firewall rules

play-ms-fonts.yml

Purpose: Microsoft fonts installation
Actions:

Installs Windows-compatible fonts
Configures font rendering

play-rpm-fusion.yml

Purpose: Third-party repository setup
Actions:

Enables RPM Fusion free and non-free repositories
Required for many multimedia codecs and proprietary software

play-toolbox-install.yml

Purpose: JetBrains Toolbox installation
Actions:

Downloads and installs JetBrains Toolbox
Configures desktop integration

Optional Playbooks

Run these manually as needed after the main installation completes.

General syntax:

cd ~/Projects/fedora-desktop
ansible-playbook playbooks/imports/optional/<category>/<playbook>.yml

Note: Most optional playbooks don't require --ask-become-pass as they use sudo internally. If prompted for a password, just enter your sudo password.

Common Optional Features

Popular add-ons for development work:

play-comms.yml

Installs communication applications:

Enables Flathub repository
Installs Slack

play-docker.yml

Docker container platform:

Adds Docker repository
Installs Docker CE and tools
Configures rootless Docker (user systemd service)
Configures subuid/subgid for user namespaces
See Containerization Guide for details

play-distrobox.yml

Distrobox installation:

Installs distrobox package
Provides seamless container integration for development
Enables running GUI apps from other distros
Auto-shares home directory with containers
See Containerization Guide for comparison with LXC/Docker

play-claude-yolo.yml

Claude Code containerised environment (Docker/Podman-based):

CCY (YOLO Mode): General-purpose development container with browser automation built in
Unified token management
Custom Dockerfile support per project
Proper isolation with container home directories
See Containerisation Guide for full details

What's installed:

git, gh, ripgrep, jq, yq, vim, python, Node.js 20, Claude Code
agent-browser CLI: Token-efficient browser automation via Chromium (no Playwright needed)

Key features of agent-browser:

93% context reduction for multi-page flows vs traditional DOM inspection
Headed mode support (--headed flag) for visual debugging
Reference-based selection (@e1, @e2) from compact accessibility snapshots

Usage:

# Create a token
ccy --create-token

# General development (browser automation included)
cd ~/Projects/my-project
ccy

# Inside CCY — browser automation ready to use
agent-browser --help              # Comprehensive built-in docs
agent-browser --headed open https://example.com
agent-browser snapshot -i         # Get @refs for elements
agent-browser click @e5           # Click using reference
agent-browser fill @e3 "test"     # Fill form fields

Token efficiency example:

# Traditional DOM inspection: 100,000+ tokens for 5-page flow
# agent-browser: ~8,000 tokens for same flow (93% reduction!)

Custom Dockerfiles:

# AI-guided customisation (comprehensive planning)
ccy --custom-docker

# Quick template-based customisation
ccy --custom

play-firefox.yml

Firefox with enterprise policies:

Firefox browser from DNF
Firefox Profile Switcher Connector for multi-profile management
Enterprise policies via /etc/firefox/policies/policies.json

What policies control:

Default homepage and search engine
Extension installation sources
Privacy and security settings
Update behaviour
Developer tools access

Customizing policies: Edit files/etc/firefox/policies/policies.json in repository, re-run playbook

play-github-cli-multi.yml

Multi-account GitHub CLI management:

Multiple GitHub accounts (work, personal, open-source, etc.)
SSH keys per account with account-specific configuration
Bash helper functions for seamless account switching
Account-specific operations (clone, remote setup, gh commands)

Setup process:

Run playbook (prompts for accounts in format: alias:username)
SSH keys generated automatically per account
Authenticate with gh auth login for each account
Bash functions available immediately

Available functions:

gh-list                    # List all configured accounts
gh-whoami                  # Show current active account
gh-status                  # Check authentication status
gh-switch work             # Switch to work account
github-test-ssh            # Test SSH for all accounts

# Account-specific commands (example with 'work')
gh-work pr list            # Run gh CLI as work account
clone-work owner/repo      # Clone with work account SSH
remote-work owner/repo     # Set git remote for work account
gh-token-work              # Get GitHub token
gh-work-make-default       # Set as default account

Configuration files:

Account definitions: environment/localhost/host_vars/localhost.yml
SSH keys: ~/.ssh/github_<alias> (per account)
SSH config: ~/.ssh/config (separate host blocks)
Bash functions: ~/.bashrc-includes/gh-aliases.inc.bash

Adding new accounts: Edit github_accounts in host_vars, re-run playbook

Example workflow:

# Work on company project
gh-switch work
clone-work company/private-repo
cd private-repo
gh-work pr create

# Switch to personal project
gh-switch personal
clone-personal myusername/hobby-project
cd hobby-project
gh-personal issue list

play-gnome-shell.yml & play-gnome-shell-extensions.yml

GNOME desktop customization and extensions:

System extensions:

dash-to-dock: Application dock with customization

Third-party extensions (via gnome-shell-extension-installer):

Blur my Shell (3193): Blur effects for panels and overview
Vitals (1460): System monitoring (CPU, memory, temperature)
AppIndicator Support (615): System tray icons
Clipboard Indicator (779): Clipboard history manager
Just Perfection (3843): Customize GNOME Shell behaviour
Tiling Shell (7065): Window tiling and snapping
Space Bar (5090): Workspace navigation enhancements

Custom extensions:

workspace-names-overview: Show workspace names in overview

What you get:

Enhanced window management (tiling)
System monitoring in top bar
Clipboard history access
Visual enhancements (blur effects)
Better workspace navigation

play-golang.yml

Go programming language:

Golang compiler and standard tools from DNF repositories
Latest stable version for Fedora 42

What you get:

go version
go build
go test
go mod init

play-rust-dev.yml

Rust development environment:

Rustup toolchain manager for Rust version management
Stable toolchain with automatic updates
Essential components: rustfmt, clippy, rust-analyzer, rust-src, llvm-tools-preview
cargo-binstall for faster binary installations
20+ Cargo tools for development workflow

Cargo tools installed:

cargo-watch - Auto-rebuild on file changes
cargo-edit - Add/remove/upgrade dependencies from CLI
cargo-audit - Security vulnerability scanning
cargo-outdated - Check for outdated dependencies
cargo-expand - Expand macros (debugging)
cargo-machete - Find unused dependencies
cargo-nextest - Next-generation test runner
cargo-deny - Dependency linting
cargo-tarpaulin - Code coverage

What you get:

# Rust toolchain
rustc --version
cargo --version
rustfmt --version
cargo clippy --version

# Development workflow
cargo new my-project
cd my-project
cargo watch -x run          # Auto-rebuild
cargo clippy                # Linting
cargo audit                 # Security check
cargo nextest run           # Fast testing

Cargo configuration optimizations:

Parallel jobs optimized for your CPU
Git fetch with shallow clones
Sparse registry for faster updates

System dependencies included: GCC, CMake, OpenSSL, SQLite, PostgreSQL, MySQL development libraries for common crate compilation

play-gsettings.yml

Desktop settings configuration:

Applies custom GNOME settings via gsettings

play-hd-audio.yml

High-fidelity audio system:

HD sample rate support: 44.1kHz, 48kHz, 88.2kHz, 96kHz, 176.4kHz, 192kHz
Dynamic rate switching: Automatic based on active audio streams
PipeWire optimization: Quantum tuning (32-8192) for low latency
Bluetooth codecs: LDAC (HQ), aptX, aptX-HD, AAC, SBC-XQ
USB audio: Special handling with larger buffers for DACs
High-quality resampling: Quality level 10

What you get:

Studio-quality audio playback up to 192kHz/24-bit
LDAC codec for wireless headphones (990kbps)
Optimized latency for music production
Better Bluetooth headphone compatibility (controller mode: bredr)

For audiophiles:

Works with external DACs
Supports high-resolution audio files (FLAC, DSD)
Professional music production capabilities
Low-latency monitoring

play-python.yml

Python development environment:

pyenv for Python version management
Python versions: 3.11.13 (LTS), 3.12.11 (stable), 3.13.1 (latest)
PDM (Python Dependency Manager) for modern dependency management
pipx for isolated CLI tool installations
Hugging Face Hub CLI for ML model management
Development dependencies: SDK headers, compression libs, cryptography support

What you get:

# Switch Python versions
pyenv versions
pyenv global 3.12.11

# PDM workflow
pdm init
pdm add requests
pdm install

# Isolated tools
pipx install black
pipx install ruff

Installed Python versions:

3.11.13 - Long-term support (recommended for production)
3.12.11 - Current stable (best balance)
3.13.1 - Latest features (experimental)

Package managers:

pip - Standard (pre-installed with Python)
PDM - Modern, fast, PEP-compliant (recommended for new projects)
pipx - For installing CLI tools in isolation

play-vscode.yml

Visual Studio Code installation:

Adds Microsoft's official Fedora repository
Installs VS Code with GPG key verification
Latest stable version

Recommended extensions (install via VS Code):

Python: ms-python.python
Rust: rust-lang.rust-analyzer
Go: golang.go
GitLens: eamodio.gitlens
Claude Code: Anthropic's official extension

play-vpn.yml

VPN client setup:

WireGuard tools and NetworkManager integration
OpenVPN firewall rules
Network profile importing

Usage:

# Import WireGuard config
nmcli connection import type wireguard file vpn-config.conf

# Connect
nmcli connection up vpn-name

# Disconnect
nmcli connection down vpn-name

play-cloudflare-warp.yml

Cloudflare WARP zero-trust VPN:

Cloudflare WARP client from official repository
DNS over HTTPS with malware filtering
systemd-resolved integration
Automatic registration and connection

Features:

Zero-trust network access
1.1.1.1 DNS with privacy
Malware and tracking protection
Faster internet (optimized routing)

play-lastpass.yml

LastPass CLI password manager:

LastPass command-line interface
Single or multi-account support
Account-specific aliases (lpass-work, lpass-personal)

Setup (prompted during playbook):

Single account: Simple setup
Multiple accounts: Define aliases (e.g., work,personal)

Usage:

# Single account
lpass login user@example.com
lpass show github
lpass logout

# Multi-account
lpass-work login work@company.com
lpass-personal login me@gmail.com
lpass-status  # Check all accounts

play-qobuz-cli.yml

Qobuz high-fidelity music streaming:

hifi-rs: Rust-based Qobuz player
qobuz-player: Enhanced fork with web interface (default)
rescrobbled: Last.fm scrobbling systemd service
Configurable default player via environment variable

Shell functions:

play [album/track]    # Play with default player
hplay [album/track]   # Force hifi-rs player
qplay [album/track]   # Force qobuz-player
qobuz_switch          # Switch default player
qobuz_web             # Open web interface
qobuz_status          # Show current player

Features:

High-resolution audio streaming (up to 24-bit/192kHz)
Web interface for qobuz-player (http://localhost:port)
Last.fm scrobbling integration
Playlist support with shuffle

play-terminal-emulators.yml

Modern high-performance terminal emulators optimized for Claude Code:

Alacritty: GPU-accelerated, lowest input latency, OpenGL rendering
Kitty: Feature-rich with native tabs, image protocol, ligature support
Ghostty: New GTK4 terminal (v1.0 Dec 2025), zero config, hundreds of themes
Foot: Wayland-native minimalist, 21MB memory, CPU rendering, server/client mode

Comparison:

Terminal	GPU	Latency	Features	Memory	Best For
Alacritty	✅	Lowest	Minimal	~50MB	Speed, responsiveness
Kitty	✅	Low	Rich	~80MB	Power users, features
Ghostty	❌	Low	Balanced	~40MB	GTK integration, themes
Foot	❌	Medium	Minimal	~20MB	Wayland, efficiency

All terminals support:

True colour (24-bit)
Fast rendering
Excellent Claude Code performance
Customizable via config files

Usage:

# Launch your preferred terminal
alacritty
kitty
ghostty
footclient  # or 'foot' for standalone

play-speech-to-text.yml

GPU-accelerated speech-to-text with AI enhancement:

faster-whisper with NVIDIA CUDA GPU acceleration
RealtimeSTT for real-time streaming transcription
Model sizes: tiny, base, small, medium, large-v3
Claude Code integration: Professional text formatting (corporate/natural modes)
GNOME Shell extension with keyboard shortcuts
Auto-paste: Text types automatically at cursor

Keyboard shortcuts:

Insert: Record and transcribe (raw)
Ctrl+Insert: Record with corporate AI processing 🤖
Alt+Insert: Record with natural AI processing 💬

Requirements: NVIDIA GPU with drivers installed (play-nvidia.yml)

See comprehensive guide: Speech-to-Text Documentation

Hardware-Specific

play-nvidia.yml

NVIDIA GPU drivers:

Installs proprietary NVIDIA drivers
Configures kernel modules

play-displaylink.yml

DisplayLink dock support:

Installs DisplayLink drivers
Creates suspend/resume service
Configures display management

Experimental

play-docker-in-lxc-support.yml

Docker-in-LXC support:

Configures host for Docker inside LXC containers
Loads kernel modules (overlay, br_netfilter)
Configures sysctl for IP forwarding
Enables user namespaces for rootless Docker
Installs docker-in-lxc command for project-based containers
Requires: play-lxc-install-config.yml (core)
See Containerization Guide for advanced use cases

Usage:

cd ~/Projects/my-docker-project
docker-in-lxc --create  # Create LXC for this project
docker-in-lxc --enter   # Enter the container
# Inside: docker-compose up

play-lxde-install.yml

Lightweight desktop environment:

Installs LXDE as alternative to GNOME

play-virtualbox-windows.yml

Windows virtualization:

Installs VirtualBox
Configures Windows VM support
Sets up ACPI tools

Archived

play-tlp-battery-optimisation.yml

Laptop power management (deprecated):

TLP battery optimization
Note: Conflicts with newer power-profiles-daemon

Running Optional Playbooks

# Install communication applications
ansible-playbook playbooks/imports/play-comms.yml

# Set up Docker
ansible-playbook playbooks/imports/optional/common/play-docker.yml

# Install Distrobox
ansible-playbook playbooks/imports/optional/common/play-distrobox.yml

# Install NVIDIA drivers
ansible-playbook playbooks/imports/optional/hardware-specific/play-nvidia.yml

# Configure multiple GitHub accounts
ansible-playbook playbooks/imports/optional/common/play-github-cli-multi.yml

# Advanced: Docker-in-LXC support
ansible-playbook playbooks/imports/optional/experimental/play-docker-in-lxc-support.yml

Creating Custom Playbooks

Place custom playbooks in playbooks/imports/optional/ following the naming convention play-<feature>.yml.

Template:

- hosts: desktop
  name: Your Feature Name
  become: true  # If root required
  vars:
    root_dir: "{{ inventory_dir }}/../../"
  vars_files:
    - "{{ root_dir }}/vars/fedora-version.yml"  # If version-specific
  tasks:
    - name: Your task here
      package:
        name: your-package
        state: present

FilesExpand file tree

playbooks.md

Latest commit

History

playbooks.md

File metadata and controls

Playbooks Reference

Quick Navigation

Core Playbooks (Automatically Run)

play-AA-preflight-sanity.yml

play-basic-configs.yml

play-nvm-install.yml

play-claude-code.yml

play-git-configure-and-tools.yml

play-lxc-install-config.yml

play-ms-fonts.yml

play-rpm-fusion.yml

play-toolbox-install.yml

Optional Playbooks

Common Optional Features

play-comms.yml

play-docker.yml

play-distrobox.yml

play-claude-yolo.yml

play-firefox.yml

play-github-cli-multi.yml

play-gnome-shell.yml & play-gnome-shell-extensions.yml

play-golang.yml

play-rust-dev.yml

play-gsettings.yml

play-hd-audio.yml

play-python.yml

play-vscode.yml

play-vpn.yml

play-cloudflare-warp.yml

play-lastpass.yml

play-qobuz-cli.yml

play-terminal-emulators.yml

play-speech-to-text.yml

Hardware-Specific

play-nvidia.yml

play-displaylink.yml

Experimental

play-docker-in-lxc-support.yml

play-lxde-install.yml

play-virtualbox-windows.yml

Archived

play-tlp-battery-optimisation.yml

Running Optional Playbooks

Creating Custom Playbooks