Feature Flags

Feature flags are the primary way to configure Marchyo. Each flag enables a group of related packages, services, and configurations.

Available flags

Option	Default	Description
marchyo.desktop.enable	false	Desktop environment (Hyprland, Wayland, audio, bluetooth, fonts)
marchyo.development.enable	false	Development tools (git, Docker, buildah, gh, virtualization)
marchyo.media.enable	false	Media applications (Spotify, MPV, etc.)
marchyo.office.enable	false	Office applications (Papers document viewer, Obsidian, Xournal++)
marchyo.gaming.enable	false	Gaming bundle (Steam, GameMode, Gamescope, MangoHUD, Lutris, Heroic) — desktop-only, opt-in

Cascading defaults

When you enable marchyo.desktop.enable, related flags are automatically enabled at a lower priority using lib.mkDefault:

# Enabling desktop...
marchyo.desktop.enable = true;

# ...automatically enables these (you can override them):
# marchyo.office.enable = true;
# marchyo.media.enable = true;
# marchyo.webapps.enable = true;
# marchyo.shell.enable = true;

Since these use lib.mkDefault, you can override them:

{
  marchyo.desktop.enable = true;
  marchyo.media.enable = false;   # Disable media despite desktop being on
}

Desktop environment

When marchyo.desktop.enable = true, Marchyo configures:

• Hyprland — Wayland compositor with pre-configured keybindings and window rules. Press SUPER+K for a searchable, on-screen cheat sheet of all active keybindings (toggle with marchyo.keybindingsHelp.enable)
• Audio — PipeWire with PulseAudio and ALSA compatibility
• Bluetooth — Enabled and configured
• Fonts — Curated set of fonts including Nerd Fonts
• Theming — Jylhis design-system theming across GTK, Qt, terminals, TUIs, and Emacs, with runtime theme switching
• Desktop shell: the unified Quickshell shell (bar, launcher, OSD, panels, notifications, lock, and polkit agent; see Desktop Shell). marchyo.shell.enable = false keeps the discrete stack: waybar, Vicinae, SwayOSD, mako, hyprlock, and hyprpolkitagent
• Terminal emulator — Ghostty
• Default applications — Configurable via marchyo.defaults.*

Development tools

When marchyo.development.enable = true, Marchyo configures:

• Git with Git LFS and GitHub CLI (gh)
• Containers — rootless Podman (with podman-tui) or Docker, plus Buildah and Skopeo
• Virtualization via QEMU/KVM (libvirtd), with virt-manager and virt-viewer
• Build tools — GNU Make, CMake, GCC, pkg-config
• Utilities — direnv (with nix-direnv), jq, yq, network debugging tools (nmap, tcpdump, netcat)

Note

Shell enhancements are not gated on development.enable: fzf, ripgrep, fd, and zoxide are installed unconditionally on every Marchyo system, and the Starship prompt is tied to marchyo.theme.enable instead.

Container backend and the docker group

The container backend is selectable and defaults to rootless Podman:

Option	Default	Description
marchyo.development.containers.backend	"podman"	"podman" (rootless, docker-compatible CLI) or "docker" (rootful daemon)
marchyo.development.containers.dockerGroup	false	Add Marchyo users to the root-equivalent docker group (Docker backend only)

The default rootless Podman backend needs no elevated group at all: it is daemonless, runs in a user namespace, and provides a docker compatibility shim so most workflows keep working unchanged.

To opt into the classic rootful Docker daemon instead:

marchyo.development.containers.backend = "docker";

Danger

The Docker backend adds the docker group, and membership in it is equivalent to passwordless root on the host. The Docker daemon runs as root and owns its socket, so any process that can reach the socket can start a container that mounts and writes the whole host filesystem as root. Supplementary groups are inherited by every process in the user’s session, so granting it exposes root to all code the user runs — browsers, editors, AI agents, npm scripts, build tools — not just Docker.

Marchyo therefore does not add users to the docker group by default. The daemon still runs; sudo docker … works. Set marchyo.development.containers.dockerGroup = true only if you accept that every process in the session effectively has root.

AI coding agent

Pick a default AI coding-agent CLI (installed only when development.enable is on). The chosen CLI is installed and $AI_AGENT is set to its command:

Option	Default	Choices
marchyo.defaults.aiAgent	null	"claude-code", "codex", "opencode"

marchyo.development.enable = true;
marchyo.defaults.aiAgent = "claude-code";  # installs the CLI, $AI_AGENT = "claude"

Gaming

When marchyo.gaming.enable = true and the desktop is enabled, Marchyo configures:

• Steam with Remote Play firewall ports, the Steam hardware udev rules, and the Xbox controller driver (xpadneo)
• GameMode and Gamescope for performance and upscaling
• MangoHUD performance overlay
• Lutris and Heroic launchers plus ProtonUp-Qt

Gaming is not auto-enabled by the desktop, so a plain desktop stays lean. Steam pulls in 32-bit graphics and is x86_64-only, so on other architectures the flag has no effect.

{
  marchyo.desktop.enable = true;
  marchyo.gaming.enable = true;
}