--- title: "Install and Use NVIDIA PAIR — Set Up PAIR with Terminal" canonical: "https://build.nvidia.com/spark/pair/terminal-setup.md" --- # Step 1. Start the terminal interface Use the PAIR terminal interface on a system without a desktop environment or over SSH. If the desktop application is running, quit it first. Do not run the desktop application and terminal interface on the same system. They start competing services and can conflict over ports, engines, and settings. Install PAIR with the appropriate platform package, then run: ```bash nvpair ``` `nvpair` starts the bundled terminal interface and its PAIR service process tree. No other PAIR process needs to be running first. The header changes to `broker ready v` when the terminal interface connects to the service. If it remains on `connecting to broker...`, open the **Logs** tab and inspect the service output. # Step 2. Pair this system PAIR uses the same six-digit PIN exchange as the desktop application. Pair only systems on a trusted network. The PIN is a short-lived setup code, not a long-term credential. To invite a discovered system: 1. Open **Nodes** (tab 3). 2. Select the system with `j` or `k`. 3. Press `i`. 4. Give the displayed PIN to the person operating the other system. To invite a system by address: 1. Open **Cluster** (tab 7). 2. Press `i`. 3. Enter the other system's hostname or IP address. Use `host:port` when it does not use the default pairing port. 4. Press `enter`, then give the displayed PIN to the other operator. Use address-based pairing when network discovery is unavailable, such as when a network filters multicast. To accept an invitation, open **Cluster**, wait for `invite received from `, press `a`, enter the PIN, and press `enter`. Press `d` to decline an invitation. The peer appears under **Members** when pairing is complete. # Step 3. Start an engine and add a model Open **Engines** (tab 6). Select an engine with `j` or `k`, then use these keys: | Key | Action | | --- | --- | | `i` | Install the selected engine. | | `s` | Start it. | | `x` | Stop it. | | `r` | Restart it. | | `u` | Uninstall it. | | `p` | Download a model. | After you press `p`, enter a model name such as `llama3.2`, then press `enter`. Download progress appears on the status line. A system can serve a request when it is online, the engine is running, and the requested model is available there. Add the same model to several systems when you want any of them to serve it. # Step 4. Check the service and endpoint Open **Overview** (tab 1). Confirm that the header shows `broker ready v`. An `ok` worker state means no crash was reported; it does not prove that the worker is responding. `DOWN` means the broker reported a crash. Open **Proxies** (tab 4), press `g` until the engine that you prepared is selected, and read its listening port. Use `http://127.0.0.1:` as ``. The default port is `11434` for the Ollama-compatible proxy and `1234` for the LM Studio / OpenAI-compatible proxy. Ask the endpoint what the cluster can serve: ```bash curl /v1/models ``` The response lists the cluster's model inventory, not only the local system's models. The terminal interface does not send inference requests. Configure a compatible client with the local PAIR endpoint to send a request. # Step 5. Check routing activity Open **Workloads** (tab 5) to see live inference activity, including the workload ID, model, engine, state, and age. The terminal interface does not show which system served a workload. Open **Proxies** (tab 4) to check each proxy's listening port and selected system. `selected=auto` means that routing is automatic. Press `g` to switch between engines, `enter` to pin the highlighted upstream, and `a` to restore automatic routing. Leave automatic routing enabled unless you are testing one system. # Next steps ## Keep PAIR running after an SSH disconnect If an SSH session closes, the terminal interface exits and the system stops serving requests. Use a terminal multiplexer when PAIR must stay running: ```bash tmux new -s pair nvpair ``` Detach from tmux with `Ctrl-b d`. Reattach with: ```bash tmux attach -t pair ``` GNU Screen also works. Start it with `screen -S pair`, detach with `Ctrl-a d`, and reattach with `screen -r pair`. tmux and Screen are not included with PAIR. ## Move around the terminal interface The second line shows the numbered tabs. The footer shows the keys for the current tab. If the screen shows `starting...`, enlarge the terminal window. | Key | Action | | --- | --- | | `tab`, `l`, or `→` | Move to the next tab. | | `shift+tab`, `h`, or `←` | Move to the previous tab. | | `?` | Show or hide full help. | | `q` or `ctrl+c` | Quit. | | `j` / `k` or `↓` / `↑` | Move within a table. | | `f` / `b` | Move forward or backward by one page. | | `g` / `G` | Jump to the first or last row. | When you enter a PIN, address, port, or model name, all keys go to that field. Press `enter` to submit or `esc` to cancel. ## Use the terminal interface tabs | # | Tab | What it shows | | --- | --- | --- | | 1 | **Overview** | Service uptime and version, plus an `ok` / `DOWN` worker table. | | 2 | **Errors** | Active service errors by severity, age, system, and message. | | 3 | **Nodes** | Discovered systems and their connection or cluster status. | | 4 | **Proxies** | Compatible proxy ports, discovered upstreams, and selected systems. | | 5 | **Workloads** | Live inference workload ID, model, engine, state, and age. | | 6 | **Engines** | Local engine installation, running, health, and port state. | | 7 | **Cluster** | Local-system identity, cluster membership, and pairing controls. | | 8 | **Manual** | Systems added by address and their reachability. | | 9 | **Settings** | Force ports, cluster auto-sync, cluster ID, and cluster name. | | 10 | **Logs** | Service output and live log-level controls. | ## Inspect errors and logs In **Errors** (tab 2), select an error and press `c` to clear it. In **Logs** (tab 10), scroll with `j`, `k`, and the page keys. Change the service log level with `d` for debug, `i` for info, `w` for warn, or `e` for error. Check this tab first when a service does not start. ## Change settings In **Settings** (tab 9), select a row with `j` or `k` and press `enter`. Boolean settings change immediately. Text fields open for editing; press `enter` to save or `esc` to cancel. In **Proxies**, press `p` to change proxy ports. Engine ports are read-only in the terminal interface. Use the desktop application to change them. ## Command locations and flags The installer adds `nvpair` to `PATH`. It places the command in these locations: | Platform | Installed command location | | --- | --- | | Linux | `~/.local/bin/nvpair` | | macOS | `/usr/local/bin/nvpair` when that directory is writable | | Windows | A per-user `bin` directory added to `PATH` | Open a new terminal after installation if the command is not found. | Flag | Effect | | --- | --- | | `--broker-path ` | Use a PAIR service binary that is not beside the terminal-interface binary. | | `--log-level ` | Set terminal-interface logging to `debug`, `info`, `warn`, or `error`. `NVPAIR_LOG_LEVEL` provides the same setting. | | `--version` | Print the version and exit. | The terminal interface writes its logs to stderr. Service logs appear on the **Logs** tab. Press `q` to quit. Quitting also shuts down the PAIR services cleanly. ## Terminal-interface limits The terminal interface is an operations tool. It cannot: - List or delete models. It can download a model but does not show a model inventory. - Change an engine's port. - Update an engine. - Control engines on other cluster systems. - Show which system served a workload. - Send an inference request. Use a compatible client with the local endpoint.