Is this page helpful?

NVIDIA Sync#

Overview#

NVIDIA Sync is a system tray utility that runs on Windows, Mac, and Ubuntu to simplify launching applications and containers on remote Linux systems. The primary example is working with a DGX Spark, GB10, or DGX Station device on your local network. However, the approach is general and works with a broad range of devices, such as a cloud instance on a public network.

NVIDIA Sync needs only the hostname on your network plus your username and password for the device. After that, you can one-click launch local Integrated Development Environments (IDEs) and applications, such as VS Code, Cursor, and AI Workbench directly from the NVIDIA Sync UI.

You can add custom applications and scripts to run on the remote device. NVIDIA Sync has a Custom Application feature that handles connection details, such as port forwarding, so that you can run web applications or containers on the remote device and still access them as if they were running locally.

In addition, NVIDIA Sync has a Tailscale Integration that creates a secure tunnel to a device on your private network. This lets you access your DGX devices for compute and inference without being on that network, such as when you are at a coffee shop or a job site.

Terminology#

  • Adding a device — Manually configuring SSH details so that NVIDIA Sync can access the device and manage key-based access. This requires the device password.

  • Importing a device — Selecting an existing SSH alias from your local main SSH configuration file for NVIDIA Sync to use. This bypasses manual configuration in the Sync application.

  • Connecting a device — Activating the SSH connection to an added or imported device through NVIDIA Sync so that you can launch applications on it.

  • Adding a Tailscale device — Enabling the Tailscale integration and following the steps to add an added or imported device to the same tailnet as your NVIDIA Sync application.

  • Direct connection — Connecting to a device on the same network as your laptop without using the Tailscale integration.

  • Tailscale connection — Connecting to a device using the Tailscale feature.

General Use Pattern#

The general use pattern for NVIDIA Sync is:

  1. Add or import a remote device to NVIDIA Sync.

  2. Connect to the device through NVIDIA Sync.

  3. One-click launch an IDE or application on the device.

  4. Add a custom application to the device and launch it.

  5. Use NVIDIA Sync to stop applications running on the device.

  6. Disconnect from the device through NVIDIA Sync.

Limitations#

  • NVIDIA Sync does not support connections through jump or bastion servers.

  • You can add multiple remote devices to NVIDIA Sync, but Sync only supports working on one device at a time.

Installation and Onboarding Flow#

Installation#

For Windows:

  1. Download the Windows installer.

  2. Double-click the installer .exe file.

  3. Accept the license agreement.

  4. Complete the installation.

For Mac:

  1. Download the Mac application.

  2. Drag and drop the application into your Applications folder.

  3. Open NVIDIA Sync from the Applications folder.

For Ubuntu:

  1. Configure the package repository:

    curl -fsSL https://workbench.download.nvidia.com/stable/linux/gpgkey | sudo tee -a /etc/apt/trusted.gpg.d/ai-workbench-desktop-key.asc
echo "deb https://workbench.download.nvidia.com/stable/linux/debian default proprietary" | sudo tee -a /etc/apt/sources.list

  2. Update package lists:

    sudo apt update

  3. Install NVIDIA Sync:

    sudo apt install nvidia-sync

Onboarding Flow#

The application opens after installation completes. If it does not, double-click the desktop icon to open it.

The onboarding flow has five steps:

  1. Read and agree to the EULA.

  2. Select local IDEs you want NVIDIA Sync to launch and manage on your remote devices.

  3. Add your first remote Linux device to NVIDIA Sync.

  4. Connect to that device through NVIDIA Sync.

  5. Launch an application on the device.

Working with Direct Connections#

Overview and Prerequisites#

NVIDIA Sync allows you to add any remote Linux device for which you have SSH access directly over the network. This type of direct connection requires your laptop to be on the same network as the device and for Sync to have the required SSH information (for example, IP address, hostname, username and password, or key).

Direct connections will work only if your laptop is on the same network as the remote device, or the remote device is accessible from the internet (for example, a cloud VM). A typical example is working with a device on a LAN, such as a home or corporate network.

If you are not on the same network as your remote device, you may be able to connect using the Tailscale integration. For more information, see the Working with Tailscale Connections section below.

Adding a Device for a Direct Connection#

There are a few different scenarios for adding a device for a direct connection.

