> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/ai-workbench/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/ai-workbench/_mcp/server.

# 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](/ai-workbench/how-to/locations/use-nvidia-sync) instead.

**The remote system must be running Ubuntu 22.04, Ubuntu 24.04, Ubuntu 26.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](/ai-workbench/install/remote-install).

**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](/ai-workbench/how-to/locations/add-existing-location#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)](/ai-workbench/install/remote-install).

**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