Applications#

Overview#

NVIDIA Sync streamlines configuring and launching applications on remote systems.

  • You can launch a default shell on the remote from within the task bar utility

  • There are default applications that NVIDIA Sync detects on your laptop when you first install it

  • You can also set up custom apps using bash launch and managements scripts

  • NVIDIA Sync handles the SSH tunnel and port forwarding

Applications are divided between default and custom.

  • Default applications — Fixed list of commonly used IDEs and harnesses like VS Code, Cursor, and Codex.

  • Custom applications — Anything you configure yourself with a script in the Settings > Custom tab.

Default Applications#

During onboarding, NVIDIA Sync detects certain installed applications and prompts you to enable them for launch.

You can launch a default application from the taskbar utility.

  • Default applications are available on any remote device that you’ve added to NVIDIA Sync.

  • Each application has an icon in the task bar utility.

  • Just click the icon to launch the application on the remote.

Codex needs its desktop app on your laptop and its CLI on the remote device.

  • Install Codex desktop version 26.818.22352 or newer on your laptop.

  • Add and connect to a remote Linux device in Sync.

  • The remote device needs internet access and curl for the setup described below. You can also use an existing Codex CLI installation.

The first launch can open a terminal to set up the remote CLI.

  1. Select the Codex icon for the connected device in the Sync pop-up window.

  2. If Sync opens a setup terminal, read the prompt and enter y to allow the install. Sync downloads and runs OpenAI’s installer as your remote user. Wait for Installation completed, then press Enter to close the setup session.

  3. Open an SSH terminal on the remote device through Sync. Run codex and follow the sign-in prompts if needed.

  4. Select the Codex icon in Sync again. Finish the SSH connection setup in Codex and open your remote project.

If you decline the install, the setup session leaves the remote device unchanged. For manual setup and sign-in help, see OpenAI’s Codex CLI guide and SSH connection guide.

If Sync asks for setup again, check the remote command.

Open an SSH terminal on that device and run codex --version. The command must work on the remote user’s login-shell PATH. If installation failed, read the setup terminal’s output before trying again.

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.

Remote Files and Working Directory#

Sync stores custom app files under your user account on the remote device. The default directory is ~/.config/NVIDIA/Sync/, where ~ is the home directory of the user you connect as. If that user’s remote environment sets XDG_CONFIG_HOME, Sync uses $XDG_CONFIG_HOME/NVIDIA/Sync/ instead.

The following paths are relative to that directory:

File or Directory

Purpose

config/custom.json

Custom app names, ports, and launch settings.

bin/scripts/port-<port>.bash

The launch script for the app on that port.

bin/nvsync-managed-port.sh

The helper Sync uses to run and stop custom apps.

logs/scripts/

Background output and error logs named port-<port>.out and port-<port>.err.

session/ports/port-<port>.pgid

Records Sync uses to track and stop the app’s managed processes.

For example, an app on port 8000 has its script at ~/.config/NVIDIA/Sync/bin/scripts/port-8000.bash. When you create or edit the app through Sync, it saves or updates the remote app definition and launch script.

The script runs from your home directory, not the directory where the script is stored. If your app needs a different working directory, use cd in the launch script before starting it. The background logs can help you check why an app failed to start.

Your launch script determines where the application, models, and data are stored. The paths above hold Sync’s settings, scripts, logs, and process records. Relative file paths in your script refer to your home directory unless the script changes directories. Docker images and volumes use Docker’s storage.

Model Launcher keeps its downloads, task logs, and model setup records under model-launcher/ in the same Sync directory. See Remote Files and Storage for those locations. Its managed OpenCode app uses the custom app files above, while the OpenCode workspace is separate at ~/opencode. See Using OpenCode.

Resetting Remote Sync Files#

To start over with Sync’s remote app setup, stop running custom apps and models, then delete ~/.config/NVIDIA/Sync/ on the remote device. If you use XDG_CONFIG_HOME, delete the Sync directory at the location described above instead. This removes your custom app definitions, scripts, and logs, along with Model Launcher’s downloads and settings. Reconnect to the device, add your custom apps again, and set up any models you want to use.

Files elsewhere, including your ~/opencode workspace and Docker images and volumes, remain. Deleting the directory does not stop running processes.

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

See The Device Does Not Appear in Discovery for discovery checks and how to add the device manually.