Connect to a Remote Location

A remote computer that has NVIDIA AI Workbench installed, and where you store and run your projects, is called a remote location. For more information, see AI Workbench Locations.

After you install AI Workbench on a remote computer, you have to connect to the remote computer from your local computer one time. After that, the remote computer appears as a location whenever you open AI Workbench locally.

AI Workbench uses SSH to securely connect to remote locations.

Use this documentation to perform the following tasks:

Generate and Store Your SSH Key
Determine Connection Information
Connect to a Remote Location
(Optional) Use a Password-protected SSH Key
SSH Directly Into a Location
SSH Details

Prerequisites

Before you can connect to a remote location, you must have the following:

AI Workbench must be installed on the remote computer. Currently, Ubuntu is the only supported OS for remote locations. For instructions, see Install AI Workbench Remotely on Ubuntu.
SSH access to the remote computer as a non-root user with sudo privileges.

Generate and Store Your SSH Key

Use the following procedure to generate and store an SSH key.

Important

If you want to use a password-protected SSH key, complete this procedure, and then see (Optional) Use a Password-protected SSH Key.

Generate an ssh key and add the public key to the remote instance’s .ssh/authorized_keys file. Open a command terminal on your local computer and run the following code that corresponds to your operating system. For details, see the OpenBSD manual page for ssh-keygen
Note
Make these changes first:
- Change local-user to the username on your local computer.
- Change remote-user to the username on your remote computer.
- Change 10.123.4.56 to the IP address of your remote computer.
- If you want to use a password-protected SSH key, change -N '""' to -N '<the password for your SSH key>'
Windows Powershell

MacOS Terminal

Ubuntu Local Computer
Copy

Copied!

ssh-keygen -f "C:\Users\local-user\.ssh\id_rsa" -t rsa -N '""' type$env:USERPROFILE\.ssh\id_rsa.pub | ssh remote-user@10.123.4.56 "cat >> .ssh/authorized_keys"
Copy

Copied!

ssh-keygen -f "/Users/local-user/.ssh/id_rsa" -t rsa -N "" ssh-copy-id remote-user@10.123.4.56
Copy

Copied!

ssh-keygen -f "/home/local-user/.ssh/id_rsa" -t rsa -N "" ssh-copy-id remote-user@10.123.4.56

Determine Connection Information

When you connect to a remote location for the first time, you specify the following information.

Field	Description	CLI
Location Name	Your name for the remote location.	`<location name>`
Description	Your description for the remote location.	`--description`
Hostname or IP Address	The address of the remote computer.	`<hostname>`
SSH Port	The default is port 22.	`--ssh-port`
SSH Username	The username on the remote computer. This is the username you see when you SSH into the machine manually.	`--ssh-username`
SSH Key File	Specify the absolute path to the private key file on your local computer. Typically, this is in the hidden .ssh directory in your home directory. You can use the file dialog to select the file. On Windows, the `SSH key file` file dialog opens in Windows, not WSL. Place your keys in the `.ssh` directory in your user directory. File permissions for your SSH keys might not appear as you expect in WSL, but you can use the SSH keys in both Windows and WSL. If you are using a password-protected SSH key, select the public key that ends in `.pub`.	`--ssh-key-path`
Workbench Directory	The `.nvwb` directory on the remote computer. If you didn’t change the path when you installed AI Workbench on the remote computer, accept the default.	`--context-workbench-dir`

Connect to a Remote Location

After you Generate and Store Your SSH Key, use one of the following procedures to connect to a remote location.

To connect to a remote location from the AI Workbench desktop app

Open the AI Workbench desktop application on your local computer.
Click Add Remote Location, and then specify the connection information for your remote location.
Click Add Location. The remote computer appears as a location in AI Workbench.

To connect to a remote location by using the CLI

Open a command window for the AI Workbench CLI. For more information, see Basic Quickstart (CLI).
Use the following command. You can specify all flags, or run the command with no flags to activate the interactive form.
Copy

Copied!
```
            
            nvwb create context <location name> <hostname>
        
```
Specify the connection information for your remote location.

(Optional) Use a Password-protected SSH Key

In some cases, you might need to use a password-protected SSH key to authenticate to a remote computer, such as when your company policy requires it. AI Workbench supports password-protected SSH keys through SSH Agent. To use a password-protected SSH key with AI Workbench, you must Generate and Store Your SSH Key, start SSH Agent, and add your key to SSH Agent, as explained following.

To start SSH Agent

Windows
MacOS
Ubuntu Local Computer

Use the start menu to search for and open Services.
In the Services list, locate and select OpenSSH Authentication Agent.
Use the Actions menu, the menu bar, or the right-click menu to open the Properties window.
For Startup type, choose Automatic and then click Apply. From now on, the SSH Agent service starts when you log in to your computer.
Click the Start to start the service now.
Click OK to close the properties window.

The ssh-agent service starts automatically when you attempt to add a key or use the service.

Run the command systemctl list-unit-files --type service -all to verify the ssh-agent service is available.
Run the command systemctl start ssh-agent to start the ssh-agent service.

To add a key to SSH Agent

Make sure the SSH Agent is running by using the previous instructions.
Open a terminal window.

Note

On Windows, use a command prompt such as Powershell or Command Prompt. Don’t use WSL.
Run the following command. Keys are typically stored in ~/.ssh/ or C:\Users\<Username>\.ssh\. If the key is password protected, you are prompted for the password.
Copy

Copied!
```
            
            ssh-add <path to private key>
        
```

Important

When you specify connection information for your remote location, select the public key that ends in .pub.

SSH Directly Into a Location

AI Workbench offers two ways to SSH directly into a remote location. If you are using the CLI, and you have already activated a location (context), you can use the command nvwb attach --host to SSH into the remote location.

When you create a remote location, AI Workbench updates your ~/.ssh/config file to create an alias automatically. Therefore you can also use the command ssh LOCATION_NAME to SSH into the computer location.

Note

On Windows, you must run these commands from WSL. For more information, see Basic Quickstart (CLI).

SSH Details

When you connect to a remote location, AI Workbench automatically opens two SSH tunnels that map ports from the remote system to your local system. One tunnel is for the service, and the other tunnel is for the reverse proxy. This allows you to securely access the remote AI Workbench service and reverse proxy from localhost. By default, AI Workbench assigns ports starting at 10000 and 10001 for the local location’s proxy and service, respectively. This information is saved in the contexts.json file.

On your local system, you’ll need to have the SSH key file and it should be located in the ~/.ssh directory. You should set the permissions for the SSH key file to 400.

If you’re using Windows, AI Workbench maps your .ssh directory on Windows to /home/workbench/.ssh. This means that the permissions may not appear as you expect, but you can use your SSH keys normally in the AI Workbench application.