Vss Manage Video Io Storage

Purpose

Manage VIOS and NvStreamer API operations for VSS video input/output and storage workflows: sensors, streams, uploads, snapshots, clips, timelines, and recording status.

Prerequisites

• Active VSS deployment reachable on $HOST_IP (see vss-deploy-profile and references/).
• NGC credentials in $NGC_CLI_API_KEY and $NVIDIA_API_KEY for any image pulls.
• curl, jq, and Docker available on the caller.

Instructions

VIOS Operations

Call the VIOS REST API to manage cameras/sensors, RTSP streams, recordings, snapshots, and storage. Use when asked to: add a camera, add an RTSP stream, list sensors, show configured sensors/cameras/streams, check stream status, get a snapshot, download a clip, upload a video file, or manage video storage. Query the VIOS API directly using curl — do not navigate the UI.

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 the direct VIOS API: PUT /vst/api/v1/storage/file/{filename} from references/api-reference.md Section 8.
• 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 -> VIOS /sensor/add handoff for a plain VIOS MP4 upload request.

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, or ingesting video for search — 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 four reference files under references/. Read whichever applies to the task in front of you:

Deployment prerequisite — VIOS MUST be running

This skill is primarily an API client and assumes VIOS is already up and reachable at the VST ingress (default http://${HOST_IP}:30888). It does not deploy VIOS itself, but when VIOS is unreachable it coordinates a deploy using its bundled deployment runbook (references/deploy-vios-service.md) or hands off to the full-stack /vss-deploy-profile skill. Before doing any work:

1. Probe VIOS:

   curl -sf --max-time 5 "http://${HOST_IP}:30888/vst/api/v1/sensor/version" >/dev/null

2. If the probe fails, VIOS is not deployed. Offer two paths forward:

   "VIOS is not reachable at http://${HOST_IP}:30888 — no deployment is currently up. You have two options: (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-deploy-profile 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 and the probe in step 1 passes, return here.
   • If the user picks (b) → hand off to /vss-deploy-profile -p <profile> (default base). Return here once it succeeds.
   • If the user declines both → stop. VIOS operations require the VST backend to be up; 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 /vss-deploy-profile -p base.

3. If the probe passes, proceed. VIOS is up; all operations below are safe to execute.

---

Known limitation — leftover containers from prior deploys

GET /vst/api/v1/sensor/list and GET /vst/api/v1/sensor/<sensorId>/streams 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. Remediation: re-run /vss-deploy-profile — its Step 0 teardown grep clears the full sensor-ms-* / vst-ingress-* / sdr-* / sdrc-* / rtspserver-ms-* set. Other paths (storage/file/* upload, */picture/url snapshot, */url clip extraction) are unaffected. 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.

---

Setup

Base URL: http://<VST_ENDPOINT>/vst/api/v1

Endpoint Resolution:

• Use the VIOS endpoint associated with the active VSS deployment. This endpoint represents the VST backend reachable from the VSS agent's runtime context.
• Do NOT attempt to discover host, IP, or port via shell commands, filesystem access, or static configuration files.
• Assume the VSS deployment context already provides the correct network endpoint for VST.

Availability Check:

• Before making any API call, verify that the VST backend is reachable via the VSS deployment endpoint:

  curl -sf --connect-timeout 5 http://<VST_ENDPOINT>/vst/api/v1/sensor/version

• If the backend is unavailable (non-zero exit code or connection error), fail gracefully and report the error to the user. See the Deployment prerequisite section above for the deploy-or-stop branch.

Fallback:

• If endpoint information is not available from context, explicitly ask the user to provide the VST endpoint (host/IP and port).

Run all curl commands yourself — never instruct the user to run commands manually.

Auth: Optional. Most deployments run without auth. If a 401 is returned, retry with -H "Authorization: Bearer <token>" and ask the user for the token.

Start/end time handling: Any API that requires startTime/endTime:

• If the user provides them, use those values directly.
• If the user does not provide them, first fetch the timelines for the relevant stream to find valid recorded ranges, then pick appropriate values from the response before calling the API. Never fabricate timestamps.

Resolving sensorId / streamId: If the user has not provided a sensorId or streamId, look it up automatically using one of:

• GET /sensor/list — lists all sensors with their sensorId
• GET /sensor/{sensorId}/streams — lists streams for a specific sensor with their streamId
• GET /sensor/streams — lists all streams across all sensors
• GET /live/streams — lists all active live streams
• GET /replay/streams — lists all available replay streams

If a sensor has only one stream, sensorId and streamId are equal and can be used interchangeably.

---