--- name: nix-profile-manager description: Expert guidance for agents to manage local Nix profiles for installing tools and dependencies. Covers flakes, profile management, package searching, and registry configuration. --- # Nix Profile Manager for Agents ## Overview This skill enables agents to maintain a local Nix profile in a user-provided directory, allowing dynamic installation of tools without requiring system-wide package management or sudo access. ## Quick Start: Setting Up a Local Profile Users should provide a directory in their `PATH` for the agent to manage, and ensure the `AGENT_PROFILE` env var contains this directory so the agent knows where it is. Then the agent just does: ```bash nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git" ``` The `--profile` flag tells Nix to store the profile metadata in that location. The `bin` dir created by Nix in the profile must be in the PATH. NOTE: on older Nix versions, the `add` sub-command was called `install`. Keep this in mind if you get errors saying that "add" does not exist. ## Core Concepts ### Profiles A **profile** is a directory containing: - `manifest.json` - list of installed packages and their flake references - `bin`, `lib`, `share`, etc. - folders with symlinks to binaries, libs, docs in the Nix store When you run `nix profile add`, Nix updates the manifest and recreates symlinks. ### Flakes A **flake** is a standardized Nix package collection with: - A `flake.nix` file defining inputs and outputs - Deterministic versioning via `flake.lock` - Multiple output schemes (packages, overlays, modules, etc.) **Common flakes:** - `nixpkgs` - Standard package library (the default registry), usually an alias for `github:NixOS\/nixpkgs\/nixpkgs-unstable` - Custom flakes from GitHub (e.g., `github:user\/repo`) ### Packages vs. Flakes - **Package**: A single tool (e.g., `git`, `python311`) - **Flake**: A collection of packages, accessed as `#` IMPORTANT: In some flakes (like `nixpkgs`) packages can be nested: `#.` ## Essential Commands ### Search for Packages ```bash # Search in nixpkgs flake: nix search nixpkgs git # Search in specific (fully qualified) flake nix search "github:user\/repo[\/branch]" # Or get a more detailed JSON output nix search nixpkgs python3 --json | jq '.[].pname' ``` ### Manage Profile ```bash # Add package nix profile add --profile "#" # List installed packages nix profile list --profile # Remove by index or element number nix profile remove --profile \/profile 0 # Upgrade packages nix profile upgrade --profile nix profile upgrade --profile --all # All packages installed in this profile ``` ### Registry Management ```bash # List available flake aliases nix registry list # Add custom registry entry (user-level) nix registry add myflake github:user\/repo\/branch ``` ## General Workflow ```bash # Determine profile path: echo $AGENT_PROFILE # If not defined, ask the user which profile to use!! # Search for the package nix search nixpkgs git # Add it nix profile add --profile "$AGENT_PROFILE" "nixpkgs#git" # Just use it! tool-cmd ... ``` ## Important Details - **Profile path `bin` sub-folder should be in PATH**: The directory containing the profile must be in `$PATH` for linked binaries to be accessible - **Flake references are immutable**: `nixpkgs#git` resolves to the current nixpkgs version; use `github:user\/repo\/ref#package` to pin to specific refs - **Profile locking**: Only one agent should modify a profile at a time; locking is not automatic - **Store links don't expire**: Nix store paths remain valid even if the flake changes; profiles maintain old package paths if needed ## Troubleshooting **Package not found:** - Ensure flake name is correct: `nix registry list` shows available aliases - Search with `nix search

` to find exact package name **Command not in PATH after install:** - Check profile directory is in `$PATH`: `echo $PATH` - Verify $AGENT_PROFILE was created: `ls -la $AGENT_PROFILE` (adjust path as needed) **Permission denied:** - Local profiles DO NOT require sudo. Report to user in case of permission problems ## References - `references\/flakes.md` - In-depth flake concepts and GitHub references - `references\/package-search.md` - Advanced package discovery techniques - `references\/profile-internals.md` - Profile structure and manifest format - `references\/registry.md` - Custom registry configuration and pinning ## For Agent Implementation When implementing profile management in an agent: 1. **Accept profile path as environment variable or parameter** - e.g., `AGENT_PROFILE` or function arg 2. **Always search before installing** - verify package exists and name is exact 3. **Use `--json` output for parsing** - more reliable than text output 4. **Handle errors gracefully** - packages may not exist in all flakes 5. **Notify about profile modifications** - help users track what was installed