Installing Pi and Configuring OmniProxy

Pi is a small terminal assistant—a program that talks with you directly in the command line, reads files, and completes tasks. It has a short system prompt and only a few tools by default. If you need other commands, workflows, or interfaces, you can add them later through extensions. Extensions are components that add capabilities to Pi, and you can share them with others after creating them.

Subagents delegate part of a task to another assistant, while plan mode organizes the steps before execution begins. Neither feature is included by default, but you can ask Pi to build them or install packages shared by others.

Before you start

macOS and Linux use an installation script—a single command that automatically downloads and installs Pi. On Windows, use the PowerShell command provided on the Pi homepage. PowerShell is the command-line environment included with Windows. You can also install Pi in WSL, the Linux environment available within Windows.

If you choose to install with npm, you need Node.js 22.19 or later. npm is the package manager used with Node.js and can install Pi from the command line.

macOS Linux

install.sh

• curl the official script
• The installer pins the dependencies
• Update with pi update

Windows

install.ps1

• Official PowerShell command
• Git for Windows provides Bash
• You can also use WSL

Node already installed

npm

• Requires Node 22.19+
• The package name is pi-coding-agent
• Add --ignore-scripts

Install and launch Pi for the first time

On macOS or Linux, open a terminal and run:

curl -fsSL https://pi.dev/install.sh | sh

On Windows, open PowerShell and run:

powershell -c "irm https://pi.dev/install.ps1 | iex"

If Node.js 22.19 or later is already installed, you can also use the alternative command from the Quickstart:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

The installation script may pause to ask questions in an interactive terminal. Follow the on-screen prompts to continue. If you already have a compatible version of Node, this npm command will not ask questions. To install Pi in another directory, add --prefix /your/directory. On 2026-10-09, this installed Pi 1.1.0.

A normal npm installation does not require dependency lifecycle scripts, which are scripts that packages run automatically during installation. The installation script pins dependencies; afterward, update Pi with pi update. For an npm installation, use the update method provided by your package manager. Nix users should install from Pi’s flake. A flake is a Nix configuration that describes software and its dependencies, and pi update cannot update a Nix installation.

After installation, first confirm that your terminal can find Pi:

pi --version

On Windows, if you want models to execute Bash commands, installing Git for Windows is recommended for most local users. Bash is the command environment Pi uses to run some commands. Pi checks the shellPath setting in ~/.pi/agent/settings.json, Git Bash under Program Files, and then bash.exe on PATH, in that order. shellPath specifies the location of Bash, while PATH is the list of directories the system searches for commands.

After starting Pi, you can enter !printf 'Bash is working\n' to check it. If your files and tools are already in WSL, install Pi in that Linux environment by following the Quickstart.

Next, enter the folder you want Pi to inspect or work on, and then start it:

cd /path/to/folder
pi

This folder becomes Pi’s current working scope. Pi uses it to discover files and configuration and to group sessions.

Get connection values from OmniProxy

First, obtain these three values from OmniProxy:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: Copy the full ID from the current OmniProxy model list

baseUrl is the API endpoint to which Pi sends requests, and it must include /v1. apiKey is the key used to access the API. Model ID is the name of the model to call and must be copied in full from the current OmniProxy model list.

Set api to openai-completions, as shown in the compatible API example. This field tells Pi which API format to use when sending requests.

Copy the entire model ID, including any slashes in the name. On 2026-10-09, the two reference IDs in the provider documentation were gemini-3.8-flash and grok-4.7. Do not copy a name that is not present in the list.

Enter the tool configuration

Pi’s user-level custom model configuration is stored in models.json. This file is located in the agent directory, which defaults to ~/.pi/agent, so its full path is ~/.pi/agent/models.json. If the PI_CODING_AGENT_DIR environment variable is set, Pi uses the directory specified by that variable instead. An environment variable is a configuration value supplied by the system for programs to read.

Enter the configuration as shown in the compatible API example:

{
  "providers": {
    "omniproxy": {
      "baseUrl": "https://your-omniproxy-origin.example/v1",
      "api": "openai-completions",
      "apiKey": "<YOUR_OMNIPROXY_API_KEY>",
      "models": [
        { "id": "gemini-3.8-flash", "input": ["text"] },
        { "id": "grok-4.7", "input": ["text"] }
      ]
    }
  }
}

providers lists the connected services, while models lists the models that can be selected. Each model’s id must match the complete Model ID in the current OmniProxy model list. input indicates that the model is configured here for text input.

apiKey can be entered as a literal value, or as $NAME or ${NAME} so Pi reads it from an environment variable. A value beginning with ! is treated as a command and executed for every request. Do not commit a real key to a repository. If the gateway does not validate keys, you can enter a placeholder string used only on your local machine. On 2026-10-09, Pi successfully read the file with this configuration.

Opening /model reloads this file. /model is the interface in Pi for viewing and selecting models. Custom models do not appear in /model until Pi can resolve their credentials. After selecting a model, press Ctrl+S to save it as the default model for new sessions.

File

models.json

• Default directory: ~/.pi/agent
• Add an entry under providers
• Set api to completions

Address

baseUrl

• Include /v1
• apiKey can reference a variable
• The model id must be exact

Select

/model

• Opening it reloads the file
• Select the model you just added
• Ctrl+S saves it as the default

Verify with a real task

After completing the configuration, you can perform a non-interactive check in a directory containing files. Non-interactive mode means Pi completes this single task and then exits instead of entering an ongoing conversation. Replace the value after --model with the complete ID from the current OmniProxy list:

pi -p --provider omniproxy --model gemini-3.8-flash --tools read "Read the first line of the file you specify. Do not modify the file."

Here, --tools read enables only the read tool, and the task also explicitly instructs Pi not to modify the file. On 2026-10-09, Pi 1.1.0 read the file contents successfully. The first response took about two minutes.

You can also use interactive mode: enter the directory, run pi, and then select a model with /model. One example task in the Quickstart asks Pi to explain how the repository is organized and how to run its checks. Observe whether it reads the files and provides an explanation, then confirm the source and model ID in OmniProxy’s request logs.

Launch

pi launches

• First cd to the folder
• pi --version produces output
• The model name appears at the bottom of the interface

Task

It read the directory

• Ask how the repository is organized
• Review the files it lists
• Do not rely only on a successful configuration save

Logs

Visible in the gateway

• Source is Pi
• Model ID matches
• Keep the key on the local machine

Common errors

• pi cannot be found: Reopen the terminal and try pi --version again. For an npm installation, confirm that the global bin directory is on PATH.
• The custom models do not appear in /model: Confirm that models.json is in ~/.pi/agent/, verify that apiKey can be resolved, and then reopen /model.
• Windows reports that Bash cannot be found: Install Git for Windows, or set shellPath in ~/.pi/agent/settings.json. Backslashes in JSON must be written twice.
• The request is rejected: Check that api is openai-completions and that baseUrl ends in /v1. Do not enable additional compatibility options merely because the service describes itself as compatible.
• The model ID is invalid: Copy it again from the current OmniProxy list.

Official references

For installation commands, see the Pi website and Quickstart. For the model file, see Choose a Model and Configuration. For the Windows command environment, see Run Pi on Windows. For the model IDs used in the examples, see the Gemini model list and xAI models page.

Replace every placeholder with values from your own OmniProxy configuration. Never publish a real key.

A saved result or HTTP 200 alone does not prove full Agent compatibility. Check the source and model in OmniProxy's call record.

Official sources · Pi ↗