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

0. 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.
1. 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.
2. 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.
3. 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.
4. 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.
5. Ask the user which devkit/platform they want to use if it is not already clear.
6. 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.
7. 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.
8. Build the demo container.
9. Run the demo container.
10. 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.
11. 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.
12. Report progress in phases, explain failures clearly, and attempt safe fixes before giving up.
13. For every issue encountered, create a report that specifies what was the issue and how you overcame it.
14. Allow the user an option to export the final report to an md file.
15. 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).

product_name contains (case-insensitive)	Mapped HSB_PLATFORM	Notes
IGX Orin	IGX Orin	Still need to ask iGPU vs dGPU if not already known
AGX Orin	AGX Orin
AGX Thor	AGX Thor
DGX Spark	DGX Spark

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>".
   

2. 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>".
   

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

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

4. 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>".
   

5. 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.
2. 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.

1. Estimate the full-run token budget for the entire setup workflow, not just the next phase. The values below are conservative heuristics, not measured historical usage. Treat them as initial safety budgets and refine them from actual /hsb-setup run logs once measured token usage is available:

   • Reserve at least 280,000 tokens for a complete setup run on IGX Orin, AGX Orin, or DGX Spark.
   • Reserve at least 340,000 tokens for AGX Thor because native build and SIPL/FuSa checks add more phases and troubleshooting.
   • Add 60,000 tokens when --verbose, custom repo handling, SSH key remediation, reboot recovery, or extra troubleshooting is expected.
   • Use the larger estimate if the platform is not yet known.

2. Check remaining usage using the best available Claude Code/account usage source for the current subscription plan. Prefer machine-readable or product-provided usage data when available. If no reliable usage source is available, ask the user to provide their current remaining usage/quota from the Claude Code account or plan UI.

   When asking the user because usage cannot be self-verified, present the options in this exact order so the safe stop choices appear first:

   1. I can't verify — stop: The user cannot determine remaining usage. Stop before Phase 1.
   2. I have < {estimate} available — stop: The user checked their plan/account UI and confirms less than the estimated budget remains. Stop before Phase 1.
   3. I have ≥ {estimate} available — proceed: The user checked their plan/account UI and confirms at least the estimated budget remains. Proceed to Phase 1.
   4. Type something: Treat as a question or free-form instruction, answer it, then re-prompt with the same ordered options.

   Do not put the proceed option first. The user must intentionally move past the stop choices before selecting proceed.

3. Display the result to the user before continuing:

   Token-budget preflight
   - Estimated tokens required for complete /hsb-setup run: <estimate>
   - Estimate basis: conservative heuristic; refine from actual run logs when available
   - Safety margin included: <margin>
   - Remaining plan usage available: <available or "unverified">
   - Result: PASS / FAIL
   

4. Stop on insufficient or unverifiable budget:

   • If remaining usage is lower than the estimate, stop before Phase 1 and explain that the skill is refusing to start because it may run out of tokens while modifying devkit settings.
   • If remaining usage cannot be verified, stop before Phase 1 and ask the user to start a fresh session, upgrade/refresh usage, or provide verifiable remaining usage.
   • --y must not bypass this preflight.

Platform questions to ask when missing

Ask only the minimum required questions:

1. Which platform are you using?
   • IGX Orin iGPU
   • IGX Orin dGPU
   • AGX Orin
   • AGX Thor
   • DGX Spark
2. Is the HSB board already physically connected and powered on?
3. Are you okay with commands that require sudo for network and Docker setup?

If the user already provided any of these, do not ask again.

Available Scripts

Script	Purpose	Arguments
scripts/hsb_phase_runner.sh	Structured shell execution with timestamped logs per phase	<phase_name> <command>

Use run_script(scripts/hsb_phase_runner.sh, <phase_name>, <command>) to run phase steps with automatic logging.

Phase details

See references/phase-details.md for full step-by-step phase instructions, output style, verbosity behavior, auto-approve mode, phase gate

...