nvidia-holoscan/holoscan-sensor-bridge/hsb-setup

Holoscan Sensor Bridge demo bring-up

Use this skill when the user wants to bring up the Holoscan Sensor Bridge demo environment end to end.

This workflow has side effects. Never run it automatically. Only run it when the user explicitly invokes it.

Before you start — required gates (do these first, in order)

Gate 1 — Read environment variables. Before doing anything else, check these variables and print their resolved values to the user:

SSH_TARGET      Remote devkit login (e.g. nvidia@192.168.1.50). Ask the user if not set.
REMOTE_ROOT     Remote working directory (e.g. /home/nvidia). Ask the user if not set.
REMOTE_SUDO     sudo / sudo -n / "" — default to "sudo" if not set.
REMOTE_SSH_OPTS Additional SSH options (optional).
HSB_PLATFORM    Platform hint — may be empty; will detect from hardware.
HSB_REPO        Custom repo URL — defaults to https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

SSH_TARGET and REMOTE_ROOT are required. Stop and ask the user for them if either is missing.

Gate 2 — Present the phase plan. Before taking any action, show the user this exact plan and wait for acknowledgement:

HSB Setup — Phase Plan
  Phase 0: Token-budget preflight
  Phase 1: Confirm platform, set up SSH, clone repo, study user guide
  Phase 2: Host prerequisite checks and network setup
  Phase 3: Native CLI build (AGX Thor only — skipped for other platforms)
  Phase 4: Build demo container, run it, ping 192.168.0.2, verify FPGA version
  Phase 5: Issues report (with option to save)
  Phase 6: Stop apps, exit container, hand control back to user

Gate 3 — Token-budget preflight (Phase 0). Run this before any SSH connection or devkit change. See ## Token-budget preflight section for the full procedure. Do not proceed to Phase 1 until the budget check passes.

Instructions

Invoke this skill by typing /hsb-setup [PLATFORM] [OPTIONS]. The skill walks through each phase interactively, prompting for confirmation before making changes.

What this skill must do

1. Run the mandatory token-budget preflight before any remote command or devkit configuration change. Estimate the tokens needed to complete all setup phases, check the user's remaining subscription-plan usage with the best available Claude Code/account usage mechanism, display the estimate and result to the user, and stop if the available budget is insufficient or cannot be verified.
2. prompt the user to confirm that the devkit is connected to the holoscan sensor bridge and everything is powered up and there is an active network connection to the outside world and that the devkit was installed with the proper OS version. if all profile parameters are known look into the repo user guide and draw a diagram of the devkit to sensor for the user to confirm that this is the setup they have.
3. Once the user confirms the setup is ready, build the ssh connection to the devkit if the user is running the claude skill from an external computer. you can skip this step if claude installed directly on the devkit.
4. Verify the host devkit platform by running cat /sys/class/dmi/id/product_name on the devkit and comparing the result to the HSB_PLATFORM environment variable using the product-name-to-platform mapping (see "Host platform auto-detection" section). If the command returns a recognized non-empty platform name that differs from HSB_PLATFORM, or if HSB_PLATFORM is empty, update HSB_PLATFORM to match the detected platform and alert the user about the change. If the command returns empty or fails and HSB_PLATFORM is already set, keep the existing value.
5. Clone or refresh the GitHub repository from the latest main branch. By default this is the public nvidia-holoscan/holoscan-sensor-bridge repo, but the user can override it with a custom repo URL via the HSB_REPO environment variable or the --repo <URL> command-line flag. if the repo is an ssh repo, alert the user if no ssh key is set and provide instructions how to set up the ssh key.
6. Ask the user which devkit/platform they want to use if it is not already clear.
7. under the cloned repo root dir, study and understand the user guide at docs/user_guide to learn how to set up host environment for each devkit and OS, demo container, running applications inside and outside the container (where applicable) and flashing the FPGA.
8. Map that platform to the correct host setup and container build mode and make sure host set up is configured properly per user guide instructions, fix and add any missing configuration or prompt the user with instruction how to fix.
9. Build the demo container.
10. Run the demo container.
11. Verify connectivity to the board at 192.168.0.2. if the connection to the board fails, prompt the user for a possiblity of a different ip address.
12. Verify the FPGA version reading register 0x80. if the FPGA version on the sensor does not match the hsb host software that is on the devkit, suggest the user to use the hsb-flash-skill to flash the board to the proper FPGA version.
13. Report progress in phases, explain failures clearly, and attempt safe fixes before giving up.
14. For every issue encountered, create a report that specifies what was the issue and how you overcame it.
15. Allow the user an option to export the final report to an md file.
16. once you are done setup, stop any running apps and exit the container giving up control on the devkit to the user at repo home directory on terminal window.

Supported platforms and build mapping

Use the following mapping unless the repository or current docs in the working tree clearly say otherwise:

• IGX Orin with dGPU OS/configuration → build with sh docker/build.sh --dgpu
• IGX Orin iGPU → build with sh docker/build.sh --igpu
• AGX Orin → build with sh docker/build.sh --igpu
• AGX Thor → build with sh docker/build.sh --igpu
• DGX Spark → build with sh docker/build.sh --igpu

If the user says only “IGX Orin”, explicitly ask whether it is iGPU or dGPU OS/configuration.

