nix-profile-manager

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