Skip to navigation
Reference

Remote Locations

View as Markdown

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

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.

MethodDescription
ManualYou provide your own SSH key and connection details for an existing machine with AI Workbench installed. See Manually Add an Existing Remote Location.
NVIDIA SyncA 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 BrevA 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.

System Requirements

Manual Requirements

RequirementDescription
Remote System DependenciesUbuntu 22.04 LTS, Ubuntu 24.04 LTS, or Ubuntu 26.04 LTS with AI Workbench installed. See Manually Install on Ubuntu (Remote).
Local DependenciesAI Workbench.
Remote User AccountA non-root user on the remote with sudo privileges.
NetworkSSH access from your local machine to the remote system.
SSH AuthenticationPublic/private key based access. Password-based SSH authentication is not supported. See Locations and SSH for supported key types and platform details.

NVIDIA Sync Requirements

RequirementDescription
Remote System DependenciesUbuntu 22.04 LTS or Ubuntu 24.04 LTS.
Local DependenciesAI Workbench and NVIDIA Sync installed
Remote User AccountA non-root user on the remote with sudo privileges.
NetworkSSH access from your local machine to the remote system.
SSH AuthenticationPassword-based SSH authentication.

NVIDIA Brev Requirements

RequirementDescription
NVIDIA AccountRequired for Brev authentication. Created during the integration flow if you don’t yet have one.
Credit CardRequired for billing. For pricing details, see the Brev documentation.
Local DependenciesAI Workbench Desktop App installed in full local mode with Brev integration configured.

Connection Fields

Manually adding a remote location requires you to enter information in the Desktop App or CLI.

NVIDIA Sync and Brev populate these fields automatically.

FieldDescription
Location NameA unique name for the remote location. Appears in the Locations Manager. Must be unique across all your locations (local and remote).
DescriptionA short description of the remote location (e.g., “AWS g4dn.xlarge with T4 GPU for training”).
Hostname or IP AddressThe remote machine’s IP address or hostname. Must be accessible from your local network or the internet.
SSH PortThe SSH port on the remote system. Default is 22.
SSH UsernameThe non-root user with sudo privileges on the remote system.
SSH Private Key FileThe 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 FileRequired 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 DirectoryThe absolute path to the .nvwb directory on the remote system. Default is $HOME/.nvwb.

SSH Tunneling

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

TunnelDescription
Service TunnelMaps 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 TunnelMaps 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.

Port Assignment

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

LocationPorts
First remote location10000 (proxy), 10001 (service)
Second remote location10002 (proxy), 10003 (service)
Third remote location10004 (proxy), 10005 (service)

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.

NVIDIA Brev Specifications

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.