Skip to main content

​
Nix Installation

Install FluffBuzz declaratively with nix-fluffbuzz — a batteries-included Home Manager module.
The nix-fluffbuzz repo is the source of truth for Nix installation. This page is a quick overview.

​
What You Get

  • Gateway + macOS app + tools (whisper, spotify, cameras) — all pinned
  • Launchd service that survives reboots
  • Plugin system with declarative config
  • Instant rollback: home-manager switch --rollback

​
Quick Start

1

Install Determinate Nix

If Nix is not already installed, follow the Determinate Nix installer instructions.
2

Create a local flake

Use the agent-first template from the nix-fluffbuzz repo:
mkdir -p ~/code/fluffbuzz-local
# Copy templates/agent-first/flake.nix from the nix-fluffbuzz repo
3

Configure secrets

Set up your messaging bot token and model provider API key. Plain files at ~/.secrets/ work fine.
4

Fill in template placeholders and switch

home-manager switch
5

Verify

Confirm the launchd service is running and your bot responds to messages.
See the nix-fluffbuzz README for full module options and examples.

​
Nix Mode Runtime Behavior

When FLUFFBUZZ_NIX_MODE=1 is set (automatic with nix-fluffbuzz), FluffBuzz enters a deterministic mode that disables auto-install flows. You can also set it manually: 
export FLUFFBUZZ_NIX_MODE=1
On macOS, the GUI app does not automatically inherit shell environment variables. Enable Nix mode via defaults instead: 
defaults write com.fluffbuzz.mac fluffbuzz.nixMode -bool true

​
What changes in Nix mode

  • Auto-install and self-mutation flows are disabled
  • Missing dependencies surface Nix-specific remediation messages
  • UI surfaces a read-only Nix mode banner

​
Config and state paths

FluffBuzz reads JSON5 config from FLUFFBUZZ_CONFIG_PATH and stores mutable data in FLUFFBUZZ_STATE_DIR. When running under Nix, set these explicitly to Nix-managed locations so runtime state and config stay out of the immutable store.
VariableDefault
FLUFFBUZZ_HOMEHOME / USERPROFILE / os.homedir()
FLUFFBUZZ_STATE_DIR~/.fluffbuzz
FLUFFBUZZ_CONFIG_PATH$FLUFFBUZZ_STATE_DIR/fluffbuzz.json