Vss Manage Video Io Storage

VIOS Operations

Purpose

Manage VIOS video input/output and storage with vss vios: sensors, streams, uploads, snapshots, clip URLs, and timelines. NvStreamer stays a separate REST API, used only for an explicit synthetic RTSP request.

When to Use

• Drive vss vios — add or delete a video file or RTSP stream, list sensors, show configured sensors, get a snapshot or clip URL (media_url), or upload a video file
• Serve test/sample videos as synthetic RTSP via NvStreamer, or drive the NvStreamer → vss vios add --type stream handoff
• Provision a source into a configured deployment so its notification receivers fan it out to RT-CV / RT-Embed / RT-VLM

Not for VLM inference or ad-hoc visual Q&A (vss-ask-video), semantic search (vss-search-archive), narrative summaries (vss-summarize-video), or reading analytics/incidents (vss-query-analytics).

Prerequisites

• The vss CLI on PATH. The OpenClaw and Hermes harness images ship it; anywhere else, install it from the same checkout as this skill so the CLI and the skill match: uv tool install <checkout>/libs/vss/cli.
• A deployment already recorded by vss configure. Confirm with vss configure show. vss configure --base-url is the only place an endpoint is supplied, and only the ingress origin the operator already has (VSS_PUBLIC_URL). If nothing is recorded and VSS_PUBLIC_URL is unset, stop and ask for the ingress origin. Never default a host or port. Exit codes, empty results, and pipe rules live in the repository root AGENTS.md.
• NGC credentials in $NGC_CLI_API_KEY and $NVIDIA_API_KEY for any image pulls.
• curl only for the direct-REST cases in Instructions, and jq for reading JSON. Use set -o pipefail, or capture stdout before piping. Docker is needed only for Compose deployment diagnostics.

Instructions

