Using the client
RoboVAST runs simulation campaigns: a scenario, a sweep of configurations, repeated runs, recorded provenance. That work happens on a service — on a Docker host or a Kubernetes cluster. If you are the person driving it rather than the person hosting it, the client is all you need to install.
pip install robovast-client
vast login robovast.example.org
The scheme is optional: a bare host is filled in as https, or as http for
loopback, so the address as the operator hands it to you is the address you can type.
Three dependencies (pydantic, click, requests), 13 packages, about 30 MB. The
full robovast distribution is 88 packages and about 290 MB, because it can execute
campaigns itself — pandas and numpy alone are 152 MB of that, and none of it is needed to
push a project, launch a campaign or wait for one.
Nothing here is a reduced version of a command that exists elsewhere. Every verb the client offers only drives a service, so a client install is a complete install rather than a truncated one.
What you can do with it
Every group is named after what it acts on, so the group tells you what you are touching.
Command |
Does |
|---|---|
|
Store or forget the service credentials, verified before saving. |
|
Move a directory into a service workspace, and back out again. |
|
Check a project, and see what its sweep expands to — both before spending compute. |
|
Launch a campaign. The one way to run a |
|
What has run, and where one campaign has got to. The list marks a live campaign whose
queue priority or hold is not the default ( |
|
Block until a campaign is genuinely over. The exit code is the answer. |
|
Stop a campaign, kill one wedged job, read its infrastructure log. |
|
Which campaign the cluster queue admits first, and whether one admits at all. Orders what is queued; runs already started finish either way (Job Queueing). |
|
Launch a new campaign from what a past one recorded. The service refuses one its
pre-flight blocks; |
|
Permanently delete campaigns, each deleted or refused on its own and reported on its own line. Exits non-zero if any was not fully deleted; a running one is refused. |
|
Pull a campaign’s archive down as a |
|
Which service is answering, which code it runs and whether it has a queue to order; whether the cluster has room. |
|
What the service’s rebuildable caches hold; |
|
What the service itself has been doing. |
|
Roll the deployed service onto the newest image at its tag, through its own API — no kubeconfig needed. Reconciles nothing else; see Deployment Modes and Access. |
|
Run a command in the experiment image, to test a container before a campaign does. |
|
Read and write single files by address. |
|
Have the service build the derived images a project’s containers declare. |
|
Check the login, the service, and that |
That is the whole loop — validate, preview, launch, wait, fetch — and none of it needs the
core. What the core adds is local analysis: vast config reads and expands a .vast
on your disk, vast results computes over a results tree. Neither drives a service, which
is why neither is here.
An agent reaches the same service through its MCP endpoint, which needs nothing
installed at all — see MCP Server. vast login prints the claude mcp add line that
registers it. The two are not alternatives with a gap between them: the control verbs are
deliberately on both sides, and each side additionally owns what only it can do — bulk bytes
and long waits here, results queries and diff-based authoring there.
What is absent, and what is only partly here
Absent: vast serve, vast config, vast results, vast ui. They are not
hidden or disabled — the distribution does not register them, so vast --help on a
client install lists exactly what it can run. That is the point of installing it alone.
Partly here: vast service, and vast cluster as an empty group. The rule is the
same one, applied a level down — a subcommand exists exactly when something that can
perform it is installed:
vast service log|info|resources|restart|cache|mcp-statsship with the client. Every one of them only drives a service, so a client install runs them completely.vast cluster setup|cleanup|jobs-cleanup|monitorandvast service upgrade|tokenarrive withrobovast-cluster. They need a kubeconfig, an API server or a cluster Secret.
So vast service --help on a client install lists restart and not upgrade, and
vast cluster --help lists nothing at all until the cluster distribution is installed.
Nothing is stubbed and nothing fails on use.
Both groups spanning two distributions is the design, not an accident: a group is named
after the object it acts on, not after what you installed. vast service restart and
vast service upgrade both act on the deployed service; one needs a URL and a token, the
other an API server. Grouping them by what they touch keeps the name honest and lets
--help differ per install.
monitor is the one worth a word. It is a live, job-level dashboard over every
campaign, and its fallback view reads the Jobs from your kubeconfig — which is what keeps it
on the operator’s side. A client install watches a campaign with vast campaign wait (one
campaign, phase by phase, with an exit code), asks vast campaign list|status, and has
the web UI; between them they show everything monitor’s service view did.
Running a campaign
Three words are worth keeping apart, because the commands do:
- workspace
a directory on the service holding files and possibly several
.vastfiles.- project
one
.vastand the files it references. A workspace holds as many as you like.- campaign
an instance created from a
.vast.
So a campaign runs a workspace’s project, and the pair (workspace, path) names it. That
is the only project binding the service accepts, and vast workspace run takes exactly
that pair — as does the MCP tool, argument for argument.
A service cannot read your disk, so getting the files to it is a shell step rather than something an agent tool can do:
cd my-experiment
vast workspace init . --name my-experiment # first time
vast workspace update my-experiment . # after edits
Prefer this over writing files one at a time through the API: the bytes never enter an agent’s context, and one command keeps the workspace and your directory in agreement.
Files under a name starting with . are skipped, as is results/ — the same rule the
service applies when it lists a workspace, so a push and a listing cannot disagree.
Then check it, and run it:
vast workspace validate my-experiment my.vast # every problem at once
vast workspace preview my-experiment my.vast # how many configurations is that?
vast workspace run my-experiment my.vast --description "pilot: new inflation radius"
validate prints each problem with its severity and exits non-zero unless every check it
covers ran and passed — including the two that need a container: the world check, and parsing
the scenario in the image that would run it (the only check that sees an import
osc.<library> that image lacks). So a service that cannot start one is reported as unchecked
rather than counted as a pass; --no-world-check / --no-scenario-check ask for the
narrower verdict on the file alone.
Omit the path when the workspace holds exactly one .vast and the service will resolve
it, naming the candidates if there are several. --push DIR does the push and the launch
in one command, creating the workspace if the name is free — the two-step form above is the
same thing spelled out.
Set --description. It is one line saying what the run is for, and it is what tells
two same-day <name>-<timestamp> campaigns apart in vast campaign list and the web UI.
vast campaign list shows the campaigns still being worked on first, then the rest newest
first. --sort size orders by the results size instead, largest first, and --asc turns
either order round; the live campaigns lead under every order. The size column is what a
campaign’s results occupy, measured once when it ended, and reads - where none is recorded
— a campaign still running, or one never measured — which also comes last under
--sort size in both directions. The order is the service’s, applied before --limit
cuts the list, so it is the same order the web UI and the MCP list_campaigns tool show.
Nothing here needs a project file or a current directory. There is no ambient project at
all: every command names its own input, so nothing in a parent directory of your CWD decides
which .vast runs.
Waiting for a campaign
A campaign can run for days, so nothing blocks a request on one. vast campaign wait polls the
service and exits when the campaign is genuinely finished — past postprocessing, not
merely past its last run:
vast campaign wait basic-nav-2026-08-16-101500
Run it as the whole command, unwrapped and unchained. Anything appended makes the shell report the wrapper’s status instead, which turns a failed campaign into a reported success — a real incident, not a hypothetical one.
Its exit codes
The exit code is the answer. The codes are defined once, as the members of
robovast.execution.wait_exit.CampaignWaitExit: the command raises them, and this table, its
--help and every list of them an MCP tool or prompt hands out are rendered from them.
Anything else refers to a code by its name.
Code |
Name |
Means |
|---|---|---|
|
|
Finished, past postprocessing. |
|
|
Failed, or stopped. |
|
|
Stopped waiting: |
|
|
The service knows no phase for this id: a typo, or a campaign that died before recording one. |
|
|
Stalled: nothing has completed for longer than one run may take. Still running, and nothing is waiting on it now. |
|
|
A running job’s simulator reported an error-level health finding about itself. Still running, and nothing is waiting on it now. |
NO_PHASE is distinct from FAILED on purpose: the two send you looking for different
things. STALLED and HEALTH_FINDING end the wait with the campaign still running and the
run not touched; the message says so and names both ways out (re-run this command, or
stop_campaign). A health finding is what a running job’s own simulator reported about
itself (What a running campaign says is wrong).
Those two are why this command exists in the form it does. A stalled or wedged campaign never
reaches a terminal phase — it holds running for its whole life — so a waiter that stopped
only on a terminal phase would never return, and nobody would be told. Only a new stall or
finding ends the wait: whatever was already true when this command started is what the caller
was just told about, and exiting on it would make “re-run this after diagnosing” an infinite
loop rather than the way back.
vast image wait answers the same way for image builds, with the members of
ImageWaitExit:
Code |
Name |
Means |
|---|---|---|
|
|
Every build finished and its image is available. |
|
|
At least one build failed. |
|
|
Stopped waiting: |
When something is wrong
vast doctor
On a client install it checks what a client has: a stored login, that the service answers,
that vast resolves in a fresh login shell, and that the symlink points at a live
interpreter. A capability you have not installed is reported once, as advisory — you get
cluster support: not installed, and not the kubectl and helm that only
vast cluster setup shells out to, because there is no setup here to run them.
A client install lacking them is not a broken one, so they cannot fail the command.
When the failure is the service’s and not yours, its own log is now readable:
vast service log -f
Not a campaign’s log — this is the service process, and several failures in RoboVAST are
diagnosable only from it (a build whose reason “lived only in the service log”, a scene
cache retrying forever). It reads whichever service the CLI resolves — a local
vast serve on the conventional port, else the vast login record — and prints which
one answered, so it is never ambiguous which service you are reading.
It covers the last few hundred kilobytes that process logged, kept in memory: enough for
what it is doing now, not its whole life, and cleared by a restart. A container that has
already died is only in kubectl logs -p deploy/robovast-service — a buffer inside a
process cannot outlive the process.
vast login symlinks vast into a directory already on your login shell’s PATH, so a
shell that activated no virtualenv — a new terminal, or an agent’s — can run it. That is
what makes vast campaign wait reachable from an agent harness. Pass --no-link to manage
PATH yourself; vast doctor will tell you if the link later goes stale.
Where to go next
Quickstart — the three ways of working, and which one you are in.
MCP Server — driving the same service from an agent, with no install at all.
Setup — installing the full product, to run campaigns yourself.