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:

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

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):

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

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 rules, and the persistent SSH session model.

Recovery playbook

Try these fixes in order when applicable:

1. Re-run the failing command once if the failure looks transient.
2. Fix missing prerequisites (git-lfs, Docker access, xhost, network route).
3. Refresh repo state and LFS content.
4. Re-run only the failed phase, not the whole workflow.
5. If still blocked, stop with a concise diagnosis and a copy-paste command list for the user.

Supporting files in this skill

• See docs/platform-mapping.md for the authoritative build and host-setup summary used by this skill.
• See docs/failure-playbook.md for common remediation logic.
• Use scripts/hsb_phase_runner.sh as a helper when you want structured shell execution and timestamped logs.

Built-in help (--help)

If $ARGUMENTS contains --help or -h, do not run the workflow. Instead, print the following help text verbatim and stop:

Holoscan Sensor Bridge — Demo Bring-Up Skill
 
USAGE
  /hsb-setup [PLATFORM] [OPTIONS]
 
PLATFORM (optional — will prompt if omitted)
  AGX Orin          NVIDIA Jetson AGX Orin (iGPU, build with --igpu)
  AGX Thor          NVIDIA Jetson AGX Thor (iGPU, build with --igpu)
  IGX Orin iGPU     NVIDIA IGX Orin in iGPU configuration (build with --igpu)
  IGX Orin dGPU     NVIDIA IGX Orin with discrete GPU (build with --dgpu)
  DGX Spark         NVIDIA DGX Spark (iGPU, build with --igpu)
 
OPTIONS
  --help, -h        Show this help message and exit
  --verbose         Show full raw command output for every phase
                    (default is concise bullet-point summaries)
  --y               Auto-approve all phase gates (skip user confirmation
                    between phases). Not recommended — a confirmation
                    warning is shown before proceeding. All output is
                    saved to a timestamped log file.
  --repo <URL>      Clone a custom GitHub repo instead of the default
                    nvidia-holoscan/holoscan-sensor-bridge.
                    Can also be set via the HSB_REPO env var.
                    Priority: --repo flag > HSB_REPO env var > default repo
 
ENVIRONMENT VARIABLES (set before invoking the skill)
  SSH_TARGET        Remote login target (e.g. ubuntu@10.0.0.1)
  REMOTE_ROOT       Remote working directory for repo clone and builds
  REMOTE_SUDO       Privilege escalation: 'sudo', 'sudo -n', or ''
  REMOTE_SSH_OPTS   Additional SSH options (e.g. -o ServerAliveInterval=30)
  HSB_PLATFORM      Platform hint (same values as PLATFORM above)
  HSB_REPO          Custom GitHub repo URL (overridden by --repo flag)
 
WORKFLOW PHASES
  Phase 0   Token-budget preflight; verify enough plan usage for a full run
  Phase 1   Confirm platform, clone repo, and study user guide
  Phase 2   Host prerequisite checks and network setup
  Phase 3   Native build of CLI tools (AGX Thor only, skipped otherwise)
  Phase 4   Build, run demo container, and verify connectivity
  Phase 5   Produce issues report, optionally export to file
  Phase 6   Stop apps, exit container, hand off to user
 
  The skill prompts for confirmation between each phase.
 
EXAMPLES
  /hsb-setup AGX Thor
  /hsb-setup AGX Thor --verbose
  /hsb-setup AGX Thor --y
  /hsb-setup IGX Orin dGPU --repo https://github.com/myorg/my-fork.git
  /hsb-setup --help

After printing the help text, do not proceed with any phases or ask any questions.

See the EXAMPLES section in Built-in help (--help) for invocation examples.

When $ARGUMENTS contains a platform, use it instead of asking again. Strip --verbose, --y, --repo <URL>, and --help from the arguments before parsing the platform name.