Is this page helpful?

Manually Add an Existing Remote Location#

Overview#

Use this method when you already have key-based SSH access to a remote machine.

You have a working SSH key pair, the remote is reachable, and you can already ssh into it. If you do not have key-based access, use NVIDIA Sync instead.

The remote system must be running Ubuntu 22.04, Ubuntu 24.04, or Jetson OS.

AI Workbench must already be installed on the remote before you add it as a location. The remote user must have sudo privileges and be able to run container commands.

You will need to install AI Workbench on the remote using the CLI.

Manual addition does not bootstrap the install. Follow the remote install directions here.

Use this method when you want to choose the container runtime.

The manual path lets you install AI Workbench with Docker or Podman. NVIDIA Sync defaults to Docker and does not offer a choice during setup.

You can’t use a password-protected out of the box.

There are extra steps if your SSH key is password-protected. See Using a Password-Protected Key below for platform-specific setup instructions.

Key Concepts#

Key Permissions

SSH expects that the private key to have read/write privileges only for the user invoking it. This means it should have 600 or 400 permissions, which you can set with the chmod command.

Connections will be refused if the key permissions are not correct.

Password-Protected Key

Creating a new SSH key gives you the option to protect it with a password.

The password does NOT replace the permissions on the key expected by SSH.

AI Workbench Binary Path

Location on the remote system where AI Workbench is installed. You must enter this while configuring the SSH connection.

Defaults to $HOME/.nvwb/bin but can be customized during installation.

SSH Configuration Type

Designation of what application is managing the SSH configuration. Types are manual, brev, and sync.

Add an Existing Machine with a Non-Protected Key#

Step One: Prepare the remote system.

  1. Make sure to have key-based SSH access as a non-root user with sudo privileges

  2. Use the CLI to install AI Workench on the remote and configure the container runtime and drivers if needed. See Manually Install on Ubuntu (Remote).

Step Two: Open the Location Manager and start adding a location.

  1. Select Locations Manager > Add Remote Location (Top Right)

  2. Select Use Existing Machine

  3. Select Next

Step Three: Enter the location details.

  1. Enter Name (alphanumeric and hyphens only, no spaces)

  2. Enter Description (free text description of the location)

Step Four: Enter the SSH connection details.

  1. Enter SSH User (username on the remote system)

  2. Enter Host (IP address or hostname of the remote system)

  3. Enter Port (leave as 22 unless you’ve configured SSH on a different port)

  4. Enter Private Key Path (absolute path to your SSH private key on your local system)

  5. Enter AI Workbench Binary Path on remote (use $HOME/.nvwb/bin if you used default installation)

Step Five: Complete the addition.

  1. Select Add Location

  2. Wait for AI Workbench to verify the connection

Success: A new location card appears in the Locations Manager.

Using a Password-Protected Key#

Password-protected keys with AI Workbench require an SSH agent.

AI Workbench does not prompt for a passphrase but it can use the SSH agent to retrieve the decrypted key from memory.

You can enter the key into an SSH agent and it will be cached for use without invoking the password.

The SSH agent must run in a session that persists or the key will be cleared.

The agent caches your key. It does not write it to disk. If the terminal session starting the agent and adding your key closes, the cached key is typically lost.

You enter the public key path in the SSH configuration instead of the private key path.

AI Workbench doesn’t have a separate interface for a password protected key. Instead, it expects you to change the path to the public key instead.

In this case, the field label SSH Private Key File in the configuration is misleading.

Password-Protected Keys on Windows#

On Windows, you must use the Windows OpenSSH Authentication Agent.

The key must be on the Windows side (C:\Users\<username>\.ssh\).

Furthermore, the WSL-side** ssh-agent will not work.

To use a password-protected key on Windows:

  1. Open Services (services.msc) and find OpenSSH Authentication Agent

  2. Set the startup type to Automatic and start the service

  3. Open a Windows terminal (PowerShell or Command Prompt)

  4. Run ssh-add C:\Users\<username>\.ssh\<your-private-key>

  5. Enter the passphrase when prompted

  6. In AI Workbench, enter the path to the corresponding .pub file in the SSH Private Key File field

Password-Protected Keys on Ubuntu and macOS#

On Ubuntu and macOS, use ssh-agent in the standard way.

  1. Start the agent if it is not running: eval "$(ssh-agent -s)"

  2. Add the key: ssh-add ~/.ssh/<your-private-key>

  3. Enter the passphrase when prompted

  4. In AI Workbench, enter the path to the corresponding .pub file in the SSH Private Key File field