Adding a DGX Spark or a GB10 Device with Device Name#

After initial setup, the system broadcasts its hostname using multicast DNS (mDNS) so you can find and add it without the IP address.

If you are on a network that does not support mDNS, you will need the device IP address on the network.

  1. Open the Settings window by clicking the gear icon in the top left corner.

  2. Select the Devices tab, then click Add Device.

  3. The device discovery modal opens to show the device name.

  4. Select the device and fill in the fields in the configuration modal:

    • Name: Enter a name to identify this device.

    • Hostname or IP: Pre-populated with the device name you selected.

    • Port number: The default is 22.

    • Username: Enter your username for accessing the device.

    • Password: Enter your password for accessing the device.

  5. Confirm the details by clicking Add.

If the details are correct, the device will be added and you can then directly connect to it using Sync.

Adding with Known IP Address#

If the device is not broadcasting its name with mDNS or you are on a network that suppresses mDNS, you need to use a known IP address.

  1. Open the NVIDIA Sync app and select Add Device.

  2. Select Add a device manually at the bottom of the broadcast modal.

  3. Fill in the fields in the configuration modal:

    • Name: Enter a name to identify this device.

    • Hostname or IP: Enter the IP address for the device on the network.

    • Port number: The default is 22.

    • Username: Enter your username for accessing the device.

    • Password: Enter your password for accessing the device.

  4. Confirm the details by clicking Add.

If the details are correct, the device will be added and you can then directly connect to it using Sync.

Importing an Existing SSH Configuration#

NVIDIA Sync can also add a device that is already aliased in your main SSH configuration file. On Mac and Linux this file is ~/.ssh/config, and on Windows it is C:\Users\<user-name>\.ssh\config.

Entries from that file are used as-is and must use key-based access to the remote device. Ensure the SSH alias is valid and working before importing.

  1. Open the NVIDIA Sync app and select Add Device.

  2. Select Add a device manually at the bottom of the broadcast modal.

  3. Entries from the main SSH configuration file are shown.

  4. Select the appropriate alias.

  5. Confirm the import by clicking Add.

Using a Directly Connected Device#

Once you have added a device to NVIDIA Sync, you can connect to it as long as you are on the appropriate network. To connect from anywhere, configure the Tailscale integration. For more information, see Working with Tailscale Connections.

Connecting and Disconnecting#

To connect to a device that you have added:

  1. Ensure you are on the same network as the device.

  2. Open the NVIDIA Sync app.

  3. Select the device name in the drop-down menu in the top left corner.

  4. Click Connect.

To disconnect from a currently connected device:

  1. Open the NVIDIA Sync pop-up window.

  2. Click Disconnect.

Working with Tailscale Connections#

Overview and Prerequisites#

There are situations where you would like to access your device even though you are not on the same network. This is useful if you have a DGX Spark on your home network but want to use it while working away from home.

NVIDIA Sync supports this kind of connection using a Tailscale integration. Tailscale is an open source client along with a service platform that provides a peer-to-peer mesh called a “tailnet.” Tailscale works with NVIDIA Sync to access your device from relatively anywhere. Learn more about Tailscale in the Tailscale documentation.

NVIDIA Sync has directly integrated the Tailscale service so that Sync itself is a node that can be connected to the other devices in your tailnet. This means that you do not need to install the Tailscale client on your laptop. Rather, you can enable the feature in Sync.

Enabling the Tailscale Integration#

To enable the Tailscale integration:

  1. Open Settings and select the Tailscale tab.

  2. Click Enable Tailscale.

  3. A browser window opens. Sign in to Tailscale and click Connect.

  4. Wait until you see Login Successful in the browser window.

  5. Close the browser and return to NVIDIA Sync.

If the browser does not open, use the option in NVIDIA Sync to resend the request. If the enable flow fails, check the error message in NVIDIA Sync for details.

Adding a Device to Tailscale#

To add a device to your Tailscale network using NVIDIA Sync, follow these steps to generate and use an authentication key. This process securely links your device to your tailnet and ensures it can communicate with other devices through Tailscale.

  1. Open the NVIDIA Sync app and go to Settings.

  2. Select the Tailscale tab.

  3. Click Add a Device.

  4. Select the device to add from the drop-down menu at the top of the modal.

  5. Use the link in the modal to go to the Tailscale authentication key settings.

  6. Create an authentication key using the default settings.

  7. Copy and paste it into the modal and select Add Device.

  8. A terminal opens connected to the device. Follow the instructions to ensure that the Tailscale client is installed and properly authenticated on the device.

