nix-agent

nix-agent is a terminal app that helps you work with Nix and NixOS. You chat in a simple text interface; answers can be grounded in official manuals, and the assistant can run read-only, allowlisted checks on your machine (for example looking up options or flake-related commands). It does not edit your system configuration by itself—you stay in control.

Community

✨ Idea or bug? Open an issue
❤️ Thanks for trying nix-agent and sharing feedback!

Supported platforms

Where it runs	Notes
Linux (64-bit PC or ARM)	Pre-built releases for common x86_64 and aarch64 machines with glibc (similar to current GitHub release builds). Very old systems might not run the release binary.
NixOS	The installer can optionally help set up your host so the published binary runs smoothly (you’ll be prompted where sudo is needed).

Table of Contents

• Quick start
• What you get
• Install (step by step)
• First run
• Configuration (basics)
• Troubleshooting
• Privacy & safety
• For maintainers
• Credits
• License

Quick start

1. Install (run as your normal user; review any “pipe to bash” script before you run it if you prefer):

curl -fsSL https://raw.githubusercontent.com/Firstp1ck/nix-agent/main/scripts/install.sh | bash

2. Add an API key for the AI service you use (OpenAI-compatible). For example:

export OPENAI_API_KEY=sk-...

You can also use NIX_AGENT_API_KEY or put api_key in the config file (see below).

3. Start the app in a real terminal:

nix-agent

What you get

Chat in the terminal	Ask questions about Nix and NixOS in a keyboard-friendly interface.
Grounded answers	The app can use an offline-style index of official documentation so replies line up with the manuals you care about.
Background doc refresh	On first start (and on a schedule you can tune), it can download and index docs for you; you’ll see simple progress hints in the UI.
Careful tooling	Built-in actions are limited on purpose: allowed file reads, documentation search, and similar non-destructive steps—not silent edits to /etc or your flakes.
Optional doc-only mode	You can prefer online search only, or local docs only, depending on your setup.

To refresh the documentation index from the command line anytime:

nix-agent docs sync

Install (step by step)

The install script downloads the latest release from GitHub and puts nix-agent in ~/.local/bin by default.

• NixOS: The script may offer to apply a small host preparation step (flakes, nix-ld, curl, and related pieces) so the release binary runs. After nix-ld is first enabled, you might need to log out and back in (or reboot) once before nix-agent starts cleanly.
• Other Linux: You get the binary in your chosen install folder; NixOS-only steps are skipped automatically.

Pin a version (example: install v0.1.0 and confirm NixOS prep without extra prompts):

curl -fsSL https://raw.githubusercontent.com/Firstp1ck/nix-agent/main/scripts/install.sh | bash -s -- v0.1.0 --yes

Using a fork or mirror: Set NIX_AGENT_GITHUB_REPO to owner/repo, or point NIX_AGENT_INSTALL_BASE at your raw scripts/ URL prefix. You can also set NIX_AGENT_BINDIR for a different install directory, NIX_AGENT_VERSION to pin a tag, or NIX_AGENT_SKIP_NIXOS_PREP=1 on NixOS to skip the optional sudo configuration step. An optional GITHUB_TOKEN can help if you hit GitHub API rate limits when resolving “latest.”

First run

• Use a normal terminal window (not a pipe). If you use SSH, you may need a TTY (for example ssh -t user@host) so the interface can start.
• The first time you open the main app, it creates ~/.config/nix-agent/ and writes a starter config.toml if needed. The docs sync command updates caches under ~/.cache/nix-agent/ and does not create the config for you.
• API keys from the environment are not written to disk; keep using env vars or set api_key in the config file yourself.

Configuration (basics)

Config file: ~/.config/nix-agent/config.toml

Typical starter settings:

# api_key = "sk-..."
base_url = "https://api.openai.com/v1"
model = "gpt-5-mini"
doc_mode = "auto"   # auto | web_only | local_only

# Background download of official docs (for auto / local_only)
docs_auto_sync = true
docs_sync_interval_days = 7

Local models (example): point base_url at your machine (for example Ollama’s OpenAI-compatible URL) and pick a model name your server provides.

Troubleshooting

Symptom	What to try
Blank or broken UI over SSH	Use ssh -t so you get a real terminal, or run from a local terminal.
nix-agent won’t start on NixOS right after install	Log out and back in (or reboot) once after nix-ld was first enabled.
“Latest” install fails or rate-limits	Set GITHUB_TOKEN, or install a specific version with the bash -s -- vX.Y.Z form above.
Docs feel stale	Run nix-agent docs sync or lower docs_sync_interval_days in config.

Privacy & safety

• The assistant does not change /etc/nixos or your flakes on its own. Any host-level changes come from you running the installer on NixOS, and only where the script describes.
• File access in the app is restricted to sensible paths (for example your NixOS config tree and the current working directory, with safety checks).
• For system changes, prefer nixos-rebuild build or test before switch when you’re unsure.

For maintainers

Tag a release whose name starts with v (for example v0.1.0 and push it). The release workflow builds, smoke-tests, and uploads archives plus checksums. Optional release notes: add Release-docs/RELEASE_vX.Y.Z.md matching the tag. Local helper: ./scripts/release.sh.

Credits

• Built with Ratatui and Crossterm
• Made for the Nix and NixOS ecosystem

License

MIT — see the license field in Cargo.toml.