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.

Base Code

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:

# Resolve the i4h-workflows base code (provides workflows/agentic/).
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"
fi
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.

Preflight

command -v uv
command -v git
nvidia-smi
df -h .

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

Each block below re-resolves REPO_ROOT (absolute) so it stays correct even if the shell's working directory is reset between commands — do not rely on cd persisting.

Step 1 — prepare a logged run dir (cheap, always allowed). Run this as its own command so the log target exists even when setup.sh is approved/run on its own:

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"

Step 2 — run the idempotent setup (long-running). On a freshly cloned repo the harness may ask to approve this script once; Step 1 already created the log dir, so it logs cleanly. Set I4H_WORKFLOWS to a pre-existing trusted clone to skip the fresh-clone gate entirely:

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"
"$REPO_ROOT/workflows/agentic/setup.sh" > "$REPO_ROOT/workflows/agentic/runs/.latest/logs/setup.log" 2>&1

Watch progress with tail -f "$REPO_ROOT/workflows/agentic/runs/.latest/logs/setup.log". For component-specific retries (also idempotent):

"$REPO_ROOT/workflows/agentic/third_party/setup.sh"
"$REPO_ROOT/workflows/agentic/policy/gr00t_n16/setup.sh"

Verify

REPO_ROOT="${I4H_WORKFLOWS:-$(git rev-parse --show-toplevel 2>/dev/null)}"; [ -d "$REPO_ROOT/workflows/agentic" ] || REPO_ROOT="$HOME/i4h-workflows"
"$REPO_ROOT/workflows/agentic/policy/run.sh" --list-envs
"$REPO_ROOT/workflows/agentic/arena/run.sh" --help
"$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

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.

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 --dry-run and --help; they confirm envs build, not that a full rollout works.

Troubleshooting

• Error: uv / git / nvidia-smi not found - Cause: missing host requirement. Fix: install it and re-run the Preflight checks before setup.sh.
• Error: a single component fails partway through setup - Cause: a third-party checkout or policy build did not complete. Fix: re-run the matching component script (e.g. third_party/setup.sh, policy/gr00t_n16/setup.sh); setup.sh is idempotent.
• Error: --list-envs or --dry-run fails after setup - Cause: setup incomplete. Fix: inspect workflows/agentic/runs/.latest/logs/setup.log and re-run setup.sh.
• Error: setup.sh fails instantly redirecting to a missing log dir - Cause: Step 2 ran before Step 1, so the run dir does not exist. Fix: run Step 1 (mkdir -p .../logs) first, then Step 2.
• Blocked: the harness denies setup.sh on a freshly cloned repo (auto-mode flags running a newly cloned external script) - Cause: a safety gate, not a setup error. Fix: run Step 1 first, then approve setup.sh once; or set I4H_WORKFLOWS to a pre-existing trusted clone (no fresh clone happens); or allow Bash(.../workflows/agentic/setup.sh:*) in settings.

Final Response

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