nix-profile-manager

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:

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 <flake>#<package>

IMPORTANT: In some flakes (like nixpkgs) packages can be nested: <flake>#<scope>.<package>

Essential Commands

Search for Packages

# Search in nixpkgs flake:
nix search nixpkgs git

# Search in specific (fully qualified) flake
nix search "github:user/repo[/branch]" <package-name>

# Or get a more detailed JSON output
nix search nixpkgs python3 --json | jq '.[].pname'

Manage Profile

# Add package
nix profile add --profile <profile_path> "<flake>#<package>"

# List installed packages
nix profile list --profile <profile_path>

# Remove by index or element number
nix profile remove --profile <path>/profile 0

# Upgrade packages
nix profile upgrade --profile <profile_path> <package_name>
nix profile upgrade --profile <profile_path> --all  # All packages installed in this profile

Registry Management

# List available flake aliases
nix registry list

# Add custom registry entry (user-level)
nix registry add myflake github:user/repo/branch

General Workflow

# 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 <flake> <partial-name> 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