Manually Connect a Remote#


Screenshot of the add remote location modal for AI Workbench showing the different fields that need to be entered.

Overview of Remote Locations#

A remote location is a machine that has AI Workbench installed and that you can access over a network via SSH. Generally speaking, you use a remote location when you want more compute power and GPUs than your laptop has.

Requirements for a remote location#

  • The remote location must be an Ubuntu 22.04 or 24.04 system

  • It must have AI Workbench installed

  • It must be accessible by SSH using a private-public key pair from your laptop

  • The SSH user must have sudo privileges on the remote system

Using a remote location is simple#

  • You install AI Workbench on the remote location

  • You connect the remote location to your local Workbench by entering the SSH information

  • You click a button to open the remote location in AI Workbench

  • You create or clone a project and start working

Manually connect a remote location#

Prerequisites#

  • A remote Ubuntu system with Workbench installed

  • An private-public SSH key pair with the private key held locally and the public key added to the remote system

  • A non-root user with sudo privileges on the remote system

  • Information from the table below

You need the following information to create the connection.

Field

Description

Location Name

A unique name for the remote location.

Description

A short description of the remote location.

Hostname or IP Address

The remote computer’s IP address or hostname.

SSH Port

The default is port 22 unless the remote system has been configured otherwise.

SSH Username

The username for the non-root user with sudo privileges on the remote system.

SSH Private Key File

The absolute path to the private key on your laptop, typically in ~/.ssh.

SSH Public Key File

(only if using a password-protected SSH key) The absolute path to the public key on your laptop, typically in ~/.ssh. Requires use of ssh-agent.

Workbench Directory

The absolute path to the .nvwb directory on the remote system. Use the default unless you purposefully installed Workbench in a different directory.

Create the connection#

  • Click Add Remote Location in the Desktop App and enter the required connection details

  • Confirm the connection details and click Add Location

Use a Password-Protected SSH Key (Optional)#

If required by company policy or security best practices, you can use a password-protected SSH key to authenticate with a remote computer. AI Workbench supports this through SSH Agent.

To use a password-protected SSH key, first generate the key, then start SSH Agent, and finally add the key to SSH Agent.

Start SSH Agent#

Windows

  1. Open Services from the Start menu

  2. Locate OpenSSH Authentication Agent in the list

  3. Open the Properties window (via Actions menu or right-click)

  4. Set Startup type to Automatic and click Apply

  5. Click Start to run the service immediately

  6. Click OK to close the window

macOS

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

Ubuntu

  1. Verify the service is available using:

    1``systemctl list-unit-files --type service -all``

  2. Start SSH Agent:

    1``systemctl start ssh-agent``

Add a Key to SSH Agent#

  1. Ensure SSH Agent is running using the steps above

  2. Open a terminal window

    Note

    On Windows, use Command Prompt or PowerShell, not WSL.

  3. Add your private key to SSH Agent:

    1ssh-add <path to private key>

If the key is password-protected, you will be prompted to enter the passphrase.

Important

When specifying connection information for your remote location, select the public key (.pub file), not the private key.

FAQs#

How does the SSH connection work?#

When you connect to a remote location, AI Workbench automatically establishes two SSH tunnels that securely map ports from the remote system to your local machine.

One tunnel is dedicated to the AI Workbench service, while the other manages the reverse proxy to provide access from localhost.

By default, AI Workbench assigns ports starting at 10000 and 10001 for the proxy and service, respectively. These details are stored in the .nvwb/contexts.json file.

How do I create a private-public key pair for remote locations?#

Creating the key pair is straight forward. Typically the difficulty is getting the public key onto the remote system.

The general steps for Ubuntu and macOS are below. If you get stuck, use an LLM to help with the details.

Prerequisites

  • Password based SSH access to the remote system

  • The IP address or hostname of the remote system, <remote_host>

  • The username for the non-root user with sudo privileges on the remote system, <user-name>

Steps

  • Create a private-public key pair locally using ssh-keygen

    • Run: ssh-keygen -f "$HOME/.ssh/<key-name>

    • Set permissions on the private by running: chmod 400 $HOME/.ssh/<key-name>

  • Add the public key to the $HOME/.ssh/authorized_keys file on the remote system

    • Run: ssh-copy-id -i $HOME/.ssh/<key-name>.pub <user-name>@<remote_host>

    • This assumes ssh-copy-id is installed in the environment, and you have password based SSH access to the remote system

Note

The Unix based steps will work for Windows if you do them from a WSL distribution like NVIDIA-Workbench.

Can I use a password-protected SSH key for remote locations in Workbench?#

Yes. You can use a password-protected SSH key, but you have to do it by using ssh-agent. See Use a Password-Protected SSH Key (Optional) for details.

How do I setup up and use ssh-agent with Workbench?#

You can

Can I use the AI Workbench CLI to create a remote location?#

Yes. You can use the AI Workbench CLI to create a remote location.