Connecting to a Tailscale Device#

NVIDIA Sync selects the connection type automatically. No user selection is required. The connection indicator in NVIDIA Sync shows which connection type is active.

If the connection drops, NVIDIA Sync enters a reconnecting state. Reconnection typically takes approximately 30 seconds. Click Cancel to stop. If the system tray is hidden and a connection error occurs, the tray may open automatically to display the error.

Switching Networks Automatically#

When you move between networks (for example, from a local network to a remote network), NVIDIA Sync switches from direct to Tailscale connection automatically. The reconnecting state is displayed briefly, then the connection indicator updates. No action is required. This applies to the NVIDIA Sync managed tunnels and to SSH-enabled applications using SSH aliases (such as VS Code or Cursor).

Managing Tailscale Devices#

You can manage the devices that are connected to your Tailscale network directly from within NVIDIA Sync using the following tools:

Tailscale Devices screen: View all devices added to Tailscale from the Tailscale settings screen in NVIDIA Sync.

Reauthenticating: If a device’s Tailscale authorization expires, reauthenticate it from the Tailscale Settings screen.

Removing devices from Tailscale: Removing the device from Tailscale deletes credentials and disconnects the device from your tailnet. Select Remove device from the action menu and follow the terminal prompts. Removing a device from Tailscale requires a direct connection. You cannot do this over a Tailscale connection.

Note

When you remove or deauthenticate a device from Tailscale, its keys are expired (they appear as expired in the Tailscale administration console). The device is not removed from the console.

Troubleshooting Connection Failures#

If you see a message saying “Unable to Connect,” use the following troubleshooting steps:

  1. Verify your network connection.

  2. In the Tailscale administration console, confirm the device is enrolled and not expired.

  3. Expand the source error for more details.

If the tray is hidden when an error occurs, it might open automatically to display the message.

Disabling the Tailscale Integration#

To disable the Tailscale integration, follow these steps:

  1. Open Settings and select the Tailscale tab.

  2. Use the three-dot action menu and select Disable Tailscale.

Warning

Tailscale devices remain visible in your Tailscale administration console. Remove them before disabling the Tailscale integration. Disconnecting clears NVIDIA Sync’s Tailscale credentials but does not remove the devices.

FAQ / Common Issues#

My session timed out during setup

Complete the Tailscale login in the browser before the session expires. If it expires, start the enable flow again from Settings → Tailscale.

I accidentally closed the browser

Resend the request from NVIDIA Sync. The enable flow can be retried.

My device shows as expired in Tailscale

Reauthenticate the device from the Enrolled Devices screen, or generate a new authentication key and re-enroll.

Unenroll command is hanging

Unenroll requires a direct connection. Connect to the device over your local network, then unenroll. You cannot unenroll over a Tailscale connection.

Configuring and Using Applications#

Overview#

NVIDIA Sync streamlines the process of launching applications and containers on remote systems, ensuring reliable connectivity across both private and public networks.

Once a remote device has been added or imported to NVIDIA Sync, you can one-click launch applications while Sync handles the connection details.

NVIDIA Sync divides applications between default and custom:

  • Default applications — Fixed list of commonly used IDEs and development platforms, such as Cursor, VS Code, VS Code Insiders Edition, and NVIDIA AI Workbench.

  • Custom applications — All other applications; these require manual configuration through the Custom tab in the Settings window.

In addition, DGX devices like DGX Spark and GB10 include the DGX Dashboard. NVIDIA Sync works with the DGX Dashboard without any configuration on your part. The DGX Dashboard automatically appears if it is available on the device.

Launching an SSH Terminal#

NVIDIA Sync always allows you to launch an SSH terminal on the remote without any setup on your part. The terminal opens into the default shell on the remote with the user set to the user you have configured for that connection. The session opens in the working directory set, defaulting to your home directory.

Default Applications#

NVIDIA Sync detects the following applications when they are installed locally and prompts you to enable them during onboarding:

Launching a Default Application#

