--- title: "DGX Station AI Skills and dgx-assist — Instructions" canonical: "https://build.nvidia.com/station/ai-skills/instructions.md" --- # Step 1. Verify your environment Confirm the Station has the hardware and software the skills expect. Python 3.11 or newer is required by the installer. ```bash python3 --version nvidia-smi --query-gpu=name,compute_cap,uuid --format=csv docker info --format '{{.ServerVersion}}' ``` Expected output should show Python 3.11 or newer, a GB300 GPU reporting compute capability `10.3`, and a running Docker daemon. Note the GPU UUIDs rather than the row order — the `nvidia-smi` index is not a CUDA ordinal on this platform, and the skills always select GPUs by UUID. # Step 2. Clone the playbook Clone the playbook repository so the installer and bundled skills are available locally. ```bash git clone https://github.com/NVIDIA/dgx-spark-playbooks cd dgx-spark-playbooks/nvidia/station-ai-skills ``` Everything the installer needs lives under `assets/`: the installer itself, the `dgx-assist.pyz` CLI, and the four skill directories. # Step 3. Preview the installation Preview the exact changes before writing anything. The target is the project that should receive the skills — not this playbook directory. ```bash assets/install.sh install \ --harness codex \ --target /path/to/project \ --dry-run ``` Expected output should show a `WOULD WRITE` line for each skill file, one for `.dgx-station/bin/dgx-assist`, a diff of the managed NVIDIA block that will be added to your context file, and a closing `DRY-RUN: no files changed`. Choose the `--harness` value that matches your agent: | Harness | Skill directory | Context file | |---|---|---| | `claude` | `.claude/skills/` | `CLAUDE.md` | | `codex` | `.agents/skills/` | `AGENTS.md` | | `gemini` | `.gemini/skills/` | `GEMINI.md` | | `cursor` | `.cursor/skills/` | `AGENTS.md` | | `all` | every supported harness | managed blocks as applicable | Each harness receives complete native skill directories with their references, scripts, and UI metadata — never a lossy transformed command or rule. # Step 4. Install the skills and CLI If the preview is correct, run the same command without `--dry-run`. ```bash assets/install.sh install \ --harness codex \ --target /path/to/project ``` The installer backs up an existing context file before its first managed edit, refuses unmanaged skill collisions and symlink destinations, and records every installed hash in `.dgx-station/install-manifest.json`. To install only the CLI for the current user, when a project-local installation is not appropriate: ```bash assets/install.sh install-cli --scope user ``` Restart your AI coding agent in the target project so it picks up the new skills and context block. # Step 5. Verify the installation Confirm the CLI is present and the bundled content is intact. ```bash cd /path/to/project .dgx-station/bin/dgx-assist version .dgx-station/bin/dgx-assist catalog status .dgx-station/bin/dgx-assist playbook status ``` Expected output should show the CLI version, a valid bundled catalog, and a healthy playbook search index. You can check the installation itself at any time: ```bash assets/install.sh status --target /path/to/project ``` # Step 6. Confirm your platform support profile The skills refuse to guess what your Station can do. Inspect it and read the resolved profile. ```bash .dgx-station/bin/dgx-assist system inspect ``` Expected output should show an exact compatibility profile and per-feature capabilities. The trusted release marker selects one of three profiles: | Profile | Identity | Behavior | |---|---|---| | Software 1.0 | `7.4.1` or `7.4.1-GB300ws`; build `2026-02-20-05-22-42` | Guidance, diagnostics, read-only MIG inspection, and explicitly qualified recipes | | Software 2.0 | `7.5.0`; build `2026-06-16-11-48-10` | Capability-scoped qualified workflows | | Unknown | Any other exact identity | General read-only evidence only | A recognized Software 2.0 profile requires this base identity and hardware evidence, and the release marker must also pass ownership, file-type, symlink, and mode checks: | Field | Required value | |---|---| | `DGX_SWBUILD_VERSION` | `7.5.0` | | `DGX_SWBUILD_DATE` | `2026-06-16-11-48-10` | | `DGX_PRETTY_NAME` | `NVIDIA DGX GB300WS` | | GB300 compute capability | `10.3` | Software 1.0 does not inherit Software 2.0 CDMM, ordering-service, or `vsloshd` expectations. It permits only recipes explicitly validated for its exact profile; MIG mutation and platform fixes remain blocked. A different build is reported as unknown rather than assumed compatible. # Step 7. Ask your agent for a DGX Station task This is the normal way to use the playbook. Open your agent in the target project and make a plain-language request: ```text Inspect this DGX Station and explain its compatibility profile and restrictions. ``` ```text Serve Qwen/Qwen2.5-Coder-1.5B-Instruct with vLLM. Show the preflight and wait for my approval before starting anything. ``` The activated skill runs `dgx-assist --json`, interprets the evidence, carries resolution, report, and plan IDs between commands, and presents the result and approval boundary to you. You never need to read or copy raw JSON in this mode. The remaining steps show the equivalent direct CLI commands, which are useful for terminal work and for understanding what the agent is doing on your behalf. # Step 8. Search the pinned NVIDIA guidance Guidance comes from a bundled multi-source snapshot, not model memory. ```bash .dgx-station/bin/dgx-assist playbook search "mixed coherency containers" .dgx-station/bin/dgx-assist playbook search "CPU weight offload HBM forward pass" .dgx-station/bin/dgx-assist playbook search "ISL KV cache maximum concurrency" .dgx-station/bin/dgx-assist playbook show RESULT_ID ``` Every retrieved record carries its repository revision, source-file SHA-256, heading, lines, role, and authority class. The snapshot pins the DGX Station Development Guide at `76a1f6adf1a740699c2efff201377947d90f7fd8`, the GB300 Bring-Up Guide at `2f2d22b2fee4b6a2964045a97b786b86b366b65b`, upstream vLLM `v0.22.1` at `0decac0d96c42b49572498019f0a0e3600f50398` matching NVIDIA vLLM container 26.06, and the NVIDIA vLLM release notes. Where sources conflict, the current Development Guide overrides older bring-up statements about mixed GPU contexts and device indices; those passages and any credential examples are excluded from retrieval. Retrieval abstains when query terms do not overlap the pinned content — do not fill an abstention with remembered platform commands. # Step 9. Run the qualified inference recipe Resolve an exact model ID to a recipe, inspect it, run preflight, then preview the launch. ```bash .dgx-station/bin/dgx-assist recipe models .dgx-station/bin/dgx-assist recipe resolve --model Qwen/Qwen2.5-Coder-1.5B-Instruct .dgx-station/bin/dgx-assist recipe show --recipe-id RECIPE_ID .dgx-station/bin/dgx-assist recipe preflight --resolution-id RESOLUTION_ID .dgx-station/bin/dgx-assist recipe run --resolution-id RESOLUTION_ID --dry-run ``` Copy the labeled recipe and resolution IDs from one command to the next; in agent use the skill does this for you. Without `--dry-run` or `--yes`, an interactive terminal shows the action preview and asks for confirmation. A non-interactive caller repeats the command with `--yes` only after showing that preview and obtaining approval. Add `--allow-download` only after every required model and image download is disclosed and approved. If you set a non-local `--bind-host` on `recipe resolve`, the matching `recipe run` also requires an explicit `--allow-external-bind`. The bundled v1 catalog contains one published Software 1.0 smoke recipe — `Qwen/Qwen2.5-Coder-1.5B-Instruct` on vLLM — bound to its exact model revision, immutable NGC image digest, backend version, release profile, and checksummed qualification evidence. This is a functional smoke claim, not a performance benchmark. These candidates are bundled but deliberately non-runnable, and will refuse to resolve: - `nvidia/nemotron-3.5-nano` on vLLM - `qwen/qwen3.6-27b` on vLLM - `nvidia/nemotron-3-super-120b-a12b` on vLLM - `qwen/qwen3.6-27b` on SGLang Verify and manage a running service, then stop it when finished: ```bash .dgx-station/bin/dgx-assist recipe status .dgx-station/bin/dgx-assist recipe stop --service-id SERVICE_ID ``` `recipe stop` revalidates ownership labels and sends SIGTERM only. It never force-kills, and it only ever stops resources recorded as owned by `dgx-assist`. # Step 10. Plan a MIG layout Inspection is available on recognized Software 1.0 and Software 2.0 profiles. Planning and apply additionally require `mig_mutation=true` and your approval. ```bash .dgx-station/bin/dgx-assist mig inspect .dgx-station/bin/dgx-assist mig profiles .dgx-station/bin/dgx-assist mig plan --layout "DRIVER_PROFILE_IDS_OR_NAMES" .dgx-station/bin/dgx-assist mig apply --plan-id PLAN_ID --dry-run ``` Expected output should show driver-discovered profiles, the disruption and restoration information for the plan, and — under `--dry-run` — no change to the GPUs. `dgx-assist` never stops active GPU clients to apply a layout. # Step 11. Run diagnostics Diagnosis is read-only. Each allowlisted fix is separately previewed, confirmed, verified, and recorded. ```bash .dgx-station/bin/dgx-assist diagnose run .dgx-station/bin/dgx-assist diagnose bundle --report-id REPORT_ID .dgx-station/bin/dgx-assist diagnose fix --report-id REPORT_ID --finding FINDING_ID --dry-run ``` Expected output should show findings correlated to pinned playbook content, and a redacted support bundle path. Bundles and receipts persist redacted argv and credential variable names only, never secret values. # Step 12. Cleanup Remove the skills, the CLI, and the managed context block from a project. > [!WARNING] > This deletes every file recorded in `.dgx-station/install-manifest.json` and > removes the delimited NVIDIA block from your context file. Managed files you > modified are preserved, and unrelated context is left untouched. ```bash assets/install.sh uninstall --target /path/to/project --dry-run assets/install.sh uninstall --target /path/to/project ``` To remove a user-scope CLI and the local caches as well: ```bash rm -f ~/.local/bin/dgx-assist rm -rf ~/.cache/dgx-assist ~/.local/state/dgx-assist ``` # Step 13. Next steps Keep an installation current, or migrate one made by an older release: ```bash assets/install.sh update --target /path/to/project --dry-run assets/install.sh update --target /path/to/project assets/install.sh migrate --target /path/to/project --dry-run assets/install.sh migrate --target /path/to/project ``` Migration removes a released legacy skill only when its exact artifact hash is known; modified legacy skills remain with a warning. Update and uninstall operate only on manifest-owned files and delimited context blocks. 1. **Automate with the JSON envelope.** Every command accepts `--json` anywhere in its arguments and returns `schema_version`, `command`, `ok`, `data`, `warnings`, and `provenance`. Errors use the same envelope with an `error` object. Never parse the human display in automation. ```bash .dgx-station/bin/dgx-assist system inspect --json | jq '.data.compatibility | {profile_id, support_level, capabilities}' ``` 2. **Branch on stable exit classes.** Inspect both the process exit code and the JSON `error.code`. | Exit code | Meaning | |---:|---| | `0` | Success | | `2` | Invalid command, configuration, or input | | `3` | Unsupported platform or operation | | `4` | No eligible exact recipe | | `5` | Safety, approval, staleness, conflict, or policy block | | `6` | Authorized action or internal operation failed | 3. **Relocate configuration and state.** Unless XDG environment variables override them, configuration lives at `~/.config/dgx-assist/config.json`, caches at `~/.cache/dgx-assist/`, and resolutions, diagnostics, service ownership, receipts, and MIG plans at `~/.local/state/dgx-assist/`. 4. **Point at a live content endpoint.** The public package uses its bundled snapshot and is entirely offline by default. An internal pilot can supply endpoint configuration in the XDG config file or via `--config PATH`: ```json { "catalog": { "manifest_url": "https://approved.example/catalog/manifest.json", "allowed_hosts": ["approved.example"] }, "playbook": { "manifest_url": "https://approved.example/playbook/manifest.json", "allowed_hosts": ["approved.example"] } } ``` Refresh accepts HTTPS from explicit hosts, validates schema, key ID, Ed25519 signature through OpenSSL, digest, generation time, and expiry, then atomically activates the artifact. A failed refresh retains the last-known-good content. Use `--offline` to suppress the 24-hour bounded refresh attempt, or `catalog refresh --dry-run` and `playbook refresh --dry-run` to inspect the configured host and cache impact without network access. 5. **Tune inference with sourced guidance.** Name the exact model and describe the workload's ISL, generated-output distribution, target concurrency, latency and throughput goals, and repeated-prefix rate. The inference skill explains NGC versus upstream containers, GPU-memory headroom, weight and KV offload, HBM placement, KV-cache sizing, prefix caching, and chunked prefill — without turning those recommendations into launch flags. Changed parameters stay non-executable until an exact recipe is physically validated. A successful end state is an agent in your project that inspects the real Station before advising, cites pinned NVIDIA guidance with provenance, and stops for your approval before every mutation.