Use vss vios for list, add, delete, timeline, clip, and snapshot. Address media by sensor name. Do not build a sensorId from a name. --type (video for a file-backed sensor, stream for RTSP) is required on delete, a filter on list, and an optional check on add, which reads the kind from SOURCE (rtsp:// or rtsps:// is a stream, anything else a video). Do not hand-build a clip window when vss vios clip --sensor NAME can resolve it. Do not navigate the UI.

vss vios list     [--type video|stream] [--sensor NAME]
vss vios timeline --sensor NAME
vss vios clip     --sensor NAME [--start-time T --end-time T]   # -> media_url
vss vios snapshot --sensor NAME [--at T]                        # -> media_url
vss vios add      [--type video|stream] SOURCE [--name NAME]
vss vios delete   --type video|stream --sensor NAME [--keep-recordings]   # --keep-recordings: stream only

curl is not the path for those operations. If a vss vios command fails, report the failure — do not fall back to raw REST.

Where direct REST is allowed. Only in three cases, documented in references/api-reference.md and references/nvstreamer-api-reference.md:

• What the CLI does not cover — sensor info/status/settings, storage file list and media info, recorder status and configuration, WebRTC session control, the RTSP proxy, network scan, device settings, saving clip or snapshot bytes to disk, and the NvStreamer API.
• The caller names a specific VIOS REST endpoint, because the question is about the API itself.
• Debugging VIOS, where the raw status code is the evidence.

For a VIOS call, the base is the one vss configure recorded, never one you assemble (NvStreamer has its own base; see Operations):

DEPLOYMENT=$(vss configure show) || exit $?
VST_URL=$(printf '%s' "$DEPLOYMENT" | jq -er '.services.vst.url')   # the /vst mount
VST_API_BASE="${VST_URL%/}/api/v1"                                   # = <VST_ENDPOINT>/vst/api/v1 in the reference

If services.vst is absent, the deployment prerequisite below applies. Do not derive a base from HOST_IP, a port, or VSS_PUBLIC_URL.

Upload routing rule:

• If the user asks to "upload <file>.mp4 to VIOS", "upload a video file", or otherwise means storing a local video as a VIOS file-backed sensor, use vss vios add --type video <file>. The filename stem is the sensor name. Uploaded names must start with a letter or digit and use only letters, digits, ., _, and -.
• Use NvStreamer only when the user explicitly needs a live/synthetic RTSP camera feed, asks for NvStreamer, or asks to retrieve an RTSP URL.
• Do not substitute the NvStreamer upload -> RTSP URL -> vss vios add --type stream handoff for a plain VIOS MP4 upload request.

Provisioning + fan-out routing rule:

• To register a source on either an Agent-backed or headless deployment, follow references/provision-vios-source.md. Register once with vss vios add; the mounted notification config determines which consumers receive it. For a requested search capability, record the receiver as enabled, absent, or unknown before claiming automatic indexing. Unreadable policy is unknown, not an unavailable capability. Only an explicit tagging request with the streaming tagging receiver itself confirmed absent and the reference's prerequisites may use manual tagging; never use it when enabled or unknown. Alert rules remain owned by vss-manage-alerts.

Do NOT use this skill for:

• VLM inference or ad-hoc visual Q&A about a clip — use vss-ask-video.
• Semantic search across the archive — use vss-search-archive.
• Narrative summaries of a recorded clip — use vss-summarize-video.
• Incident-range or alert-window reports — use vss-generate-video-report Mode B.
• Reading analytics metrics, incidents, or alerts — use vss-query-analytics.

Reference contracts shipped with this skill

This skill bundles five reference files under references/. Read whichever applies to the task in front of you:

Deployment prerequisite — VIOS MUST be running

This skill operates a deployment vss configure already recorded. It does not construct a VIOS URL, and it does not deploy VIOS itself. When the vios group is missing, coordinate a deploy using the bundled deployment runbook (references/deploy-vios-service.md) or hand off to /vss-build-vision-ai.

For Kubernetes, do not use kubectl port-forward, an in-cluster Service name, a NodePort, or a guessed Helm release name. Before doing any work:

1. Confirm the recorded deployment:

   vss configure show
   vss configure check
   vss vios list

   vss configure show prints the origin already recorded. If nothing is recorded, the only setup is:

   vss configure --base-url "${VSS_PUBLIC_URL}"

   and only when the operator's ingress origin is already in VSS_PUBLIC_URL. If VSS_PUBLIC_URL is unset, stop and ask for the ingress origin. Never default a host or port.

2. vss vios list exits 4 when no deployment is recorded, or the recorded deployment does not expose vst. vss configure check does not use that code: it exits 3 when any recorded route is unreachable and 1 (as does vss configure show) when nothing is recorded, and it prints which command groups are available. On exit 4 from vss vios, re-run vss configure --base-url with the operator's ingress origin, or hand off to deploy. Do not curl a constructed URL to decide that. Offer the standalone path:

   "The vios group is not configured (exit 4) — no deployment is currently serving VIOS. (a) Bring up VIOS standalone using this skill's bundled references/deploy-vios-service.md runbook — image tags, env vars (notably VST_INSTALL_ADDITIONAL_PACKAGES=true), host directories, NGC login, bring-up command, healthcheck loop, and known deployment issues are all documented there. This is the right path if you only need VIOS itself (no RT-VLM / ELK / etc.) or if you're composing a custom profile. (b) Deploy a full VSS profile that includes VIOS via the /vss-build-vision-ai skill — base (recommended), lvs, search, or alerts all bring VIOS up alongside other components. This is the right path if you want a complete VSS stack. Which would you like?"

   • If the user picks (a) → walk them through references/deploy-vios-service.md step by step. Pay particular attention to its § Environment Variables — Required for Upload-to-Caption Path and § Known Deployment Issues sections — the libav-missing failure (VST_INSTALL_ADDITIONAL_PACKAGES=true) and the volume-drift hang (docker compose up --yes or docker volume rm first) are the two most common bring-up blockers. After deploy succeeds, record the operator's ingress origin with vss configure --base-url "${VSS_PUBLIC_URL}" (stop and ask if that variable is unset) and confirm vss vios list exits 0, then return here.
   • If the user picks (b) → hand off to the matching /vss-build-vision-ai stock workflow (default base). Return here once it succeeds and vss configure records the new origin.
   • If the user declines both → stop. VIOS operations require the vios group to be configured; do not attempt to fabricate responses or proceed with a degraded mode.

   Pre-authorized autonomous mode: if your caller has granted explicit pre-authorization to deploy prerequisites (e.g. the request says "pre-authorized to deploy prerequisites", or you are running in a non-interactive evaluation harness with that permission), skip the confirmation and prefer path (a) — bring up VIOS standalone via this skill's bundled references/deploy-vios-service.md — unless the request explicitly asks for a full VSS profile, in which case invoke the /vss-build-vision-ai stock Base workflow.

3. If vss vios list exits 0, proceed. An empty sensor list at exit 0 means the deployment has no sensors; it is not a missing service. Do not retry it.

Known limitation — leftover containers from prior deploys

VIOS's sensor listing (GET /vst/api/v1/sensor/list) can return HTTP 502 Bad Gateway or stale results when leftover *-smc VST containers from an earlier deploy survive teardown and win the network_mode: host port-bind race on :30000 / :30888. vss vios list fails that way, and so do timeline, clip, snapshot, and delete, because each resolves the sensor name through that listing. Report the failure; do not route around it with a raw call. Remediation: re-run /vss-build-vision-ai — its Step 0 teardown grep clears the full sensor-ms-* / vst-ingress-* / sdr-* / sdrc-* / rtspserver-ms-* set. Full failure-mode catalogue, remediation, and the current routing contract (direct vs SDRC; SDR/Envoy removed in PR #711) live in references/deploy-vios-service.md § Known Deployment Issues and issue #151.