Remote Locations#

This page documents the technical specifications for remote locations in AI Workbench.

For conceptual background and SSH authentication overview, see AI Workbench Locations.
For step-by-step procedures, see How to Add Remote Locations.
For SSH and platform-specific FAQs, see Locations and SSH.

Connection Methods#

AI Workbench supports three methods to add a remote location.: Each method handles SSH configuration differently. All three result in the same remote location experience once connected.

Method	Description
Manual	You provide your own SSH key and connection details for an existing machine with AI Workbench installed. See Manually Add an Existing Remote Location.
NVIDIA Sync	A system tray utility that installs AI Workbench on the remote and manages the SSH key (`nvsync.key`) for you. Requires password-based SSH access to the remote. See Use NVIDIA Sync with AI Workbench.
NVIDIA Brev	A cloud GPU broker that provisions instances and manages SSH through the Brev CLI. Requires an NVIDIA account and credit card. See Add a Brev Instance.

Requirement	Description
Remote System Dependencies	Ubuntu 22.04 LTS or Ubuntu 24.04 LTS with AI Workbench installed. See Manually Install on Ubuntu (Remote).
Local Dependencies	AI Workbench.
Remote User Account	A non-root user on the remote with sudo privileges.
Network	SSH access from your local machine to the remote system.
SSH Authentication	Public/private key based access. Password-based SSH authentication is not supported. See Locations and SSH for supported key types and platform details.

Requirement	Description
Remote System Dependencies	Ubuntu 22.04 LTS or Ubuntu 24.04 LTS.
Local Dependencies	AI Workbench and NVIDIA Sync installed
Remote User Account	A non-root user on the remote with sudo privileges.
Network	SSH access from your local machine to the remote system.
SSH Authentication	Password-based SSH authentication.

Requirement	Description
NVIDIA Account	Required for Brev authentication. Created during the integration flow if you don’t yet have one.
Credit Card	Required for billing. For pricing details, see the Brev documentation.
Local Dependencies	AI Workbench Desktop App installed in full local mode with Brev integration configured.

Manually adding a remote location requires you to enter information in the Desktop App or CLI.: NVIDIA Sync and Brev populate these fields automatically.

Field	Description
Location Name	A unique name for the remote location. Appears in the Locations Manager. Must be unique across all your locations (local and remote).
Description	A short description of the remote location (e.g., “AWS g4dn.xlarge with T4 GPU for training”).
Hostname or IP Address	The remote machine’s IP address or hostname. Must be accessible from your local network or the internet.
SSH Port	The SSH port on the remote system. Default is `22`.
SSH Username	The non-root user with sudo privileges on the remote system.
SSH Private Key File	The absolute path to the private key file on your local machine. If using a password-protected key with SSH Agent, enter the path to the `.pub` file instead. See Locations and SSH for details on password-protected keys.
SSH Public Key File	Required only when using a password-protected SSH key managed by SSH Agent. The absolute path to the public key file on your local machine.
Workbench Directory	The absolute path to the `.nvwb` directory on the remote system. Default is `$HOME/.nvwb`.

When you open a remote location, AI Workbench creates two SSH port-forwarding tunnels.

Tunnel	Description
Service Tunnel	Maps the remote AI Workbench service to localhost. Enables the Desktop App or CLI to communicate with the remote service using the same GraphQL API as local locations. Default port: `10001`.
Proxy Tunnel	Maps the remote reverse proxy to localhost. Routes web application traffic (JupyterLab, TensorBoard, etc.) to your local browser. Default port: `10000`.

The SSH connection remains active as long as the remote location is open.: Closing all Desktop App windows connected to the location or running nvwb deactivate in the CLI terminates the SSH tunnels.

AI Workbench assigns port pairs dynamically when you add multiple remote locations.

Port assignments are stored in ~/.nvwb/contexts.json and persist across sessions.: If you delete and re-add a location, it may receive different port numbers.

AI Workbench manages Brev instance lifecycle automatically.: When you open a Brev location, AI Workbench starts the instance. When you close all windows connected to that location, AI Workbench stops the instance.

Verify instances are stopped after use to avoid unexpected charges.

Connection issues or app crashes may prevent automatic shutdown. Verify instance status in the Brev console at NVIDIA Brev after closing locations.