To launch a default application, follow these steps:

  1. Open the NVIDIA Sync application.

  2. Connect to an existing device.

  3. Select the application from the pop-up menu.

  4. Wait for the application to launch.

Custom Scripts and Applications#

Overview and Prerequisites#

Custom scripts allow you to write and run bash scripts on a connected device and access web-based services through an SSH tunnel to your local computer.

This allows you to define, launch, and connect to webapps, containers, and servers on the remote device through a port that you define in the NVIDIA Sync app. You can also use this to run background tasks like downloading data and models.

Scripts are created on a per-device basis and they run in the user’s home directory on the remote device. When you create or edit a custom script, NVIDIA Sync automatically saves or updates it on the remote device.

Once you have added a script to a device, it shows in the NVIDIA Sync app when it is connected to the device. You run it by selecting the associated port in the application.

NVIDIA Sync runs the script as your user on the remote device using a bash command.

The only prerequisite for using this feature is that bash is installed on the remote device.

Adding and Editing a Custom Script to a Remote Device#

Custom scripts are added on the Custom tab of the Settings window. To add a script to the device, you must first add or import the device to NVIDIA Sync and then connect to it through Sync.

  1. Connect to an existing device.

  2. Verify that bash is installed.

  3. Open Settings → Custom tab.

  4. Click Add New, or click Edit on an existing script.

  5. Enter an identifying name and desired port in the Add Custom modal.

  6. Write your bash script in the Launch Script code editor.

  7. Configure the launch settings.

  8. Click Add or Update.

You can also add a script from the pop-up menu by clicking Add New in the Custom section.

Selecting a Port for the Script#

You must assign a port for the script even if the script will run in the background on the remote device. The assigned port is bound between the remote device and your local device, and the local port is bound until you stop the custom application or disconnect NVIDIA Sync.

For example, assigning port 8000 for a custom application binds local port 8000 to remote port 8000, and local port 8000 is bound until it is released.

Configuring Launch Settings#

The Add Custom modal lets you configure how the custom script launches a user interface.

  • Auto open in browser at the following path — Opens your default web browser after the application starts. It opens to http://localhost:<port>/<URL Path>. Leaving the URL path unset will load the root of the web application.

  • Launch in Terminal — Opens an SSH terminal to the remote with the script running in it. This is useful if you need to monitor the status of the application or script being launched or run. The terminal stays connected even if the script fails.

Leaving these options blank runs the script in the background without opening any interface.

Writing the Bash Script#

The Add Custom modal has a simple file editor that lets you write, edit, and paste text that is saved locally in the application as well as on the remote device. You can write standard bash scripts for Python, Docker, and similar tools.

You should ensure that there is a new line at the end of the script. However, you do not need to include the interpreter line (for example, #!/bin/bash) at the top of the file.

NVIDIA Sync runs the script as your user on the remote device with a bash command.

Running a Custom Script#

  1. Connect to a device.

  2. In the main window, find your script under the Custom section.

  3. Click the script to start it.

If Launch in Terminal is enabled, an OS terminal window opens with the script running interactively. Otherwise, the script runs in the background.

If Auto open in browser is enabled, NVIDIA Sync waits for the service to become available (up to 30 seconds) and then opens the URL in your default browser.

Stopping a Custom Script#

Click the x on the running script in the pop-up window to close it. This stops the service and releases the port.

Working with Ports and Tunnels#

The following information can be useful when assigning ports to custom scripts or resolving connection issues.

Login shell: Opening a terminal through NVIDIA Sync uses a bash login shell, so the $PATH (including /usr/local/cuda/bin) matches a manual SSH session.

Custom port: Set and persist a non-default SSH port for each device when adding the device.

Port conflicts: If a port is already in use, NVIDIA Sync displays a clear error instead of failing silently or routing to the wrong application. If a port-in-use error appears, release the port and retry.

Common Issues#

My PATH looks different in an NVIDIA Sync terminal compared to SSH

NVIDIA Sync uses a bash login shell, so $PATH (including /usr/local/cuda/bin) should match a manual SSH session.

Port-in-use error

Release the port or stop the application using it, then retry.

NVIDIA Sync is not discovering my device

Confirm the device is broadcasting _ssh._tcp on the network. Check that mDNS is working and the device is reachable.