v0.6.0 to v0.8.0

48 added, 51 removed. Audit A to A.

---

name: i4h-workflow-setup

- version: "0.6.0"

- description: Verify host requirements and run `workflows/agentic/setup.sh`. Use when asked to set up, install, or bootstrap the agentic workflow, or hits missing `.venv`, third-party checkout, or engine errors.

+ description: Preflight and set up the root-level workflow runtime. Use for installation, missing component environments, or third-party failures; do not use for rollout validation.

license: Apache-2.0

metadata:

author: "Isaac for Healthcare Team <isaac-for-healthcare-support@nvidia.com>"

+ version: "0.8.0"

tags:

- isaac-for-healthcare

- i4h

- - agentic-workflow

- setup

- - installation

+ - dependencies

---

- # i4h Workflow — Setup

+ # i4h Workflow Setup

## Purpose

- Verify host requirements and run the idempotent `workflows/agentic/setup.sh` to bootstrap the agentic workflow. Use when asked to set up, install, or bootstrap the workflow, or when hitting a missing `.venv`, third-party checkout, or engine error.

+ Prepare the complete runtime, then prove dependency-light workflow discovery works.

- ## Base Code

+ ## Instructions

- These steps drive the i4h-workflows base code (the `workflows/agentic/` tree). To reuse an existing checkout, set `I4H_WORKFLOWS` to its path (no clone happens). Otherwise this resolves the current repo, or clones to `~/i4h-workflows` — pick that default without prompting. Run every command below from the resolved root:

+ 1. Resolve the base checkout.

+ 2. Run every host preflight check.

+ 3. Run default full setup.

+ 4. Verify discovery and `lint --all`.

+ ## Resolve the checkout

```bash

- # Resolve the i4h-workflows base code (provides workflows/agentic/).

+ export I4H_WORKFLOWS_REPO_URL="${I4H_WORKFLOWS_REPO_URL:-https://github.com/isaac-for-healthcare/i4h-workflows}"

+ I4H_REPO_DIR_NAME="${I4H_WORKFLOWS_REPO_URL%/}"

+ I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*/}"

+ I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME##*:}"

+ I4H_REPO_DIR_NAME="${I4H_REPO_DIR_NAME%.git}"

+ [ -n "$I4H_REPO_DIR_NAME" ] || { echo "Cannot derive a checkout name from I4H_WORKFLOWS_REPO_URL" >&2; exit 2; }

ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"

- if [ ! -d "$ROOT/workflows/agentic" ]; then

- ROOT="${I4H_WORKFLOWS:-$HOME/i4h-workflows}"

- [ -d "$ROOT/workflows/agentic" ] || git clone https://github.com/isaac-for-healthcare/i4h-workflows "$ROOT"

+ if [ ! -d "$ROOT/workflows/i4h_workflows" ]; then

+ ROOT="${I4H_WORKFLOWS:-$HOME/$I4H_REPO_DIR_NAME}"

+ [ -d "$ROOT/workflows/i4h_workflows" ] || git clone "$I4H_WORKFLOWS_REPO_URL" "$ROOT"

- export I4H_WORKFLOWS="$ROOT"; cd "$ROOT"

+ export I4H_WORKFLOWS="$ROOT"

+ cd "$ROOT"

```

- ## Basics

- - `workflows/agentic/setup.sh` is the idempotent setup entry point.

- - Cosmos setup is separate; invoke only when the user asks for Cosmos or video transfer.

+ Treat this resolver as part of the skill contract: a hosted copy may run outside the base repository, so never assume the current checkout contains `workflows/i4h_workflows`. `I4H_WORKFLOWS_REPO_URL` selects the clone source. When `I4H_WORKFLOWS` is unset, derive the fallback directory from that URL; set `I4H_WORKFLOWS` only to reuse or choose a specific destination. Never replace an existing checkout.

## Preflight

```bash

+ uname -srm

command -v uv

command -v git

nvidia-smi

df -h .

+ ./setup.sh --help

```

- Required: Linux, `uv`, `git`, NVIDIA driver/GPU, disk space for third-party checkouts. Docker is optional unless using Cosmos or local VLM containers.

+ Require supported Linux on `x86_64` or `aarch64`, `uv`, Git, network access for missing packages/assets, sufficient disk and model-cache space, and an NVIDIA driver compatible with the repository's Isaac Sim version. Read the exact current requirements from `./README.md`; do not rely on remembered version numbers. Require Docker only when the requested local VLM or Cosmos service needs it.

- Run the steps below in order. Each step is a separate bash call; variables persist in the local agent's tmux session.

+ ## Sync

