systemone - VLM Run

vlmrun gw systemone, alias vlmrun gw s1, asks typed, calibrated questions of text, images, a PDF, or a video, and returns a probability per answer rather than generated text. See System One for the concepts and gateway for shared options.

vlmrun gw s1 "Invoice #44 was charged twice" --noul is_urgent

Positionals are resolved by what they are: an image path or URL becomes an image part (up to 8), a .pdf becomes the document part, .txt / .md / .json / .yaml becomes the state, and anything else is literal state text. Use -s to set the state explicitly, and every positional is then media.

Asking questions

Three inline flags cover most asks, and all are repeatable:

Flag	Form	Answer
`--noul`	`ID` or `ID="question text"`	P(yes), 0.0 to 1.0
`--choice`	`ID="a\|b\|c"`, a label may carry `:description`	The label, per-label probabilities, confidence
`--score`	`ID="level0\|level1\|..."`	The expected level, legend, probabilities, confidence

vlmrun gw s1 ticket.txt \
  --choice department="billing|technical|sales" \
  --score frustration="Calm|Frustrated|Very angry"

For anything larger, -Q/--questions takes inline JSON, @file.json, or - for stdin, in either a list form (ids carried per question) or the wire map. -B/--body sends a full request body, and other flags override it.

vlmrun gw s1 ticket.txt -Q @triage.json --json

Listing models

vlmrun gw s1 models prints the models a gateway serves with their release dates. There is no catch-all alias, so name one of them with -m.

vlmrun gw s1 models

Video

A video positional is sampled into frames, and each frame is one read. Answers render as a series over time: a sparkline per numeric question with its true peak and low, and a choice as the segments it held.

The video flags below ship in the next CLI release. The same reads are available now from Python: see Streaming.

vlmrun gw s1 clip.mp4 --fps 1 --ws -c 8 \
  --noul has_people="Are people visible?"

Flag	Description
`--fps`	Frames read per second of video. Each frame is one read.
`--max-frames`	Refuse to sample more than this from one clip. Default 60, checked against the clip’s duration before anything is sent.
`-c, --concurrency`	Frame reads in flight at once, 1 to 32.
`--ws`	Read the clip over one WebSocket session instead of a request per frame.
`--gate-mode`	How a gate reads a timeline: `any` (default), `all`, `mean`, or `sustained:N` for N frames in a row.

--ws is worth setting on anything but a short clip: the saving is round trips, so it grows with frame count. See Streaming. --gate-mode matters because a gate over footage usually asks whether something ever happened, which is why any is the default. sustained:N is the debounced form:

vlmrun gw s1 door.mp4 --fps 2 --noul is_open --gate 'is_open>0.9' --gate-mode sustained:8

Gates

--gate asserts a condition and sets the exit code, so a read can guard a script. It is repeatable and all gates must pass. Gates are checked against the question spec before the request is sent, so a selector that cannot apply costs nothing.

Selector	Value
`id`	P(yes) for a noul, the score for a score, the chosen label for a choice
`id.noul`, `id.score`	The number, explicitly
`id.choice`	The chosen label
`id.confidence`	`1 - H(p)/ln K`
`id.probabilities.LABEL`	One label’s probability

vlmrun gw s1 report.pdf --noul is_safe --gate 'is_safe>0.9'

Exit codes: 0 every gate passed, 1 a gate failed, 2 the request failed. With --json the verdicts go to stderr, so stdout stays a clean response body.

Repeats and dry runs

--repeat N sends the same request N times and reports mean, spread, and every read, which is how you see how much to trust one number. Gates then apply to the mean. This is distinct from --samples, which averages noise draws inside a single read. --dry-run prints the request body and exits without sending it. Piped output is the verbatim body, so it composes with curl.

vlmrun gw s1 ticket.txt --noul is_urgent --repeat 5
vlmrun gw s1 scan.jpg --noul signed --dry-run

Options

Option	Description
`-Q, --questions`	Questions as inline JSON, `@file.json`, or `-`
`--noul`, `--choice`, `--score`	Inline questions, repeatable, merged over `-Q`
`-s, --state`	State as text, `@file`, or `-`. Every positional is then media
`-B, --body`	Full request body; other flags override it
`-m, --model`	Model id. There is no catch-all alias, so name a served model
`--detail`	Vision budget: `auto` (default, reads at high), `low`, or `high`
`--steps`	Denoise steps per read, 1 to 8
`--samples`	Noise draws to average, 1 to 32. Every draw is billed
`--reasoning-effort`	Tokens of reasoning before the answer on a generative engine: `none` (default), `minimal`, `low`. A diffusion engine rejects it
`--fps`, `--max-frames`	Video sampling rate and its ceiling
`-c, --concurrency`	Frame reads in flight, 1 to 32
`--ws`	One WebSocket session instead of a request per frame
`--gate-mode`	`any`, `all`, `mean`, or `sustained:N` over a timeline
`-g, --gate`	Assert a condition, repeatable
`-r, --repeat`	Send N times and report mean and spread, 1 to 64
`--dry-run`	Print the request body and exit
`-j, --json`	Print the raw response JSON
`--timeout`	Request timeout in seconds

Remote images are fetched by the CLI, because the route accepts images only as data URLs, and must resolve to a public address. Set VLMRUN_ALLOW_PRIVATE_URLS=1 for an internal image host.

​Asking questions

​Listing models

​Video

​Gates

​Repeats and dry runs

​Options

Asking questions

Listing models

Video

Gates

Repeats and dry runs

Options