Build Vision AI Skill

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.

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.

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

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.

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.

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

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:

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/<name>/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/<name>/override.env; do not assemble that list by concatenating the two stock profile files.

Before bring-up, the Skill validates _builds/<name>/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:

set -o pipefail
BUILD_DIR="_builds/<name>"
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.

Container image tag

deploy/docker/containers.env derives every managed first-party image tag from one knob, VSS_CONTAINER_TAG, defaulting to develop-latest. 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 <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. It is built from develop by default, whatever image tag the stack runs. To build it from a nightly or a release instead, name the 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 harness builds from develop.

The Skill checks out that revision alongside your checkout (under _builds/<name>/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: 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. After NemoClaw onboarding, run nemoclaw <sandbox> gateway-token --quiet on the deployment host and enter the token in Connect NemoClaw chat. 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.

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/<name>/:

_builds/<name>/
|-- 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

Use the vss-build-vision-ai skill to deploy the VSS base profile on this machine.

Use the vss-build-vision-ai skill to deploy the VSS search profile with remote LLM and VLM endpoints.

Use the vss-build-vision-ai skill to deploy a warehouse 3D profile with behavior analytics.

Use the vss-build-vision-ai skill to build a custom VSS stack for streaming object detection, video embeddings, and semantic search.

Use the vss-build-vision-ai skill to deploy the VSS base profile with the NemoClaw harness at nightly-20260928.

Use the vss-build-vision-ai skill to deploy the VSS base profile with image tag 3.4.0 and the NemoClaw harness at v3.4.0.

Use the vss-build-vision-ai skill to tear down the VSS build.

After deployment

After the Skill returns the deployment URL, configure the checkout-local vss CLI against that origin. Run this from the VSS Blueprint checkout:

VSS_REPO_ROOT="${VSS_REPO_ROOT:-$PWD}"
vss() { uv run --project "${VSS_REPO_ROOT}/libs/vss" vss "$@"; }
vss --version
vss configure --base-url "<VSS_PUBLIC_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.