Install nrgrd
nrgrd is NeuroGrid's terminal client: a coding agent that works on your
repository from the shell. It connects to any OpenAI-compatible endpoint,
including a NeuroGrid deployment, and it is published on PyPI as
nrgrd.
It runs on macOS, Linux and Windows, and needs Python 3.11 or newer.
This is the tool for using inference. If you want to rent out a GPU, you want the agent instead, which ships as a Docker image.
Install
With uv (recommended)
uv installs nrgrd in its own environment, puts the nrgrd command on your PATH,
and downloads a suitable Python if you don't have one.
uv tool install nrgrd
Don't have uv yet? Install it first, then run the command above in a new terminal.
# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
With pipx
Needs Python 3.11 or newer already installed.
pipx install nrgrd
With pip
Install into a virtual environment, not your system Python. nrgrd is then available whenever that environment is active.
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install nrgrd
Check it worked
nrgrd --version
It prints the installed version, for example nrgrd 0.1.0.
First run
Open a terminal in the project you want to work on and start nrgrd:
cd my-project
nrgrd # interactive
nrgrd "explain this repository" # one prompt, then exit
The first time, it asks for the endpoint URL and API key of your deployment, both from your NeuroGrid console. It then asks the endpoint which models it serves, and if there is only one, it picks it for you.
The API key is kept in your operating system's credential store — Keychain, Windows Credential Manager, or Secret Service on Linux — not in a config file.
Change the connection later with /config edit. Type /help to see every
command.
Update and uninstall
| uv | pipx | pip | |
|---|---|---|---|
| Update | uv tool upgrade nrgrd | pipx upgrade nrgrd | pip install -U nrgrd |
| Uninstall | uv tool uninstall nrgrd | pipx uninstall nrgrd | pip uninstall nrgrd |
Troubleshooting
Windows: "incompatible hardlinks" (os error 396)
Symptom. uv tool install nrgrd fails with
The cloud operation cannot be performed on a file with incompatible hardlinks. (os error 396).
Cause. uv installs by hardlinking files from its cache. OneDrive, common on work laptops, does not allow hardlinks in the folders it manages.
Fix. Tell uv to copy files instead:
uv tool uninstall nrgrd
uv tool install nrgrd --link-mode=copy
To make copying the default for every uv install, run this once and open a new terminal:
[Environment]::SetEnvironmentVariable("UV_LINK_MODE", "copy", "User")
nrgrd is not recognised
Cause. The folder where uv or pipx puts commands is not on your PATH yet.
Fix. Run uv tool update-shell (or pipx ensurepath), then open a new
terminal.
error: externally-managed-environment
Cause. On recent macOS and Linux, pip refuses to install into the system Python, to protect the operating system's own packages.
Fix. Use uv or pipx, or pip inside a virtual environment as shown above.
Package 'nrgrd' requires a different Python
Cause. pip or pipx is running on Python 3.10 or older.
Fix. Install with uv, which downloads a suitable Python by itself, or install Python 3.11 or newer.
pipx: "pipx needs uv>=…"
Cause. Recent pipx uses uv when it finds uv on your machine, and your uv is older than it requires.
Fix. Update uv (uv self update if you installed it with the standalone
installer), or skip it with pipx install --backend pip nrgrd.