Host platform auto-detection

During Phase 1 (after SSH is established or when running locally), verify the actual devkit hardware by reading the DMI product name and comparing it to the HSB_PLATFORM environment variable.

Product-name-to-platform mapping

The following table maps known /sys/class/dmi/id/product_name values to supported HSB_PLATFORM values. Match using case-insensitive substring search — the product name may contain additional text (e.g., "Developer Kit", revision numbers).

If the product name does not match any known pattern, treat it as unrecognized and fall through to the manual platform question in step 5.

Detection and reconciliation logic

Run the following on the devkit (inside the Phase 1 SSH heredoc or locally):

DETECTED_PRODUCT=""
if [ -f /sys/class/dmi/id/product_name ]; then
  DETECTED_PRODUCT=$(cat /sys/class/dmi/id/product_name 2>/dev/null | tr -d '\n')
fi
 
DETECTED_PLATFORM=""
if echo "$DETECTED_PRODUCT" | grep -qi "IGX Orin"; then
  DETECTED_PLATFORM="IGX Orin"
elif echo "$DETECTED_PRODUCT" | grep -qi "AGX Orin"; then
  DETECTED_PLATFORM="AGX Orin"
elif echo "$DETECTED_PRODUCT" | grep -qi "AGX Thor"; then
  DETECTED_PLATFORM="AGX Thor"
elif echo "$DETECTED_PRODUCT" | grep -qi "DGX Spark"; then
  DETECTED_PLATFORM="DGX Spark"
fi
 
echo "DETECTED_PRODUCT=$DETECTED_PRODUCT"
echo "DETECTED_PLATFORM=$DETECTED_PLATFORM"
echo "HSB_PLATFORM=${HSB_PLATFORM:-}"

After collecting the output, apply the following reconciliation rules:

1. `DETECTED_PLATFORM` is non-empty and `HSB_PLATFORM` is empty → set HSB_PLATFORM to DETECTED_PLATFORM. Alert the user:

`` Platform auto-detected from hardware: <DETECTED_PLATFORM> (product_name: <DETECTED_PRODUCT>). HSB_PLATFORM was not set — updating to "<DETECTED_PLATFORM>". ``

1. `DETECTED_PLATFORM` is non-empty and differs from `HSB_PLATFORM` → override HSB_PLATFORM with DETECTED_PLATFORM. Alert the user:

`` WARNING: Hardware reports "<DETECTED_PLATFORM>" (product_name: <DETECTED_PRODUCT>), but HSB_PLATFORM was set to "<HSB_PLATFORM>". Updating HSB_PLATFORM to match the detected hardware: "<DETECTED_PLATFORM>". ``

1. `DETECTED_PLATFORM` is non-empty and matches `HSB_PLATFORM` → no change needed. Confirm:

`` Platform verified: <HSB_PLATFORM> matches hardware (product_name: <DETECTED_PRODUCT>). ``

1. `DETECTED_PLATFORM` is empty (file missing, unreadable, or unrecognized product name) and `HSB_PLATFORM` is set → keep the existing HSB_PLATFORM. Warn:

`` Could not auto-detect platform from hardware (product_name: "<DETECTED_PRODUCT>"). Keeping existing HSB_PLATFORM: "<HSB_PLATFORM>". ``

1. Both `DETECTED_PLATFORM` and `HSB_PLATFORM` are empty → fall through to the manual platform question in step 5.

After reconciliation, persist the updated HSB_PLATFORM in the remote session state file so subsequent phases use the correct value.

Linux/Windows-friendly wrapper variables

When this skill is used from Linux/Windows with a local Claude Code session that shells out to SSH, prefer these environment variables when present:

• SSH_TARGET for the remote login target such as nvidia@agx-thor-host
• REMOTE_ROOT for the remote working directory where the repo should live
• REMOTE_SUDO for privileged commands. Accept sudo, sudo -n, or empty string
• REMOTE_SSH_OPTS for additional SSH options
• HSB_PLATFORM as an optional platform hint
• HSB_REPO for a custom GitHub repository URL to clone (e.g. https://github.com/myorg/my-hsb-fork.git). If not set, defaults to https://github.com/nvidia-holoscan/holoscan-sensor-bridge.git

If these are set, notify the user of these settings and use them without re-asking unless the user explicitly overrides them.

Before Phase 1, print the resolved remote execution settings you will use, with secrets redacted if needed.

Mandatory interaction pattern

Present the phase plan from Gate 2 above before making any changes. Skip Phase 3 for non-Thor platforms.

Then execute one phase at a time.

After each non-final phase (Phases 0–5):

1. Show a phase summary. The detail level depends on --verbose mode (see "Verbosity mode" section):

• Verbose: full output + detailed status block (phase name, what ran, result, next action).
• Concise (default): bullet-point summary with issues highlighted.

1. Prompt the user with Proceed to Phase <N+1>? [Y/n] while specifing what is phase N+1 and wait for confirmation before continuing (see "Phase gate" section).

If something fails, do not just dump raw logs. Summarize:

• the exact command that failed
• the likely root cause
• what safe repair you will try next
• whether the repair succeeded

Token-budget preflight

Phase 0 - token-budget preflight

This phase is mandatory and must run before any SSH connection, repo clone, package/configuration check, container build, reboot, or devkit setting change.