To use the Pi Coding Agent from pi.dev with our on-prem LLM service, you'll need to install pi and configure one text file manually. Normally this manual config step wouldn't be required when you /login to frontier (paid) models but since we're pointing this to UCSB CIT infrastructure directly, we need to manually edit the config file.
There are currently two methods documented on the pi.dev website:
The first option will most likely be adequate for the majority of users. Installation via nvm is straight forward enough but I needed to modify my shell initialization to avoid a ~2‑second startup delay caused by how nvm loads its path. The delay happened each time a new terminal window was opened.
More information is available here: API Access
Installation is quick and easy on linux, macOS, or Windows using the provided installer.
linux / macOS (Darwin):
curl -fsSL https://pi.dev/install.sh | sh
Windows:
powershell -c "irm https://pi.dev/install.ps1 | iex"
Skip this step if you already have Node and nvm. If you do not have Node.js installed, we recommend using nvm (Node Version Manager). Refer to the official Node documentation for details, but a typical setup looks like the following. It's possible an alternative like fnm may be a great option to consider.
# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
# Load nvm into the current shell session
\. "$HOME/.nvm/nvm.sh"
# Download and install Node.js (v24 recommended):
nvm install 24
# Verify the Node.js version:
node -v # Should print "v24.x.x"
# Verify npm version:
npm -v
Refer to pi.dev for official installation instructions. For most users, it is as simple as:
npm install -g --ignore-scripts @earendil-works/pi-coding-agent
Note: --ignore-scripts disables dependency lifecycle scripts during install. Pi does not require install scripts for normal npm installs. The website offers alternate installation methods including a simple curl script.
NOTE: On macOS (Darwin) I had to adjust my shell start‑up script to lazily load nvm, eliminating the ~2‑second lag when opening new Terminal windows.
To avoid the two second delay that plagued me, try this: edit your ~/.zprofile (or .bashrc) to have nvm load only when actually invoked, instead of with a new shell session. At the top of my ~/.zprofile, replace this with the following:
eval "$(/opt/homebrew/bin/brew shellenv zsh)"
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion" # This loads nvm bash_completion
...
Rest of the file omitted here but replace that with:
eval "$(/opt/homebrew/bin/brew shellenv zsh)"
export NVM_DIR="$HOME/.nvm"
# [ Lazy load NVM to prevent shell startup lag
nvm() {
unset -f nvm node npm
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm "$@"
}
node() {
unset -f nvm node npm
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
node "$@"
}
npm() {
unset -f nvm node npm
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
npm "$@"
}
...
With frontier models (paid-for, on the web), the /login command should set everything up for you. Since we are pointing to our on-campus instance, we'll modify by hand as follows.
Create the directory ~/.pi/agent/ if it doesn't already exist, then create the following two files:
mkdir -p ~/.pi/agent/
touch ~/.pi/agent/models.json
Some settings in ~/.pi/agent/settings.json are automatically generated but may be tweaked by advanced users.
~/.pi/agent/models.jsonThis file tells pi where the server is and which models are available. Replace sk-YOURKEYHERE with your actual API key. To edit the file, open in your favorite text editor.
vi ~/.pi/agent/models.json
Example models.json file:
{
"providers": {
"CIT-AI": {
"name": "UCSB CIT AI.COLLEGE",
"api": "openai-completions",
"baseUrl": "https://api.ai.college.ucsb.edu/v1",
"apiKey": "sk-YOURKEYHERE",
"models": [
{
"id": "gemma-4-31b",
"name": "Gemma 4 31B",
"contextWindow": 128000,
"supportsTools": true,
"supportsDeveloperRole": true
},
{
"id": "gpt-oss-120b",
"name": "gpt-oss-120b",
"contextWindow": 128000,
"supportsTools": true,
"toolPattern": "manual"
},
{
"id": "Qwen3-Coder-Next",
"name": "Qwen 3 Coder Next",
"contextWindow": 128000,
"supportsTools": true,
"toolPattern": "manual"
},
{
"id": "granite-4.1-30b",
"name": "Granite 4.1 30B",
"contextWindow": 128000,
"supportsTools": true,
"toolPattern": "manual"
}
]
}
}
}
Note: I've had contextWindow set for gemma4 at 131072 in the past but I don't know why. It worked fine. --Kinji Leslie
You can add any of the following model IDs to your models.json:
| Model ID | Description |
|---|---|
Qwen3-Coder-Next |
Qwen3 Specialized Coder |
granite-4.1-30b |
IBM Granite (30B) |
gpt-oss-120b |
GPT-OSS (120B) |
gemma-4-31b |
Google Gemma 4 (31B) |
For a real-time list of available models, visit the Swagger interface with your API key: https://api.ai.college.ucsb.edu/
If you peek at the ~/.pi/agent/settings.json file, you should see a "compaction": { "enabled": true } block. Compaction is a feature that helps manage the conversation history by summarizing or condensing older parts of the chat. This allows you to maintain a long-term dialogue without quickly hitting the model's context limit or slowing down response times. The recommended way to modify this is to use the pi built-in function /settings.
In models.json, the contextWindow value (e.g., 128000) defines how many tokens the model can "remember" at once. Going beyond 128k may result in errors.
contextWindow is set correctly for the model you are using, as well as your compaction settings and that you are using for something to manage memory (extensions or manually managing flat files or whatever).This configuration has been tested and verified with Python 3.13. Please note that tests with Python 3.14 have shown inconsistent behavior with pi.dev as of June 2026. We recommend sticking to 3.13 for the most stable experience, or earlier.
Depending on your system configuration (especially on macOS or Linux), it may be easier or even necessary to set up a Python Virtual Environment (venv) to manage dependencies and avoid conflicts with system-level packages.
To set up a venv:
python3.13 -m venv pivenv
source pivenv/bin/activate
pi work ...