- ### Step 1 — resolve repo and run dir

+ Run the default full setup:

```bash

- REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"

- RUN_DIR="${REPO_ROOT}/workflows/agentic/runs/setup_$(date +%Y%m%d_%H%M%S)"

- mkdir -p "${RUN_DIR}/logs"

- ln -sfn "${RUN_DIR}" "${REPO_ROOT}/workflows/agentic/runs/.latest"

+ ./setup.sh

```

- ### Step 2 — run setup

- On a freshly cloned repo the harness may ask to approve `setup.sh` once. Set `I4H_WORKFLOWS` to a pre-existing trusted clone to skip the fresh-clone gate.

+ The explicit equivalent is:

```bash

- "${REPO_ROOT}/workflows/agentic/setup.sh" > "${RUN_DIR}/logs/setup.log" 2>&1

+ ./setup.sh all

```

- Watch progress with `tail -f "${RUN_DIR}/logs/setup.log"`. For component-specific retries (also idempotent):

- ```bash

- "${REPO_ROOT}/workflows/agentic/third_party/setup.sh"

- "${REPO_ROOT}/workflows/agentic/policy/gr00t_n16/setup.sh"

- ```

+ Use `./setup.sh clean` only when the user explicitly requests a full rebuild or cleanup because it deletes generated caches, component environments, and third-party checkouts. Setup is idempotent; do not clean as a generic repair. The setup script restores pinned third-party sources and the upstream Isaac Sim skill catalog; do not copy that catalog into `skills/`.

## Verify

```bash

- "${REPO_ROOT}/workflows/agentic/policy/run.sh" --list-envs

- "${REPO_ROOT}/workflows/agentic/arena/run.sh" --list-envs

- "${REPO_ROOT}/workflows/agentic/policy/run.sh" --env scissor_pick_and_place --dry-run

- "${REPO_ROOT}/workflows/agentic/arena/run.sh" --env scissor_pick_and_place --dry-run

+ ./run.sh list

+ ./run.sh lint --all

+ test -f ./third_party/IsaacSim-045ca8b/skills/SKILLS.md

```

+ Use `run.sh show <workflow> --mode <mode>` when the user named a workflow. These checks prove discovery and contracts without importing Isaac Sim. Use `i4h-workflow-validate` for an actual rollout.

+ ## Troubleshooting

+ On failure, report the first host, network, checkout, or uv-sync error and rerun full setup only after correcting that cause.

## Prerequisites

- - Linux host with `uv`, `git`, and an NVIDIA driver/GPU (check via the Preflight commands).

- - Disk space for the third-party checkouts (`df -h .`).

- - Docker only when using Cosmos or local VLM containers; otherwise optional.

+ Require supported Linux, network access, `uv`, Git, disk space, and a compatible NVIDIA GPU/driver for simulator use.

## Limitations

- - Linux only; requires an NVIDIA driver/GPU.

- - Cosmos setup is separate — `setup.sh` does not run it; invoke Cosmos only when the user asks for it.

- - Verify steps use `--list-envs` and `--dry-run`; they confirm envs register and build, not that a full rollout works.

+ Setup does not download every optional checkpoint or prove any rollout succeeds. `clean` is destructive to generated environments and third-party checkouts.

- ## Troubleshooting

+ ## Examples

- - **Error:** `uv` / `git` / `nvidia-smi` not found — Cause: missing host requirement. Fix: install it and re-run Preflight before `setup.sh`.

- - **Error:** a single component fails partway through setup — Cause: a checkout or component venv did not finish. Fix: re-run that component's script (e.g. `third_party/setup.sh`, `arena/setup.sh`, `policy/setup.sh`); all are idempotent.

- - **Error:** `--list-envs` or `--dry-run` fails after setup — Cause: setup incomplete or a component venv missing. Fix: inspect `${RUN_DIR}/logs/setup.log` (or `workflows/agentic/runs/.latest/logs/setup.log`) and re-run `setup.sh` or the failing component script.

- - **Error:** `setup.sh` fails instantly redirecting to a missing log dir — Cause: Step 2 ran before Step 1, so `${RUN_DIR}/logs` does not exist. Fix: run Step 1 first, then Step 2.

+ - `Set up the i4h workflow on this machine and tell me if any host requirements are missing.` → preflight, run default full setup, then run discovery and `lint --all`.

- ## Final Response

+ ## Completion gate

- Report setup status, failed component (if any), relevant log path, next recommended smoke test.

+ Report every host check, synced target, first failing component if any, discovery/lint results, and the smallest next smoke command. Do not claim simulator or policy success from setup alone.