> This page is for version 3.3.0 (default). > For other versions, use one of these documentation indexes: > - 3.3.0 (default): https://docs.nvidia.com/vss/3.3.0/llms.txt > - Dev: https://docs.nvidia.com/vss/dev/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.nvidia.com/vss/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.nvidia.com/vss/_mcp/server. # Build Vision AI Skill > **Warning** > > Agent Skills are released as **Early Access** and are not intended for use in production environments. > Agent Skills for VSS were validated using Claude Opus 5. The `vss-build-vision-ai` Skill is the recommended deployment entry point for VSS. Use it from a coding agent such as Claude Code or Codex when you want to deploy a ready-made VSS workflow, deploy a warehouse blueprint, or build a custom vision stack from the VSS microservices. For developer-profile and custom builds, the Skill can also set up a host-side NemoClaw harness after the VSS stack is ready. Warehouse deployments do not support the NemoClaw harness yet. Unlike runtime Skills that operate a running deployment, `vss-build-vision-ai` does the build-time work: it chooses the closest validated profile, resolves the required services, creates deployment artifacts, validates the Docker Compose plan, deploys the stack when requested, and returns the URL you use afterward. > **Note** > > For the fastest first run, use `vss-build-vision-ai` to deploy the `base` > profile from the [Quickstart](/getting-started/quickstart#deploy-the-base-profile). ## When to use it Use `vss-build-vision-ai` when you want to: * Deploy a pre-built developer workflow such as `base`, `alerts`, `lvs` (Video Summarization), or `search`. * Deploy a warehouse industry blueprint, including 2D, 3D, MV3DT, and auto-calibration variants. * Build a custom stack from capabilities such as dense captioning, object detection and tracking, semantic search, alerting, or video summarization. * Rebuild a running deployment with additional vision capabilities in one resolved stack. * Tear down a stack that was created by the Skill. > **Warning** > > Deploying a rebuild or extension over a running deployment replaces the same > Compose project after you confirm the teardown plan. The default teardown uses `down -v`, which > removes that project's named volumes, including applicable model caches and > service state. `down -v` does not delete bind-mounted data under the configured > `VSS_DATA_DIR`, but the Skill's separate bind-mounted data cleanup does; that > cleanup requires its own confirmation. Back up required state or ask the Skill > for the cache-preserving teardown before you approve the replacement. Do not use this Skill for ordinary runtime operations after deployment. Once the stack is running, use the matching runtime Skill from the [Agent Skills catalog](/vision-agent/agent-skills#available-skills), or configure the checkout-local `vss` CLI wrapper for tasks such as uploading video, asking a question, searching an archive, managing alerts, or generating a report. ## Deployment paths `vss-build-vision-ai` supports three entry paths. | Path | Use it for | What the Skill does | | ---------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | Pre-built developer workflow | Quickstarts and standard workflows | Selects one validated developer profile: `base`, `alerts`, `lvs` (Video Summarization), or `search`. | | Pre-built industry blueprint | Warehouse deployments | Selects a warehouse variant and expands its validated service list. | | Custom build | Capability combinations that do not exactly match a stock profile | Starts from the closest profile and creates the smallest delta needed for the requested capabilities. | ## Supported profiles ### Developer workflows The table summarizes the default Skill-generated deployment for each developer workflow. Build Vision AI resolves the service graph for the requested capabilities and selected harness, so the exact graph can vary. | Profile | Best for | Default Skill-generated capabilities | | --------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | | `base` | First run, video Q\&A, and report generation on short clips | UI, Redis, VIOS, and RT-VLM. | | `alerts` | Real-time alerting and alert verification | Alert Bridge, Video Analytics API, RT-VLM, and optionally RT-CV with behavior analytics. | | `lvs` (Video Summarization) | Long video summarization | LVS server, RT-VLM, ELK/Kafka, VIOS, and the UI. | | `search` | Natural-language video search | RT-CV detection and tracking, RT-Embed embeddings, Elasticsearch, Video Analytics API, and search services. | VA-MCP is conditional: the Skill retains it for an in-stack agent that needs its tools or an explicitly requested legacy MCP/SOP capability. NemoClaw and host-CLI builds remove unrequested VA-MCP and use the Video Analytics API. For `alerts`, the Skill asks which mode you want: * `2d_vlm` for continuous RT-VLM inspection and real-time alert APIs. * `2d_cv` for RT-CV detections, behavior analytics, and VLM verification. ### Warehouse blueprint The warehouse path deploys validated industry-profile combinations rather than composing a custom delta. The Skill asks for the warehouse mode, deployment variant, size when applicable, and sample dataset. | Mode | Use it for | | ------------------ | ----------------------------------------------------------------- | | `2d` | Multi-camera RT-DETR perception and warehouse behavior analytics. | | `3d` | Depth-aware Sparse4D perception with behavior analytics. | | `mv3dt` | Multi-view 3D tracking with BEV fusion and appearance ReID. | | `auto-calibration` | Producing calibration for a selected warehouse dataset. | Warehouse deployments register their own sample sources through the warehouse configurator. Do not manually provision sources during the build path unless you are working with a separate custom or headless deployment. ## Host preflight and intake The host must satisfy [Prerequisites](/getting-started/prerequisites) (Linux, GPU, Docker, NVIDIA Container Toolkit, NGC). The Skill's own checks in `skills/vss-build-vision-ai/references/prerequisites.md` also require: * `uv` for mandatory service-graph checks and helper scripts. Install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`. * `curl`, `docker`, and NGC CLI access. The Skill asks which developer workflow or warehouse variant you want, LLM/VLM locality (local vs remote), and hardware. Defaults follow the selected profile (for example alerts `2d_vlm` vs `2d_cv`). Each answer changes the composed stack (services, `MODE`, GPU placement). The credential gate is determined by those answers: | Choice | Credential | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------ | | Any standard VSS deployment | `NGC_CLI_API_KEY`; authenticate Docker to `nvcr.io` separately before running the Skill. | | Public OpenAI-compatible harness endpoint | `COMPATIBLE_API_KEY` issued by the endpoint provider. | | `build.nvidia.com` model endpoint | `NVIDIA_API_KEY`. Create one from [NVIDIA API Keys](https://build.nvidia.com/settings/api-keys). | | Gated or rate-limited Hugging Face model download | `HF_TOKEN`. | | Self-hosted harness endpoint or no harness | No harness key. Stack-level NGC/model credentials still apply. | The Skill blocks before deploying when a required key is missing. It does not silently change the provider or disable the harness. During host preflight the Skill runs `deploy/docker/scripts/pin_docker_version.sh` with approval when needed. The script enforces the supported Docker range and `cgroupfs` setting and can restart Docker. Run it before starting containers, not on a host where unrelated running containers may be interrupted without review. ## Custom capability builds For custom builds, describe the capabilities you want instead of choosing a profile directly. The Skill owns the capability mapping: it selects the closest Foundation profile and creates a build-local delta for the services the request adds or removes. The Skill includes VIOS as the video input and storage layer for guided custom builds. It retains ingress only when the requested capability or harness needs a single public origin, and adds ELK/Kafka only for capabilities that publish to Kafka or index into Elasticsearch. ### Combine real-time alerting and video summarization Request the capabilities as one custom build; do not bring up the stock alerts and LVS profiles separately: **`Paste into your coding agent: Combined deployment prompt`** ```text title="Paste into your coding agent: Combined deployment prompt" Use the vss-build-vision-ai skill to build and deploy one VSS stack that combines real-time VLM alerting (2d_vlm) with long-video summarization. Show the resolved services, GPU placement, and teardown impact before deploying. ``` The build records exactly one stock profile as `FOUNDATION` in `_builds//override.env`, but correctness is determined by the resolved service graph rather than by forcing either stock profile to run unchanged. `MODE=2d_vlm` applies to the alerting path; the Skill must recompute every Foundation-derived configuration path and value in the build-local override instead of applying the LVS profile's derived paths to that mode. The resolved stack contains one `alert-bridge`, one `lvs-server`, one LLM, and shared instances of RT-VLM, VIOS, Kafka, Redis, Elasticsearch, Logstash, ingress, and `vss-video-analytics-api`, plus any selected agent or harness. It must set the alerts mode to `2d_vlm`, enable always-on alerting and RT-VLM Kafka output, and retain the LVS server and its Kafka summary path. The Skill writes the exact `COMPOSE_PROFILES` and dependent environment values to `_builds//override.env`; do not assemble that list by concatenating the two stock profile files. Before bring-up, the Skill validates `_builds//resolved.yml`. After readiness, `vss configure check` must report `summarize` as available, and the Alert Bridge, RT-VLM, LVS, and Video Analytics API services must be running. Harness-free builds use the `vss-manage-alerts` Skill for alert rules and incident queries; it calls Alert Bridge directly and does not require the in-stack VSS Agent. From the repository root, after the Skill reports the build name, inspect the exact generated plan and the services started from it: **`Run in the deployment host terminal`** ```bash title="Run in the deployment host terminal" set -o pipefail BUILD_DIR="_builds/" grep -E '^(FOUNDATION|COMPOSE_PROFILES)=' "$BUILD_DIR/override.env" docker compose -f "$BUILD_DIR/resolved.yml" config --services docker compose -f "$BUILD_DIR/resolved.yml" ps --services --filter status=running docker compose -f "$BUILD_DIR/resolved.yml" config --format yaml | sed -n '/^ lvs-server:/,/^ [^ ]/p' | grep -E 'KAFKA_(ENABLED|BOOTSTRAP_SERVERS|STRUCTURED_SUMMARY_TOPIC)' ``` Confirm that the resolved and running service lists each contain one `alert-bridge`, one `lvs-server`, `kafka`, `rtvi-vlm`, and `vss-video-analytics-api`. In the final command output, confirm that `KAFKA_ENABLED` is `true`, `KAFKA_BOOTSTRAP_SERVERS` names the `kafka` service, and `KAFKA_STRUCTURED_SUMMARY_TOPIC` is non-empty. Review the `COMPOSE_PROFILES` line as generated; do not replace it with a static list from this page because harness and capability choices can change the resolved graph. The default combined workflow uses one GPU. Alerts and Video Summarization share one RT-VLM process; Video Summarization does not add a second VLM. Alternative local or dedicated model choices can require additional GPU placement, so review the resolved plan before deployment. LVS work and continuous alert inference contend for the shared RT-VLM, and the Skill must still validate measured memory headroom and stream/request capacity on the target host. > **Warning** > > Developer profiles default to the same Compose project name, `vss`, and also use > singleton container names and host ports. Running stock alerts and LVS commands > side by side on one host is not supported; changing only > `COMPOSE_PROJECT_NAME` does not remove those collisions. A custom combined build > follows the replacement and teardown behavior described under > [When to use it](#when-to-use-it), so review the teardown plan before > proceeding. ## Container image tag `deploy/docker/containers.env` derives every managed first-party image tag from one knob, `VSS_CONTAINER_TAG`, defaulting to `3.3.0` on `release/3.3.0`. A build that must run a release's images selects that tag. Do not edit `containers.env`; it is checked in and shared by every deployment on the host. The Skill takes the tag from the first source that answers: 1. The request, for example *"deploy base with image tag ``"*. 2. `VSS_CONTAINER_TAG` already exported in your shell. 3. Neither, in which case `containers.env` defaults. This is the ordinary case. The Skill names the selected tag in the pre-deploy review summary and applies it to the images it manages. If any of those is left on the default tag, the build stops rather than deploying a partially tagged stack. On GB300 and DGX Spark, SBSA-suffixed services run the `-sbsa` variant of the selected tag, so their images differ from the common tag by that suffix. ## Harness source ref The NemoClaw sandbox image carries the operation Skills, the `vss` CLI and the OpenClaw plugin from one revision of this repository. The Skill defaults its harness source to `release/3.3.0`, independently of the stack image tag. To build it from another revision, name that revision in the request: 1. The request, for example *"deploy base with the NemoClaw harness at `nightly-20260928`"*. 2. `VSS_HARNESS_REF` already exported in your shell. 3. Neither, in which case the Skill selects `release/3.3.0` and stages that revision. The Skill checks out that revision alongside your checkout (under `_builds//harness-src`) and builds the sandbox from it, so the Skills, CLI and plugin all come from the one revision; `vss --version` inside the sandbox reports it. The ref is independent of the [container image tag](#container-image-tag): name both to pin both. Revisions older than staged harness builds are refused rather than silently replaced by `develop`. ## Agent harness When a developer-profile or custom build includes the in-stack VSS Agent, the Skill asks whether to deploy a host-side agent harness. The default harness is NemoClaw, which runs outside the Docker Compose project and operates the deployed stack through its public ingress URL. For a NemoClaw build with the VSS Web UI, the UI starts with the stack. Its chat surfaces wait for a gateway token. Follow the Quickstart's [NemoClaw handoff](/getting-started/quickstart#continue-in-nemoclaw) to connect using the returned sandbox name and chat URL, then copy videos into the sandbox. The UI checks gateway access at runtime; the container does not need to be restarted. If you choose no harness, operate the deployment from the host with the `vss` CLI. If you explicitly request the in-stack VSS Agent, the Skill preserves that agent instead. > **Note** > > A harness is not a Docker Compose service. The Skill never adds `nemoclaw` to > `COMPOSE_PROFILES`; it installs and starts the harness only after the VSS stack > passes readiness checks. Warehouse deployments do not enter the NemoClaw harness flow. The Skill deploys the selected Warehouse variant as-is; for the 2D `bp_wh` variant, that means preserving the in-stack VSS Agent. ## What the Skill creates For each build, `vss-build-vision-ai` writes build-local artifacts under `_builds//`: ```text _builds// |-- override.env |-- compose.yml |-- patches/ # optional; changed or new services only `-- resolved.yml ``` Warehouse builds also generate `configurator.env` because the warehouse configurator reads its own environment file. The Skill validates `resolved.yml` before deployment. If deployment is requested, it starts exactly the validated Compose plan and waits for profile-specific readiness checks before returning. ## Example prompts **`Paste into your coding agent: Deploy search`** ```text title="Paste into your coding agent: Deploy search" Use the vss-build-vision-ai skill to deploy the VSS search profile with remote LLM and VLM endpoints. ``` **`Paste into your coding agent: Deploy warehouse`** ```text title="Paste into your coding agent: Deploy warehouse" Use the vss-build-vision-ai skill to deploy a warehouse 3D profile with behavior analytics. ``` **`Paste into your coding agent: Pin images and harness to one release`** ```text title="Paste into your coding agent: Pin images and harness to one release" Use the vss-build-vision-ai skill to deploy the VSS base profile with image tag 3.3.0 and the NemoClaw harness at release/3.3.0. ``` **`Paste into your coding agent: Tear down`** ```text title="Paste into your coding agent: Tear down" Use the vss-build-vision-ai skill to tear down the VSS build. ``` ## After deployment If NemoClaw was provisioned, continue in its chat using the Quickstart's [handoff](/getting-started/quickstart#continue-in-nemoclaw). The sandbox already contains the operations Skills and configured `vss` CLI. To operate from the host terminal instead, configure the checkout-local `vss` CLI against the returned deployment origin. Run this from the VSS Blueprint checkout: **`Run in the deployment host terminal`** ```bash title="Run in the deployment host terminal" VSS_REPO_ROOT="${VSS_REPO_ROOT:-$PWD}" vss() { uv run --project "${VSS_REPO_ROOT}/libs/vss" vss "$@"; } vss --version vss configure --base-url "" vss configure check ``` Then use the runtime Skills or CLI command groups that match the deployed services: * `vss-manage-video-io-storage` or `vss vios` for sensors, uploads, clips, and snapshots. * `vss-ask-video` or `vss vlm` for one-off visual questions. * `vss-generate-video-report` for report generation. * `vss-summarize-video` or `vss summarize` for video summaries. * `vss-search-archive` or `vss search` for archive search. * `vss-manage-alerts` and `vss-query-analytics` for alerts and analytics data.