Web UI
RoboVAST ships a small web frontend — a browser client of the
robovast-service (see Client–Server Architecture). It is a thin client of the same
robovast.service.interface.RobovastInterface contract the CLI and MCP
server use, so it works identically against a one-node deployment on your own machine
or a published one.
It provides four views:
Monitor — lists campaigns and shows each one’s live progress (phase, per-batch run progress, budget/stopping criteria), with a Stop action and a collapsible live log panel. Every campaign is listed folded: one row carrying its phase, id, description, its results size, a time, and a compact run meter, with the jobs list, the Details panel and the log not rendered at all — so a page of campaigns is a page of rows rather than metres of scroll. Clicking the row (or its chevron) unfolds the full card. Nothing opens itself, including the newest campaign and one that ended badly: the row says which it is, and opening it is always the reader’s choice.
The time column asks a different question of each state. A campaign that is over shows how long ago it finished — the freshness of its results, which its start time answers badly: a campaign that ran for eight hours and ended a minute ago is the newest thing on the page and started three days back. The listing orders the terminal group by the same figure, so the column and the order agree; a campaign whose record carries no terminal outcome falls back to its start time in both. A campaign that is still going shows how much longer it has, and shows nothing when no honest estimate exists. Hovering gives the exact times, and the duration or the expected finish.
A search may also stop early, and the estimate cannot see that coming: it measures the declared work, and a
no_improvementcriterion one flat round from firing means that work will not be done. So when the service says a stopping criterion is about to fire, the cell reads may stop early instead of a duration — the more useful fact, and the one the duration would otherwise misstate — and the ring’s arc turns amber beside it. Hovering gives the criterion’s own sentence (“not improved for 2 of 3 rounds”). A search bounded only by convergence, which had an empty cell before, now reads stops on convergence: no duration is projected, but the mechanism that will end it is named.Only
no_improvementcan be “about to fire”. It counts rounds, so its distance is real;target_objectiveandmetricfire on a value that can move any distance in a single round, so a proximity warning for them would claim a rate nothing supports. The verdict is tri-state like the stall verdict, and for the same reason: a search with nothing measurable declared says nothing rather than promising it will spend its whole budget.For a search that estimate is never its current round: a search runs an unknown number of rounds, so the round it is on says nothing about the whole, and one starting its sixth of six would otherwise claim the same remaining time as one starting its first. It is projected from what bounds the search instead — a
batchescriterion (the rounds still to come) or arunsone (the runs still to come), at the rate the current batch is achieving, and the smaller of the two when both are declared, since the campaign stops at whichever fires first. A search bounded only by an objective, a metric orno_improvementshows nothing: those fire on a value nothing can project. Like the batches estimate it answers when the work runs out, not when the search stops — another criterion may end it earlier.The compact meter is the same bar the open card draws full width — same segments, same
done/total— with the counts inside the track and the rest (passed, failed, no result, start and finish times) on hover; on a running campaign its striped segment is the runs in flight, so the folded row is live. A search campaign’s folded row adds a small budget ring, because a search’s run counters describe its current batch rather than the campaign. The ring measures whichever declaredbudgetcriterion is closest to exhausting — the one that will fire first, so the one that says when the campaign actually ends — and its hole carries that share as a percent — the unit varies (runs, rounds, evaluations, seconds), so a share is the one figure that reads the same for all of them. An exhausted budget shows a tick rather than100%: three digits and a sign do not fit a 26px ring, and replacing the single value that does not fit is what lets every other value keep its%. The tick is only for an exact full share, so a budget with a run still left in it reads99%rather than claiming to be done. The hover names the figure (budget spent 67% of runs), which is also what tells it apart from the round count the hole shows when nothing bounds the search. Hovering gives the rounds, the binding criterion with its unit and its scope, every other declared criterion including thestoppingones, the best objective, and the objective-over-rounds chart.The scope matters on the hover because a
runsbudget counts the campaign’s runs while the meter beside the ring counts the current batch’s: two run figures that otherwise look like they disagree.Only the four
budgetkinds can fill the ring. They are monotone resource caps, so a share of them means something; the threestoppingkinds are result-dependent early exits and are not a share of the same thing —no_improvementresets to zero on an improvement, so a ring driven by it would run backwards — and they appear on the hover as figures rather than as an arc. A search bounded only by those draws the bare ring with its round count inside: there is no denominator, and none is invented.In the open card every criterion is a sentence rather than a pair:
coverage >= 0.8besidenow 0.1, with a✓once it has fired. The comparison is published (BudgetItem.op) because a bare0.1 / 0.8silently implies>=, so ametricwritten<=read as “12% of the way there” when it had in fact already stopped the campaign.A bar is drawn only where the criterion has a floor to measure from: the four caps, and
no_improvementcounting up from zero to its patience (a static row claiming “2 of 3 strikes” survives the reset that rules it out of the ring). Ametricand atarget_objectiveget none — knowing a metric fires at<= 0.8says nothing about where it started, and an objective’s initial value is whatever the first batch happened to measure. Publishing the comparison made those rows readable, not their fraction computable.The campaign list itself is streamed over Server-Sent Events (
GET /campaigns/events), not polled: a launched campaign appears in the list immediately — with its true live phase and how long ago it started — and every phase change is pushed within a second. That age is deliberately relative rather than a wall clock: a campaign id already ends in a-YYYY-MM-DD-HHMMSSstamp, so an absolute start time beside it says the same thing twice. Hovering it gives the exact start and finish in your browser’s locale and timezone, and how long the campaign took — and the exact time is worth having, because the id’s stamp comes from the service host’s clock while this one is the viewer’s, which on a cluster are not the same reading. Leaving the tab and coming back does not leave it behind; see Staying up to date. Hovering a campaign’s name says where it came from — the workspace and the.vastit was launched from; see Where a campaign came from. A small cloud after the name says the campaign is already on the share: a cloud with a check for its postprocessed archive, a hollow cloud when the share holds only the raw campaign-end upload. Hovering it names every variant the share holds. It is read from the share’s own listing, so a share that is unconfigured or unreachable shows no cloud rather than a wrong one. A running campaign’s standing with the cluster queue is a chip beside the launcher’s name, folded or open:prio +2/prio -1when its priority is not the default0, andpausedwhen it is admitting no new runs. A campaign at the default shows neither. Both are live-only, like the queue they describe: a campaign that is over has no standing with it, so a finished card never carries them. They are set from the running card’s actions menu — Set queue priority… (the field starts at the current value, and only a whole number is accepted) and Pause admitting new runs / Resume admitting runs — the same operation asvast campaign priority|pause|resume(Job Queueing). The entries appear only on a service with a queue, which it reports ascan_schedulein/version. A change is confirmed by a notice carrying the service’s own answer, the priority the campaign now has and that runs already started are unaffected. The phase reflects the whole lifecycle, including its two pre-run steps:building(the campaign is waiting for its experiment image — builds are content-addressed and shared, so it may be waiting on one another campaign triggered) andvariation(the campaign’s configurations are being expanded), thenrunning→finishing→postprocessing→finished(orfailed/stopped). A build that fails is shown as afailedcampaign in the list rather than vanishing, and its builder output is in that campaign’s own log under aBUILDdivider. The per-batch run bar also distinguishes finished runs (the solid fill) from those currently running (a lighter segment on top), with the exactrunning N · pending Mcounts beside it. While a fixed-size campaign runs, an ETA (~12m left (≈ 14:35), the estimated finish time in your locale) appears next to that count once at least one run has finished, extrapolating from the average time per completed run. Below that progress, the open card carries two tabs, and which two depends on what the campaign is: a running one gets Jobs and Log, a finished one Details and Log. Details is not offered while a campaign runs because its numbers come from a table postprocessing writes, and Jobs is not offered once it is over because there are no live jobs left. Only the selected tab is rendered, so an unwatched Log holds no stream open; a job whose log you expanded is still expanded when you come back to the Jobs tab. The Jobs tab lists each execution unit of the current batch — a Kubernetes Job — with its status; expanding a running one streams that job’s own live log: every container it runs, merged into one stream, each line tagged[<container>]and colored per container when the job has more than one. That matters in the ROS shape, where the simulator and the system under test have their own containers and a failure is only legible when their output is read against the scenario’s. On the cluster, every placed row also names the node its pod landed on, as a coloured chip. The name is the information and the colour only a scanning aid – one machine is one colour down the whole list, so a batch that has piled onto a single node is visible without reading twenty rows. Colours are derived from the name, so they are the same for every viewer with nothing stored, and a set of them on screen is kept collision-free: two nodes are never the same colour, because two chips painted alike would read as one machine. A job the scheduler has not placed has no chip – that is what “not placed yet” looks like. Every row carries how long that job has been going, on the right, and that clock starts when the job does – before its pod is scheduled and before its inputs are staged – so a row that is stillpendingorblockedhas one too, which is where “how long has this been stuck?” is the question worth asking. Beside it, a running job on the cluster carries two small meters, cpu and memory. The track is the container’s limit, the fill is what it is using, and the hairline is what it reserved: so the fill against the hairline says whether the reservation was the right size, and the fill against the track’s end says whether the job is near being throttled or OOM-killed – which is also when the meter turns amber and then red. The exact figures are on the hover. Where a container states no cpu limit it may use the whole node, so there is no ceiling to draw and the bar is scaled to the reservation instead, which the hover says. A job that is not measured shows no meter at all rather than an empty one: an empty track reads as an idle job, which is a stronger claim than “not measured”. That is the case on a cluster with no metrics-server or a service whose RBAC predates themetrics.k8s.io/podsgrant – see Deployment Modes and Access, and the Jobs tab says which. A running job’s row also carries a red Stop button, which kills that job alone and lets the rest of the campaign carry on — the intervention for a job that is visibly wedged and will not exit by itself. It is offered on running jobs only: a queued one has not started, and a blocked one has a cause (no quota, an unpullable image) that deleting it does not fix. Nor on the two rows that are not trials. On a cluster campaign that calibrates its sizing (see Per-node container sizing) the Jobs list carries one row per node being measured, marked with acalibrationchip beside its status and named for its node; and while a cluster campaign is in itspostprocessingphase it carries the conversion of its rosbags, marked with apostprocessingchip and namedrosbag conversion. It is the phase’s only job, so without the row a campaign that is busy converting gigabytes of bags shows an empty Jobs list. That row is the one that does not open: its work runs in init containers, which a pod log does not carry, and its output is published to the campaign log’sPOSTPROCESSINGsection every few seconds while it runs — where it stays once the cluster has removed the job, which is when a failed postprocess is usually read. The Log tab beside it is where to look, and the chip’s tooltip says so. Both rows are the campaign’s infrastructure, not its trials — they are kept out of the job counts, out of the run meter and out of the ETA — and neither can be stopped one at a time, because there is no run to record as killed. Confirming asks for an optional reason, and the reason is worth giving — it is stored with the run and is what explains the kill to whoever reads the results later. The kill is permanent: the runs it cuts short are recorded askilled(see A run somebody stopped: killed), counted as neither passes nor failures. The campaign live log panel below is the campaign’s unified infrastructure log — the variation (config generation), run (controller) and postprocessing phases assembled into one stream with===== PHASE =====dividers — streamed live and shown in full once it finishes. Both tails follow the newest line only while you are at the newest line, the same contract as the run log: scroll back and the arriving lines are appended without moving the view, so a passage stays where you are reading it, and a button in the corner jumps back to the end and resumes following. A selection also pauses the follow while you hold it — auto-scrolling out from under a drag is what made a live log impossible to copy from — and dropping it resumes the tail by itself. Stop cooperatively ends the campaign and terminates its in-flight jobs, so running work halts within seconds whatever phase the campaign is in (what a stop ends, per phase). That is the whole campaign; to end one job and keep the rest, use the per-job Stop on its row above. It asks first, and says how many runs are in flight at that moment — the one thing a reader needs before pressing it that nothing else on the card shows. Worth confirming because there is no resume: a stopped campaign is over, and Retrigger campaign starts a new one from run zero rather than continuing this one. A card’s controls are two buttons: the actions menu (☰) and the fold. The menu is ordered by what a reader came for — open something, take something away, re-run something, destroy something — and every entry is conditional, so a campaign with nothing to act on yet is offered no menu at all. Its middle group is Download, which streams the campaign’star.gzstraight from the service’s/data/campaigns/{id}/archiveroute, tarred off its results tree as it is read and never buffered — and, when that campaign also has a copy on the share, Copy share link (omitted for a share provider that has no link a browser could open — SFTP has none). Below those, Retrigger campaign starts a new campaign from what this one recorded — its frozen_config/and the image its runs actually used — rather than from the workspace it was launched from, which may be gone or may have moved on. The source campaign is untouched, so this works whatever state it ended in, and the new campaign appears at the top of the list with a description naming the one it came from. It replays the recorded launch (_execution/launch.yaml), so re-running a one-config pilot stays a one-config pilot. A campaign that built its own image and never recorded a usable ref for it is refused rather than rebuilt from a guess: a campaign’s build context is not archived in its results, so the refusal names the container and points back at the workspace. A container the campaign did not build is not refused — its declared ref is resolved again at launch, exactly as a fresh launch from the workspace would, and the new campaign says which containers that applied to, because it will not be running the same bytes. Every re-run goes through the pre-flight (the same five axes the CLI’svast campaign rerun --checkprints), and the service refuses on a blocking one — a config no migration step carries forward, an image outside this host’s container-protocol window — so a re-run that could only fail in the backend is answered before it launches. The browser reads that report first and says which axis blocks, in a dialog whose Re-run anyway starts the campaign regardless: the override belongs to whoever has decided they understand the axis. A refusal that arrives anyway is the service’s own sentence, in a sticky error notice. A finished campaign also carries a collapsed Details box — what it cost, how it behaved, and what the next one should reserve; see The Details panel. The same menu offers Retrigger postprocessing, which opens a dialog to adapt theresults_processing.postprocessingblock (in a Monaco YAML editor) and re-run the analysis against the preserved raw rosbags — to compute different metrics after the fact without a new run. Because a campaign is self-contained (it carries the.vastthat ran), the edit is written into that file in place: theresults_processing.postprocessingblock of the campaign’s own_config/<name>.vast, with no override file and no revision history. It is the one narrow exception to the snapshot being a record of what ran, and it is why the read-only config view calls that snapshot frozen rather than immutable. The browser equivalent ofvast cluster monitor. Its Export to share entry names the variant it will write — (raw) or (postprocessed). That is not a setting: which one a campaign yields is read off the campaign itself, and once postprocessing has written into its tree the raw campaign no longer exists to export. A campaign ends up on the share as both by being uploaded at campaign end (before postprocessing, hence raw) and exported again afterwards.Launcher — starts a campaign from a workspace (which
.vast, config filter, runs per configuration, Postprocess when done and Upload to share when done toggles) and watches its live status. The browser equivalent ofvast workspace run. Upload to share when done streams a raw, pre-postprocessingtar.gzto the configured external share the moment the runs finish (off by default; the share destination comes from the service’s.env).Config — a workspace-based
.vasteditor with live validation, a generated-configuration preview, and a per-configuration view the.vastdeclares. It also serves, read-only, the configuration a campaign already ran — see Reading the configuration a campaign ran.Results — browse a campaign’s data: an Explorer over its analysis notebooks, a panel-based replay of one run, and read-only SQL with charts.
Admin — the service rather than the work: how loaded the cluster has been, which version is running, and what the service has been doing. Pinned to the foot of the sidebar beside the usage meters, which report the same service. See The Admin page.
The Admin page
Every other page is about a campaign. This one is about the service running them, and it answers the questions no other page does.
How loaded has the cluster been. The sidebar meters say now; “is the cluster busy?” is a
question about a period. The service samples its own /usage every 30 seconds and keeps
24 hours of readings, plotted as CPU and memory against capacity over the last hour or day.
One chart for the whole cluster — every node summed, one colour per resource — and two readings per resource: a filled area for what is actually being consumed, under a dashed line for what has been reserved. The gap between them is the number that sizes the next sweep: a campaign reserving nine cores per pod and using two draws a chart that would otherwise read as a full cluster while it idled. The caption names the encoding, so a reader never has to infer which is which.
On a cluster the dashed line is the sum of pod requests, and the fill comes from
metrics-server. Where metrics-server is not installed — or where the service’s RBAC predates
the metrics.k8s.io grant, which vast service upgrade reconciles — there is no fill
and the caption says why, rather than a zero line that would read as an idle cluster. A
single sample can be missing its fill too (a node that joined seconds ago is not in metrics
yet); that is drawn as a gap.
The recording is in memory only, and the caption under the chart says what it actually covers: a service started ten minutes ago has ten minutes of history, and an empty 24-hour view is the beginning of the record rather than an idle cluster. A restart clears it — including the restart the Upgrade button below causes. Capacity is stored with every reading rather than once, so a node joining or being drained does not redraw the past against today’s size.
What version is running, and is there a newer one. The page reports the version, the git revision where the deployment can tell (blank means it cannot, which is not a mismatch), when the running image was built, and the image digest the kubelet actually resolved — the only thing that distinguishes two builds of a floating tag. Against that it reports what the tag points at in the registry now. A registry that does not answer is reported as unknown, never as “up to date”: that would tell you a fix you have just published is not there.
The build date is the one line that reads without a second thing to compare it against: a revision needs a checkout and a semver needs a changelog, while “built 18 days ago” answers “is this deployment old?” on its own. It comes from the image itself, baked in at build time (see Container images) rather than read from a label — a container cannot read its own labels — so it is absent on a source checkout or a hand-built image rather than guessed at.
Note the asymmetry, which is deliberate: the available image is shown as a digest only. A version and a date can be asked of the image this service is executing and not of one it is not, and the answer would cost a walk through the registry’s manifests and config blob on every poll. It would also decide nothing — Upgrade is not a choice between versions, it rolls onto whatever the tag points at — so the digest and the verdict beside it are the whole answer this page needs.
Upgrade rolls the pod, and reconciles nothing else. It stamps the Deployment’s restart
annotation; with imagePullPolicy: Always the new pod pulls the tag afresh. RBAC, the
registry ingress route, the credential Secrets and the build daemon are untouched, so a
version needing a permission the last one did not will deploy and then fail at runtime with
a 403. vast service upgrade is the command that reconciles all of
it, and the credential Secrets in particular can only be done there — they are rebuilt
from the operator’s environment, which the pod does not have.
So the button is for “new bytes are published and nothing else changed”. A live campaign is not by itself a reason to refuse: its Jobs keep running and the replacement pod re-attaches to them. What the service refuses is the narrower case its own resume planner cannot answer for – the campaigns that could not be picked up again – and the refusal names each one with the reason it gives, which is what an operator would have to act on. Only then does the page offer to force, quoting that refusal; the first confirmation is not an override, because at that point there is nothing yet to override. The old pod stops before the new one starts – the campaigns are on a volume one node may mount at a time – so the API is away for a few seconds, and longer where the replacement has campaigns to pick up; the page waits for the running digest to change rather than trusting the request it just made.
Where a deployment cannot roll itself — a vast serve started by hand — there is no
button, just the reason. The same holds for a deployment set up with a fixed version
(ROBOVAST_PROJECT_TAG, see Container images): the button only ever re-pulls the tag the
deployment already runs, so it is offered only on a tag CI moves — latest, main, or
a pull request’s pr-<n>. Moving a pinned deployment to another version is
vast service upgrade with the new tag in its environment. The chart and the log work
unchanged.
What it is configured with. RoboVAST is configured entirely through environment
variables: an operator writes them into a .env and vast cluster setup /
vast service upgrade bake them into the pod. Nothing read them back, so “which share is
this uploading to?” and “did the last upgrade pick up that credential?” needed kubectl.
The Service configuration panel — collapsed until you open it, and fetched only then —
lists what this service is actually running with, grouped by what it configures, with the
default printed beside a setting that is unset.
The panel reports what is in force, not where it came from. In the pod every value
arrives as an environment variable and nothing there can tell a .env line from a real
one, so claiming a .env provenance would be a claim the process cannot check. The
caption at the foot says what a change costs on this deployment, which differs: a pod
loads its Secrets through envFrom at container start and never again, so only
vast service upgrade without --no-restart picks one up, while a vast serve
started by hand just needs restarting.
No credential is ever rendered — not masked, not truncated, not behind a reveal. A
secret shows as set and its value never leaves the service, because RoboVAST has no
per-route authorization: anything a response carries is available to every logged-in
caller. Two other kinds of value are held back for narrower reasons: registry endpoints and
refs never cross the client interface at all, and a path on the service’s own disk is shown
only to a caller on that machine — the same rule /version applies to its roots.
The list comes from the environment rather than from a catalogue in the code, so a setting
added to RoboVAST appears here without anyone maintaining a list. The cost is that a key
nothing recognises can turn up; it is shown as set with no value, since the next
setting somebody adds may well be a credential. If you see one, that is the prompt to
describe it in robovast.service.settings_report.
What it can give back. The Service cache panel — collapsed until you open it, and
measured when you do — lists what the service keeps that it can rebuild from durable data:
the compiled 3D worlds. The results tree is never offered: it is the campaigns’ durable
home, not a copy of one. Clear cache removes everything not in
use and says what it freed; what it keeps is listed with the reason. It is the thing to reach
for when new work is refused for disk space. vast service cache [--clear] does the same
from a terminal.
What the service has been doing. A service writes to stderr, and stderr is not readable back, which is why several failures in RoboVAST are diagnosable only from a log nobody could reach. The service now keeps its last few hundred kilobytes in memory and tails them here live, over the same stream the campaign logs use.
Two limits, both stated on the page: it holds what this process logged, so a container
that has already died is only in kubectl logs -p deploy/robovast-service; and a busy
multi-campaign run fills the buffer quickly, since every campaign’s records are interleaved
in it. vast service log [-f] prints the same thing from a terminal, against whichever
service the CLI resolves.
What the service did, kept. The Service events panel — collapsed until you open it, and fetched only then — is the durable half, and the distinction from the log above it is the whole reason it exists separately. That log is this process’s recent output and dies with the pod; these survive a restart, which is when they are most worth having.
What they carry is the two things this app otherwise shows once and forgets. Refusals: an action the service would not do — a retrigger it could not accept — was composed in the request that refused it and shown for ten seconds. And campaign lifecycle: the same starts, endings and failures the toasts and the OS notifications announce, which until they scrolled away were held by nothing. Each row carries the service’s own words, the time, the severity, who was refused where they said, and the status the caller got.
Repeats collapse: an identical refusal inside a minute is counted onto the row already there
(shown as repeated) rather than recorded again, so a panel polling something that cannot
answer it does not push the rest of the record out.
Newest first here, though the route (GET /admin/events) serves oldest-first from a cursor:
a caller resuming a position wants what came after its seq, and a person opening a panel
wants what just happened.
Staying up to date
A monitor you have to remember to refresh is a monitor that lies. The page keeps itself
current across a tab switch, a suspended laptop and a dropped kubectl port-forward,
and it does so on two mechanisms, because the page has two kinds of live data.
The streams — the campaign list and every log panel — are Server-Sent Events, and the
browser’s own EventSource recovery covers only the easy failure. Two others are handled
here. It gives up: after enough consecutive failures the browser parks the stream in
readyState CLOSED and never reopens it. And it cannot see a zombie: when a laptop
suspends or a tunnel is torn down, the socket raises no error, reports OPEN forever, and
delivers nothing more — indistinguishable from a campaign that simply has not changed. So
the service heartbeats every quiet second with a visible event (HTTP API), and the
UI watches that clock: a stream that is closed, or silent for 15 s, is replaced with a fresh
connection whenever the tab becomes visible, the page it feeds is switched to, the network
returns, or the check next runs.
The Refresh button beside the campaign list’s heading does the same thing on demand — it
is not the only way to get there, which is why it is an icon rather than a labelled
button: it sits next to the heading it acts on, the way the Explorer’s and the run view’s do.
Anything other than a healthy stream is labeled reconnecting… next to it, so a stale list
always says that it might be.
The polled readings — a campaign’s phase and its per-job listing, and the sidebar’s resource meters — deliberately stop polling while the tab is hidden, so a monitor left open in a background tab costs the service nothing. That is what makes coming back the moment they must be re-read: without it a card would show the phase from before you switched away for as long as its timer takes to restart. Those queries, and the Results tab’s campaign listing, therefore fetch once on return.
Switching pages counts as coming back, and for a while it did not. Every page is kept
mounted once visited so its state survives navigation — an editor buffer, a scroll position,
an upgrade in progress — and a page that never unmounts is one whose data is never re-read
either. So a page’s readings are also gated on that page being the one on screen: they stop
while it is not, and they are read again on the way back in. That is one rule with two
halves, and the second is what answers “did the version I just published land?” on arriving
at Admin, or shows a .vast that was added from the CLI without a browser reload.
Which readings take the gate is a judgement about each one, not a blanket policy. It applies to what is cheap and can change while you are elsewhere: workspaces and file listings, the campaign phases and job lists, the service version and upgrade check, the campaign listing, a run view’s panel layout. It deliberately does not apply to a finished campaign’s results — the SQL behind the Explorer, the Data browser and every run-view panel, and the notebook render. That data cannot change, because the campaign that produced it is over, and re-reading it is the most expensive thing this UI does; making every visit pay for it would buy nothing. Re-running postprocessing is what invalidates those, and it already does.
One stream takes the gate as well. In its default order the campaign list reads the app-wide stream, which stays open wherever you are: the start and end notices it feeds are owed to a reader who is on another page. Choosing a different order opens a second stream for that order alone, and that one is closed while the campaign page is not the one on screen – nothing reads it there, and the service orders every campaign it knows about on every tick it sends.
The gate is also what stops a hidden page from spending on the service’s behalf: before it, the Admin page cost a container-registry round trip every minute for as long as the tab was open, whichever page you were actually looking at, and each running campaign cost a Kubernetes API call every two seconds from a card nobody could see.
The file open in the config editor is a stronger case than the rest, because that editor
autosaves on every keystroke. A buffer holding a file’s old contents does not merely show you
something out of date — the next character you type writes it back over whoever changed that
file in the meantime. So returning to Config also re-reads the open file and compares it with
what the server last held. Unchanged, nothing happens. Changed on disk while your buffer holds
exactly what was last saved from it — the ordinary case, since autosave keeps those equal —
and the new version is simply loaded, with the save chip saying reloaded from disk so the
editor is never seen to swap its contents without a word. Only if both have moved is there
anything to decide, and then it asks: Load the new version, discarding your unsaved edits,
or Keep mine, which saves them over the change on disk. Keeping yours writes immediately
rather than waiting for your next keystroke, so the answer you gave and the file on disk do
not disagree in the meantime.
The app itself can go stale too, and it is the one thing here that no amount of
polling helps with. Each view is a separate chunk fetched on first visit, named by a
hash of its contents; restarting the service onto a new build rehashes all of them. A tab
opened before the restart is still holding the previous index.html, so the next view it
opens asks for a file that is no longer there. Nothing is wrong with the service and nothing
is wrong with the tab — they are simply one build apart.
So the failure is caught where it happens, at the view’s own boundary, and it offers both
clicks: Try again, which re-attempts the download and is what a dropped tunnel needs,
and Reload, which fetches the new document and is what a restart needs. The message
names both causes rather than guessing between them. A reload is cheap here because the
navigation lives in the URL hash — it comes back to the view you were on. The service serves
index.html as no-cache so that reload is guaranteed to see the new build, and
everything under assets/ as immutable, since a content hash in the name is a promise the
bytes never change.
What deliberately does not move is a result you are reading. The Results views take a snapshot of the campaign list and adopt a new one only when you ask (see Results viewer) — a finished campaign is immutable, so reshuffling its tree under someone mid-read would cost attention and return nothing. Freshness applies to what is still changing.
Being told what happened
Two kinds of thing the page has to say, and they are kept apart on purpose.
A passing fact gets a notice. Retriggering a campaign, copying a share link, deleting a workspace, finishing an upload, starting postprocessing — these are worth confirming and not worth keeping. They appear as a notice at the bottom right, stack newest-nearest, and clear themselves after ten seconds. Hovering the stack holds every countdown for as long as the pointer is there, so one never expires mid-sentence; the ✕ dismisses one immediately. At most four are shown at once, and the oldest give way — a batch of campaigns ending together must not bury the list they are about. Repeating an action refreshes its own notice rather than stacking a second copy of it, so leaning on a menu entry does not build a tower.
A failure is given weight, not permanence. A refusal or an error from something you did appears in the same bottom-right stack, with the service’s own message under it in monospace. It is held three times as long as a passing notice — ten seconds is enough to notice a sentence and not enough to read one — counted separately so a burst of campaigns ending cannot evict it, and drawn nearest the corner so an arriving notice pushes the stack up above it rather than shifting it out from under the pointer. Hovering the stack holds it for as long as you are reading. It still clears itself: a notice that must be clicked away turns every failure into a chore.
They are no longer kept on the card that raised them, because nothing there ever cleared one. The card does not unmount and the action’s state was never reset, so a refusal stayed visible until the tab was reloaded — long after the campaign it was about had moved on, and sometimes next to a later attempt that had succeeded.
What is worth keeping has a home. A campaign’s failure reason is on its card, and the notice announcing it offers Open campaign, which unfolds that card and scrolls to it. A refused action — a retrigger the service would not accept — is in the Service events panel on Admin, in the service’s own words and with the status the caller got, for as long as the record holds it; the notice’s longer duration is only what carries it until you look. (A refusal the service expects — stopping a job that finished a moment earlier — stays an ordinary ten-second warning; it names a race, not a fault.)
A campaign is addressable. #/execution?campaign=<id> opens the campaign view with that
campaign’s card unfolded and scrolled to; Copy link to this campaign in the card’s menu
hands you that URL. It is an instruction for arrival rather than a description of the page —
cards fold and unfold freely afterwards, and several can be open at once, so the link says where
to start and not what the page must look like.
Campaigns announce themselves. Starting and ending is reported wherever you are in the
app, not only on the Campaigns page — a campaign that ends while you are reading results says
so. A campaign that has finished and been postprocessed offers View results on the
notice, which opens the Explorer on it; one with no results yet does not, since there would be
nothing to open. Two cases are deliberately quiet: a service restart, which leaves campaigns
at phase unknown because their driver was lost rather than because they ended, and which
would otherwise announce an ending for every campaign at once; and a campaign moving between
running phases, which is progress rather than news.
The same events are kept. A notice is gone when you scroll past it and an OS notification when you dismiss it, so every start and ending is also written to the durable record behind Service events on Admin — which is where “what happened to that campaign last Tuesday?” is answered by something other than whoever happened to be looking.
An upgrade announces itself the same way. A service roll keeps running after you navigate away from Admin, and the handover starts a short countdown that reloads the tab — so the notice appears wherever you are, and offers the same Not now the panel does. Without it the reload arrives unannounced on a page you were reading.
Notifications outside the tab are off until asked for, and asked for once. The first time a browser sees a campaign running, a banner above the page offers to tell you when it ends — in context, so the offer arrives with a reason rather than on arrival. Enable raises the browser’s own permission prompt; No thanks declines, and either answer is remembered, so the question is never put twice. Once granted, a system notification appears when a campaign ends and this tab is in the background — never while you are looking at the page, which already showed the notice.
The standing switch is on Admin → This browser, which is also the way back after either answer. It is a preference of the browser, not of the service: several people share one instance behind one token, and each of them answers for their own browser. If the browser has blocked notifications for the site the switch says so and stays off, since a permission denial is sticky and cannot be re-prompted from the page — only that browser’s site settings can undo it.
This is separate from the push notifications a campaign sends to a phone, which come from the service rather than the browser and arrive whether or not anything is open; see Cluster Execution.
The list can be searched. The magnifier at the right-hand end of the heading row opens a field under it, hidden until asked for, that narrows the list to the campaigns whose id, description or launcher contains what you type — several words narrow further, wherever in the row each one sits. The heading says showing N of M while it is narrowed, and an empty result says which search emptied it, because a short list with nothing explaining it reads as a deployment with nothing in it. Closing the field, or Esc, restores the whole list: a filter that outlived its own field would hide campaigns with nothing on screen saying why.
Several campaigns can be deleted at once. The checklist button in the heading row turns on selection mode: every card gets a checkbox, and a bar under the heading counts what is picked and offers Delete N selected, plus a box that picks every finished campaign the list shows. A running campaign’s checkbox is disabled, because the service refuses to delete one and a control that can only produce a refusal says something false about what it does; a picked campaign that becomes busy again, or disappears, drops out of the selection, so the count is always what would be sent. A campaign the search hides stays picked and is sent too, and the dialog names it.
The delete asks once, in a dialog listing every id it will remove, and then answers in that same
dialog, id by id: deleted, already gone, not fully deleted (with the path it had to leave —
see execution.run_as_user in Configuration), or refused because the campaign is
running. It is the same operation as vast campaign delete A B C and the delete_campaign
MCP tool given a list, and like them it is not all-or-nothing: one refusal leaves the rest
deleted rather than sending you back to retry every one.
The phase is deliberately not matched. It is one value out of a known set, which is a control
of its own rather than something to spell out in a free-text box — and matching it there would
make a typed failed quietly mean two different things once that control exists.
The list can be ordered. The selector beside the magnifier offers Newest first (the default), Oldest first, Largest first and Smallest first. Campaigns still being worked on lead under every order, and the order applies within that group and within the rest. Newest is when a campaign finished, falling back to when it started, as the time column shows; largest is the results size on the folded row, which is what the results occupy, measured once when the campaign ended. A campaign with no size — one still running, or one that was never measured — shows none and comes last in both size orders, since an unknown size is not the smallest.
The service applies the order, before it cuts the list at a hundred campaigns, so on a large
deployment Largest first shows the hundred largest rather than the hundred newest re-sorted.
The choice is kept in the address (#/execution?sort=size&order=desc), so a reload or a
shared link comes back to the same order, and it outlasts a visit to another view. The start
and end notices are unaffected by it: they always follow the newest campaigns.
Bringing a campaign in
The import menu at the right-hand end of the campaign list offers the two ways a
campaign gets here. Import archive… takes a campaign archive (.tar.gz) off your
machine — a colleague’s results, a published dataset, or a campaign from a service you have
since torn down. It is the other direction of a campaign card’s Download, and it is the
same operation as vast campaign import and the import_campaign MCP tool: the browser
is only how the bytes get there (HTTP API). The other entry, Import from Share,
takes one off the configured share instead and is described under
Importing from the share; there the service does the fetching and no bytes pass through
your browser at all.
Extracting is not importing. Listings, this page and every query answer from the
campaign’s campaign.db, not from its results tree, so an archive that was merely unpacked
would appear blank — which is why the archive is registered, and why vast results
download alone does not make a campaign appear here.
It is also not instant. The import is a tracked operation like any other: the campaign
appears in the list straight away at phase importing — its id is read from the archive
before a byte is extracted — and, when the archive is a raw one, rolls on into
postprocessing rather than finishing without the tables anybody would query. So the
dialog closes as soon as you start it and you watch the row, exactly as for a run. A failed
import removes itself; there is no half-campaign left to tidy up.
An older archive is brought forward on the way in. The .vast’s version ladder is
applied in memory (the archived file is never rewritten), the campaign store migrates when it
is opened, and a store that is missing entirely is reconstructed from the results tree — the
normal case for a raw, pre-postprocess archive.
That is four independent things that can each be fine, old, missing or broken, so the outcome
is reported per stage rather than as one word, and every stage that is not ok says what
recovers it. The report is written to the campaign’s _execution/import.json, and this page
shows it under the heading once the campaign settles — the import answers with the campaign’s
id, not with a verdict, so there is nothing to show until there is.
The panel is collapsed by default, because an import is usually unremarkable and its headline is the whole story; the headline still names any caveat, so what folds away is the detail behind one, never its existence. Two problems are offered as a button rather than as advice: an archive whose campaign id is already here is refused before anything moves rather than silently replacing evidence, and Replace existing re-imports over it without re-uploading the bytes; a corrupt store offers Rebuild store, which reconstructs it from the results tree. A refusal of either kind never creates a campaign row, which is why it is reported here rather than on a card.
A degraded import is not a failure. A campaign that lists but under-reports — its runs were archived without their run directories, say — is still a campaign somebody has, and discarding it to keep a verdict clean would throw away the data. Only a stage that genuinely blocks fails the import, and the one thing nothing here can fix is an archive from a newer robovast: a schema cannot be migrated downwards, so that one asks you to upgrade.
Where a campaign came from
Hover a campaign’s name on its card and it says which workspace and which .vast the
campaign was launched from, with the workspace id and the file’s full, workspace-relative
path — the campaign’s frozen _config/ keeps only the basename, so a project holding
several .vast files in subdirectories would otherwise be ambiguous.
It is on the name rather than in a line of its own because it answers a question about a campaign the reader has already found by its name: a card is read for what the campaign is doing, and a permanent second line spends that space on something wanted occasionally.
The name itself is unchanged — same type, same weight, no underline, no cursor change, nothing that moves by a pixel. So the hover is not advertised: it is a detail for whoever goes looking, and it is documented here rather than marked on a card that is read at a glance for something else.
It is a record, not a link, and it is deliberately not clickable. A campaign is
workspace-independent (Client–Server Architecture): the workspace named may since have been edited,
renamed or deleted, and for an ingested campaign it may never have existed on this deployment
at all. Nothing resolves it — Retrigger campaign still relaunches from the campaign’s own
_config/, which is the honest thing to re-run. A link would promise the workspace is still
there, and that is the one thing this cannot promise.
A re-run adds a Rerun of row naming the campaign it came from, above the workspace the
configuration originally came from — copied forward at launch rather than looked up, so it
survives the parent campaign being deleted and a re-run of a re-run still names the root. The
campaign listing is paged, so a hover that had to find its parent in the list would answer
differently depending on where you had scrolled.
A re-run also gets a Config row saying which config version it read: v1 → v4,
migrated when the ladder had to carry the parent’s frozen .vast forward, and v4, as
written when it did not. Both are worth a row, because a re-run that read a different
config version than the campaign it reproduces is not repeating the same experiment — and
without the second wording, “nothing was migrated” would look exactly like “nobody recorded
it”, which is what a re-run from before this was kept shows: no row.
A campaign that ran before this was recorded has no hover at all. Its .vast basename
could be read out of its snapshot, but that says nothing about which workspace, and filling in
half the answer would read as though it knew the rest.
The same record reaches an agent through the MCP get_campaign_summary tool, beside the
image and code provenance it already reports. It is deliberately not on
list_campaigns, which is a triage listing.
The Details panel
A finished campaign’s card opens onto its Details tab: what the campaign cost, how it behaved, and — the reason it exists — what the next one should reserve. It answers “did this run well, and what did it cost?”; the Results explorer keeps answering “what did it find?”, which is why there is no per-configuration breakdown here. A campaign that has finished but not yet been postprocessed has no such measurements, and the tab says so rather than drawing an empty grid that would read as “this cost nothing”.
It has no frame of its own — the tab is its title and its open state — and it queries nothing until that tab is showing. Its four SQL statements include one that scans every 1 Hz resource sample of every run, so a page of twenty campaigns would otherwise pay for twenty campaigns nobody asked about. Opening it reads once; the answer is re-read when the campaign’s metric tables appear, since a campaign is finished some minutes before it is postprocessed.
Columns, each answering something the others cannot:
Overview — CPU-hours consumed, simulated time (summed run durations; the simulator runs at realtime pacing, so one simulated second is one wall second) and completed runs per minute of wall clock. Counted in runs, which is what the data records — a job with
execution.runs_per_job > 1carries several.CPU and Memory — a ring of MEAN usage per container, showing which of them the pod’s demand is actually made of, beside one bar per container: the box is the p25–p75 of per-tick demand, the whiskers p05–p95, the tick inside it the median, the amber tick the peak, and the faint backdrop what the
.vastreserved. An over-reservation is the backdrop the box does not fill. The row ends with the measured median; the suggestion is in the column header’s hover, with the p95 and peak it comes from.Ended in — which scenario action each run’s trial was in when it ended, top five, split pass/fail. Derived from the
behaviorstable thatscenario_executionwrites for every campaign, and campaign-independent by construction: it names no action, topic or plugin. A run that timed out is attributed to the goal it was pursuing, not to the scenario’s own terminal marker.Duration — the distribution of run durations. Binned over the data’s range rather than from zero, with a ten-second floor so a campaign whose runs agreed to within milliseconds does not draw that noise as if it were a spread.
Objective — a search’s best objective per round, with its stopping criteria beneath. Rate-shaped objectives are drawn against 0..1, since
best = 1then means “as good as it can get”; anything on another scale keeps its own range, and both axes are labeled either way.
Sizing advice
The CPU and Memory hovers give, per container, what was declared, what was measured, and what
to reserve — the value to write into execution.containers.<name>.resources.cpu /
.memory, plus the pod total, which is the figure that divides into the cluster quota.
The two rules differ, and the difference is not cosmetic:
CPU is sized on sustained use (p95) plus 25% headroom, rounded up to a quarter core. Exceeding a cpu reservation costs CFS throttling for that scheduling period — slower, still correct — which is the right price for not reserving a brief peak permanently. A container whose peak is far above its sustained use is marked ⚡: it will be throttled during those bursts, and that is the trade rather than an oversight.
Memory is sized on the PEAK plus 25% headroom, rounded up to 128Mi. Exceeding a memory limit is an OOM kill: the run dies and the campaign loses that cell. Sizing memory on a percentile would be choosing how often a run survives. Its figures are upper bounds —
memory_rss_bytesis summed per process name, so pages shared with a fork count twice.
A suggestion is withheld, with the reason shown, when the container produced fewer than 30 samples: a campaign of sub-second runs yields single digits of in-window ticks across every run put together, and a p95 over seven points is the maximum wearing a percentile’s name.
The advice works on a campaign that declares no resources block at all — which is the
campaign that most needs it, since nothing else says what to set. The container names are
read from the config either way, so the measured main container (recorded under the role name
robovast) still resolves to a name that appears in the reader’s file.
The same advice reaches an agent. get_campaign_summary in the MCP server returns an
advice list computed by robovast.results_processing.advice, which is the authority
for these rules; tests/results_processing/test_advice.py pins the web UI’s constants
against it, so the two cannot drift into telling a human and an agent to reserve different
amounts for the same campaign. Each item carries a plain-text title and detail beside
its kind, so a consumer that has never heard of a particular kind can still show it.
What a campaign declares, and where it lands
Everything the UI draws is declared in the .vast’s visualization: block, which is
shaped like this page: one key per view.
visualization:
config:
panels: [...] # Config tab, third column
results:
run_view:
panels: [...] # Results -> Run view
timeline: {...} # Results -> Run view, playback time base
explorer:
notebooks: [...] # Results -> Explorer
data_browser:
plots: [...] # Results -> Data browser
Reading an older campaign. A campaign archived before these keys moved carries them in
two unrelated top-level blocks. The mapping, for anyone opening a campaign’s archived
_config/*.vast:
Old key |
Now |
|---|---|
|
|
|
|
|
|
|
|
This table documents a historical format; it is not a compatibility promise. Nothing in
RoboVAST reads the old keys: a .vast using them is refused by name, and a campaign that
ran with them keeps them in its frozen snapshot — so its Explorer tabs, declared plots and
run-view panels do not appear, and it can neither be retriggered nor reconstructed into a
workspace. Its data is unaffected: SQL, logs, the run listing and the download all work. To
bring such a campaign forward, migrate its configuration by hand:
vast files cat /results/<campaign_id>/_config/<name>.vast > old.vast
# move the keys per the table above, then:
vast workspace init <dir> --name recovered
Config editor
The Config tab is where a .vast is authored. Because a browser has no working
directory, the project lives in a server-side workspace (see
Client–Server Architecture): select or create one, upload the scenario file and any
run files, and author the .vast in the Monaco editor.
Taking a project out and putting one back
Three buttons beside the workspace picker:
Download saves the selected workspace as <ws-id>.tar.gz — the project files under
one directory, which is the same archive vast workspace download fetches.
Export to share publishes it to the configured share, which the service uploads to with its own credentials (a browser has none). The toast names the object, which is what somebody on another deployment types to import it.
Import from share lists the workspaces on the share and brings one in. Each import creates a new workspace named after the archive; nothing here is replaced, so importing twice gives you two copies. Both share buttons are absent where the deployment has no share configured — see Sharing Results.
Tip
To seed a workspace from an existing project directory in one command (instead of uploading files by hand), use the CLI — it mirrors the MCP workspace tools and drives the same service:
vast workspace init configs/examples/ros2_basic --name ros2demo
vast workspace list # confirm it
# then open the Config tab and pick "ros2demo" from the workspace dropdown
vast workspace init writes .vast/.osc inline and uploads the rest
(preserving sub-directories and the executable bit). Re-running it on the same
directory creates a new workspace each time; a name that already exists gets
an incrementing -2/-3 suffix (printed in the command’s output) so the
copies stay distinguishable in the dropdown.
To push a fresh version of a project into the workspace that already exists
(instead of making another copy), use vast workspace update with the
workspace’s ws-… id or name:
vast workspace update ros2demo configs/examples/ros2_basic # add + overwrite
vast workspace update ros2demo configs/examples/ros2_basic --prune # also delete removed files
To work on individual files rather than sync a whole directory, a workspace’s
contents are addressable as /sources/<workspace_id>/<path> — the writable
half of the same address space a campaign’s outputs use (see
Reading these files):
vast files ls /sources/ros2demo/ # what the workspace holds
vast files cat /sources/ros2demo/demo.vast
vast files put /sources/ros2demo/files/run.sh ./run.sh
vast files rm /sources/ros2demo/files/old.osc
put writes .vast/.osc directly and streams everything else through
the upload side channel, preserving the executable bit — the same two paths the
Config tab’s drag-a-folder upload uses.
update re-uploads every file (overwriting in place) with the same inline /
side-channel split and skip rules as init. By default it only adds and
overwrites; --prune also deletes workspace files that no longer exist under
the directory, so the workspace mirrors it exactly. In the
browser, dragging a project folder onto the Config → Files tab performs the
same add/overwrite sync. An agent has no third route: the MCP interface reaches the
service, not the caller’s disk, so a whole directory goes through this command.
Tip
It lands wherever the UI is — with no flag at all. A workspace lives in the
store of whichever service you talk to, and vast workspace follows the same
one the browser is on: a service answering on the local port, otherwise the one
vast login recorded.
# (a) a service running on this machine → this follows it:
vast workspace init configs/examples/growth_sim
#> Target: service (http://127.0.0.1:8800) [detected]
# (b) logged in to the deployed one → this goes there:
vast workspace init configs/examples/growth_sim
#> Target: service (https://robovast.example.org) [detected]
# (c) neither → this machine, in-process:
vast workspace init configs/examples/growth_sim
#> Target: this machine, in-process (store: …)
There is no flag to pick between them: with the service published and
authenticated, an operator uses the same path as everybody else. Every command
prints the Target: it
resolved — including [detected] — so the choice is never silent. To reach a
service that is neither local nor in this cluster (a remote VM), bring up your
own tunnel to the conventional port 127.0.0.1:8800
(ssh -N -L 8800:127.0.0.1:8800 <vm>) — the same auto-detect then follows it,
no flag needed.
The .vast JSON Schema
(from the service) drives completion and inline validation as you type, and the
service validates the whole project (schema + scenario references + plugin refs)
after each edit — problems appear in the panel below the editor, and so does advice on a
valid project (listed under the pass, since it does not take it away). Generate expands
the config and lists the resolved configurations with their parameters, without
running anything. Variation plugins declared in the .vast plugins: list are
installed server-side automatically, so validation and preview resolve them.
The config view
The Config tab is three columns: the editor, a narrow list of the
configurations Generate expanded to, and — beside them — a view of the selected
configuration that the .vast itself declares.
visualization:
config:
panels:
- parameters: {title: Scenario parameters, height: "35%"}
- world: {title: World configuration, height: "15%"}
- scene3d: {title: Scene} # no height -> takes what is left
Panels stack top to bottom in declaration order. A panel’s only layout field is its
height — pixels, or a percentage of the column; the last one may omit it and take
whatever the others left. (Declaring two heightless panels is refused when the campaign is
validated, naming the panel, rather than laying one over the other.) Everything else on a
panel entry is that panel’s own data binding, exactly as in the run view.
A .vast that declares no config: block gets parameters and world, so the
column is never empty for want of a block nobody wrote.
The built-in panels:
Scenario parameters (parameters) — what the trial is given, as YAML, and nothing
else. Not the _-prefixed keys a variation writes for other readers (_map_file,
_path, _goal_parameter_name), and not a preview of each factor’s value list with this
configuration’s value marked: both would restate in a second notation what the .vast in
the next column already says, and the column is too narrow to spend on that.
World configuration (world) — the resolved sim block: the world this
configuration runs in and the plugin overrides on it. A different question from the
parameters — one says what the trial does, the other what it runs in — and it is where a
campaign that varies its environment shows that. Describe world asks the simulator, in
the campaign’s own image, which plugin keys it actually offers; behind a button because it
runs a container.
Scene (scene3d) — the world in 3D, with what this configuration’s variations placed
drawn on it. Same renderer and same navigation as the run view’s.
The geometry is the campaign’s base world. It is keyed on the .vast’s world and
its campaign-level overrides, not on the selected configuration, so clicking through
configurations swaps markers rather than running a container each time — and the entry is
the same cache a campaign uses, so compiling it here leaves the run view warm, and the
reverse. A configuration naming a different world file (a floorplan baked per cell) is a
different identity and does get its own geometry.
What that costs is stated in the panel: an override that changes geometry through a plugin is not in the mesh, only what the variation contributes as markers. This is a view of the base world plus placements, not a compiled preview of the exact model the run will load.
Map (map2d, ships with robovast_nav) — the occupancy map a nav campaign plans
on, with the same markers drawn top-down. It exists beside the 3D scene because it is the
planning view: a path is searched over these cells and an obstacle is placed relative to
that path, so “why did the path go there” is a question about this picture. Drag to pan,
wheel to zoom, double-click to fit; the scale bar reads in meters.
Which map it draws: the one a variation contributed as its map role, or the one bound on
the panel, which is how a campaign points at a map it holds itself. A binding wins, being the
author naming a file outright:
- map2d:
title: Map
map: files/depot.yaml # or {param: map_file} / {internal: _map_file} / {role: map}
markers:
- {kind: pose, pose: {position: {x: 0.0, y: 0.0}}, label: start, color: "#60a5fa"}
- {kind: pose, param: goal_pose, label: goal, color: "#4ade80"}
Its markers are in the map frame — the panel is the map — so a map-frame parameter
needs no offset: here, where the world-frame 3D scene needs one. The map itself must be
a nav map.yaml (image, resolution, origin) beside an 8-bit binary PGM,
which is what map_saver writes; the panel reports anything it cannot read rather than
drawing a map at a guessed origin.
What a variation contributes
The markers are not the panels’ knowledge. A variation type answers
config_view_data() with neutral
geometry — a box at a pose, a polyline, a pose marker — and every panel draws whatever it
is handed. So a panel renders a variation it has never heard of, and a new variation needs
no change in any panel. See Showing what a variation produced for writing one.
Markers can also be declared in the .vast, on either geometry panel and with the same
grammar, which is how a campaign whose factor is a plain parameter list shows its endpoints —
nothing about ParameterVariationList knows about placement, so it contributes nothing:
- scene3d:
markers:
# The robot spawns at world (-8, 0), per the world's spawn_robot plugin.
- {kind: pose, pose: {position: {x: -8.0, y: 0.0}}, label: start, color: "#60a5fa"}
# goal_pose is a MAP-frame pose and map = world + (8, 0) for this world, so the
# marker is shifted back by it.
- {kind: pose, param: goal_pose, offset: [-8.0, 0.0, 0.0], label: goal}
Every field of every panel is bound the same way, and a panel that declares its fields has them checked: a misspelled binding is a validation error naming the valid fields, rather than validating cleanly and leaving the panel silently empty. The four sources are
map: files/depot.yamla literal — written out, the common case;
map: {param: map_file}a resolved scenario parameter, so the field follows the selected configuration;
path: {internal: _path}an
_-prefixed key a variation left on the configuration, named exactly as the configuration carries it;map: {role: map}a named entry of what the variations contributed.
A source naming something a configuration does not have resolves to nothing, and the panel
draws nothing for it — the same rule, and the same reason, as a param: that misses.
Which fields a panel takes is in get_plugin_details("robovast.panel_types", "<type>") and
in the served config schema, so the editor completes them.
A marker states its placement once. pose: writes it out in the shape a .vast states a
placement in everywhere else ({position: {x, y, z}, orientation: {yaw}}, or a bare
{x, y}), and carries the yaw with it; pos: (with yaw:) is the bare-point spelling,
the one SceneMarker itself carries, and stating both is refused.
param: reads a resolved scenario parameter, so the marker follows the selection; one
parameter holding a list of poses yields one numbered marker each. internal: reads a
variation’s own datum the same way — and for kind: path it reads the polyline itself, which
is how a campaign draws a route a variation planned (_path). offset: is a literal
translation applied afterwards — the way a map-frame parameter is placed in a world-frame
scene, declared in the file because nothing in a panel can know a campaign’s frames. A
param: the configuration does not have draws nothing, rather than a marker at the
origin: a pose silently at (0, 0) is a wrong answer, an absent one is a visible question.
label is drawn beside the marker by map2d.
Declared and contributed markers are concatenated, not one overriding the other: a campaign can have both.
See configs/examples/basic_nav/basic_nav_roqsim.vast for the declared form. The
contributed form needs no declaration at all: a map2d panel with no markers: draws
whatever the variations contributed.
Starting it
The service serves the UI itself, so the web frontend comes up together with
robovast-service — there is no separate web server to run or port to expose.
Build the UI once, then start the service:
cd frontend/ui && npm install && npm run build # emits frontend/ui/dist (served by the service)
Open the service URL in a browser and you get the UI; the REST API is served
same-origin under the same URL (OpenAPI at /docs). The in-cluster service
ships the same build in its image, so a deployment needs no extra step.
Accessing it — vast ui
vast ui is a thin shortcut: it opens a browser at the service on the
conventional local port and does nothing else. Something must already be serving
there — a deployment reached over a port-forward, or the published one recorded by
vast login:
kubectl port-forward svc/robovast-service 8800:8800 # this machine's deployment on :8800
vast login <url> # the deployed one, published over its Ingress
vast ui # open a browser at whichever of those answers
This machine — deploy with
vast cluster setup minikube, forward the port, thenvast uito open it (On this machine). If nothing answers,vast uisays so and exits rather than starting anything.Published — deploy and publish it with
vast cluster setup --ingress-host, then openhttps://robovast.<domain>and log in. No kubectl, no kubeconfig, nothing held open.vast login <url>points the CLI and MCP at the same place.Through a tunnel —
ssh -N -L 8800:127.0.0.1:8800 <host>to a machine whose port-forward is up, then openhttp://127.0.0.1:8800. Because that is the conventional port,vast uiand every other command auto-detect the tunnel — nothing to export.
Because the service serves the web UI and the REST API on the same port,
whatever vast ui opens is all a browser, the vast CLI, and the MCP server
need. Other service-touching commands (vast workspace …) resolve the same
target the same way, so nothing needs to be exported.
A connection indicator in the sidebar footer reads disconnected until the
service answers, then becomes a stack of labelled meters showing the backend’s
live resource usage, each with the compact used/total in the bar and a
hover tooltip spelling the numbers out:
CPU and Mem — always shown: the cluster’s node capacity vs. the summed requests of the pods scheduled onto those nodes (runs still queued for a node show up in the jobs meter as pending, not as CPU in use). So on a cluster these meters are what is reserved; what is actually being consumed is on the Admin page’s chart, beside it (see The Admin page).
get_resource_usagereports both readings ascpu_reserved/cpu_measured, either of which is null where the service has no such reading.Jobs — only while there is scenario work, since a permanent
0/0on an empty track was indistinguishable from a dead widget. Its total is the outstanding work (running + pending), not a capacity, so a full bar means the queue has drained.Disk — the filesystem the backend’s runs write into: the filesystem of the node carrying the service pod — the disk its workspaces are a
hostPathon, named in the tooltip. Deliberately not a cluster-wide sum, which would report tens of terabytes free while the one disk that decides whether a campaign can be written filled up. Unlike CPU and memory on a cluster, this is measured usage rather than a sum of pod requests — nothing reserves disk, so a request sum would read near-empty on a full disk.Results — the results volume, where the backend can measure one separately. This is where every campaign lives, so a full one is not merely a slow cluster. It appears only where the volume is a thing of its own — a provisioned claim on the service pod; where the volume is a directory on the service’s node there is no separate figure to report and Disk is already that filesystem.
Beneath them, refusing new work: disk below reserve appears while either meter has less
free space than the reserve the service keeps (ROBOVAST_DISK_RESERVE_GB, see
Deployment Modes and Access); its tooltip is the sentence a refused launch carries.
The last two appear only where the backend can actually report them, and are
absent rather than zero when it cannot: a service older than the fields, a
cluster whose kubelet could not be read (the service needs nodes/proxy; see
Deployment Modes and Access), or a results volume the kubelet reports no separate figure for. get_resource_usage reports the reason when the
backend tried and failed. The reading is sampled at most once every few seconds
and shared across browser tabs, so it never loads the backend.
Note
Every request needs the service’s shared token — a browser presents it as the cookie
/login sets — and a service published over an Ingress insists on TLS. See
Deployment Modes and Access.
Results viewer
The Results tab explores a finished campaign’s data through three sub-views: an Explorer (a campaign → config → run tree with per-node notebook reports — with a batch level between campaign and config for a search campaign), a Run view (a time-driven, panel-based replay of one run — see below), and a Data browser (ad-hoc SQL + charts). Each carries a small icon, used in the sidebar and again on the campaign cards.
The selected result is the URL, down to the run:
#/results/explorer/<campaign> the campaign
#/results/explorer/<campaign>?batch=<i> one search round
#/results/explorer/<campaign>/<config> one configuration
#/results/explorer/<campaign>/<config>/<run> one run
#/results/explorer/<campaign>/<config>/<run>?tab=<name> ...and which of its tabs
#/results/run/<campaign>/<config>/<run> the same run, replayed
So a link addresses a result, not just the campaign that produced it: “look at this run’s
log” is a URL you can paste to someone, and a reload comes back to the same node with the
tree already opened on it. The path is the same <campaign>/<config>/<run> address a run
has on disk and under /results, so there is one spelling to
learn rather than two.
Both views use it, and share it. Pick a run in the Explorer and switch to the Run view and that run is what plays; each has an icon button that hands its node to the other — at the right of the Explorer’s tab row, and left of the Run view’s gear, both carrying the icon of where they lead. Beside it in each sits a second one, Open configuration, on the campaign the selection belongs to (see Reading the configuration a campaign ran) — the campaign’s, so it needs no run selected. The Data browser is campaign-scoped, so it carries no node: stepping through it and back returns to the campaign.
Two things stay out of the path deliberately. The notebook tab is a lens on a node rather
than part of its address, so it is a query parameter (?tab=; the built-in Log tab is
?tab=log, which is why a workload may not be named log). And a batch is a grouping
recorded in the store rather than a directory — a run is identified by its config and index alone
— so it appears only when a batch node is itself the thing selected. For a config or run it is
looked up, never carried: a second copy of a derivable fact is one that can disagree.
A URL naming a config or run the campaign does not have falls back to the campaign node. A finished campaign’s structure is fixed, so that is a wrong link rather than a stale one, and nothing keeps re-checking it.
Each campaign card in Campaigns also offers shortcuts — in its actions menu (the ☰ button) — that jump straight into the Explorer or the Run view for that campaign. A card only offers what it can deliver: Open in Results Explorer once the campaign is finished and postprocessed (the same gate the Results tab itself applies), and Open in Run view only if the campaign also recorded runs to replay. The Run view’s entry appears while the campaign is still running too, reading Open in Run View (preview) — it leads to a replay of the runs that have already finished (see Previewing a campaign that is still running), and it is the only route to one, since the jobs list above drops a run as soon as it completes. The Run view is also a play-icon button on the card itself, first among its controls, shown under the same condition as its menu entry, folded or open: replaying a run is what a reader most often opens a campaign for. Everything else stays a named line in the menu rather than a row of icon buttons: a list whose rows are meant to be scanned cannot also carry five same-sized glyphs per row that have to be learnt before they can be used. Changing the selection inside a view updates the URL without adding a browser-history step, so Back always returns to where you came from in one press; a jump between views is a real step, so Back returns to the view you left.
Reading the configuration a campaign ran
Open configuration opens Config on a campaign’s frozen _config/ — the configuration
it was actually staged with — at #/config/campaign/<campaign_id>. It is offered from a
campaign card’s actions menu, and as an icon button in the Explorer and the Run view on the
campaign whose result is on screen. It appears once the campaign can have that snapshot at
all and stays for the rest of its life, so the configuration of a campaign that is still
running can be read while it runs.
Two phases are before that point and every route to it is hidden through both. A run stages
_config/ when its first batch is prepared; a campaign taken in from an archive has it
once the bytes land, and is listed at importing from before the first of them arrives —
its campaign directory does not exist yet. The run’s gate is one-way: the controller advances
to running before that first batch is staged, so the entry can still be offered a little
early. The Config view reports that as what it is — the configuration is not staged yet, with
a Retry — rather than as a campaign that never froze one. The two absences look identical
from a listing, and only the campaign’s phase separates them.
This is not a workspace, and it is deliberately not in the workspace picker. It is
served from the read-only results tree (/results/<campaign_id>/_config/, which has no
write route at all), and those links are the only way to it: clicking Config in the
sidebar always returns to your workspaces. Where a workspace has its picker, the header
names what is on screen — <campaign_id>/<file>.vast (read-only) — and the editor takes
no cursor at all: a caret blinking in a YAML buffer is an invitation to type an edit that
would then be refused.
Two things are unavailable in that mode, and both for the same reason: live validation and
Generate are workspace operations, and validating the snapshot in place would be wrong
anyway — _config/ archives the scenario at its basename while a .vast may declare
scenarios/foo.osc, so it would report a scenario that is plainly there as missing.
Create workspace from this is the way on: it reconstructs the snapshot into a new,
ordinary workspace — placing the scenario where the .vast declares it, the same
reconstruction Retrigger campaign performs — and refuses, creating
nothing, if the snapshot is short a file its own run used. From there everything works
normally, and launching it starts a campaign of your own rather than editing a record of
one that already ran.
Explorer. The tree shows each campaign’s configs and runs with a pass/fail status
dot; selecting a node opens its details on the right. When a campaign declares
evaluation notebooks under
visualization.results.explorer.notebooks, each workload appears as a tab, and the notebook for
the selected node’s level (campaign / batch / config / run) is executed server-side and
shown as a rendered HTML page. The notebook’s DATA_DIR is set to the selected node’s
directory (see Writing Evaluation Notebooks). Output is cached, so re-selecting a
node is instant. The selected node is URL-carried and shared with the Run view, so selecting a
run here is the run that replays there (see above); the Data browser takes only the campaign.
Search campaigns group by batch. A search proposes its configurations one round at a
time, so a flat config list buries the very thing that says whether the search worked. For
a campaign whose mode is search the tree therefore inserts a batch node per
ask/tell round: each carries the round’s pass tally and its best objective, and each config
below it is labeled with its own objective. A batch-mode campaign has exactly one round,
so it is left flat — grouping it would add a node that says nothing.
A batch is a grouping recorded in the store, not a directory: a search’s configs sit
flat under the campaign root whichever round proposed them. A batch notebook is
therefore given the campaign root as its DATA_DIR and told which round through an
injected BATCH index. See evaluation notebooks for how to
declare one.
After the declared workloads comes a built-in Log tab, which needs nothing in the .vast.
It shows the same merged log as the run-view panel — same filters, same colors — over whatever
the selected node scopes to, and it is where the cross-run question lives, because a run view
can only ever show one run:
a run node — that run’s lines;
a config node — every run of it, with a
run_idcolumn;the campaign — a search across every run at once, reporting hits per run joined to each run’s verdict, so “which runs logged this, and did they fail?” is one query. Click a row to read that run’s log, and the trail back to the search stays.
There is no playback clock here, so the view drops the graying and the jump button rather than implying a position it does not have.
Data browser. The left panel lists the campaign’s tables in the results
index — one per metric CSV, plus the runs dimension table
(per-run status/duration_s and each varied parameter as a param_*
column), with campaign.db attached as schema campaign. Write read-only SQL
in the editor and Run it; the result shows as a table and, via the chart builder,
as a chart — pick x / y / color columns and a mark. Join runs to any metric
table on (config_name, run_id) to answer “how does <param> affect <metric>”.
The campaign’s databases are files in its own directory on the service’s results tree, so a first query transfers nothing and waits for nothing — there is no cache to warm and no state a view has to explain before it runs.
Note
A campaign only becomes queryable once analysis postprocessing has run — it
derives its tables from the raw rosbags and loads them into the index. Launching with Postprocess when done
(the default) runs it automatically on both backends; otherwise the Results tab
offers a Run postprocessing button, and the CLI equivalent is
vast campaign postprocess <id>. To change the postprocessing
parameters and re-run, use Retrigger postprocessing in the Monitor view’s
campaign actions menu (see above). The rosbag→CSV step always runs in
the campaign’s own execution image, as a Job,
because rosbags only deserialize where the system-under-test’s ROS2 message types
are defined.
Declared plots. A campaign can carry its own saved plots, authored in the
.vast under visualization.results.data_browser.plots (analogous to referencing analysis notebooks).
Each plot is a SQL query plus a Vega-Lite
encoding; the viewer runs the query and binds the result rows into the spec as
data.values — so the query’s column aliases are the Vega-Lite field names and
no data block is written:
visualization:
results:
data_browser:
plots:
- title: "Landing error vs wind speed"
query: >
SELECT r.param_wind_speed AS wind_speed,
m.value AS landing_error,
r.config_name AS config
FROM runs r
JOIN landing_error m ON (m.config_name = r.config_name AND m.run_id = r.run_id)
vega_lite:
mark: point
encoding:
x: { field: wind_speed, type: quantitative }
y: { field: landing_error, type: quantitative }
color: { field: config, type: nominal }
Declared plots render automatically in the Results tab for that campaign, and are
schema-validated with the rest of the .vast in the Config editor.
These are campaign-scoped: one query across every run, rendered in the Data browser. For the same Vega-Lite authoring against a single run, on the replay timeline and with a playback cursor, see the vega run-view panel.
The same SQL surface is available to an LLM through the MCP describe_campaign_data
/ query_campaign_data_sql tools, which resolve locally or delegate to a configured
service — so CLI, MCP, and the web UI read results the same way.
Run view
The Run view replays a single run of a postprocessed campaign over its rosbag timeline. You pick a campaign and a run; the view then lays out a set of panels that a shared playback clock drives — dragging the timeline moves every panel to the same instant. All panels read only the run’s recorded results — its postprocessed tables, plus per-run artifact files such as the 3D scene descriptor (there is no live connection to the system-under-test).
The run picker lists only campaigns that actually recorded runs (num_runs > 0,
tallied from campaign.db). A campaign that never started, or that ended before its
campaign.db was written, has nothing to replay, so it is not offered here at all — rather
than being selectable and then answering with an empty view.
Previewing a campaign that is still running
A campaign’s finished runs can be replayed while the rest of it is still running, as a preview. This is the only way to see one at all before the campaign ends: the Monitor’s jobs list is live-only, so a run leaves it the moment it completes, and the other Results views wait for postprocessing.
Only the 3D replay works. scene3d reads a run’s own capture/capture.json and a scene
descriptor compiled on demand, neither of which needs postprocessing; every other panel reads the
index, and a running campaign has no rows there at all — they are written when postprocessing
ingests the campaign. So the preview mounts the 3D scene and the playback transport and leaves the
rest out, rather than mounting panels that could only report the same failure once each per run.
That is also why a campaign is offered as a preview only if it has a scene to replay. A
simulator that records no capture contributes no scene3d, so there would be nothing at all to
show; such a campaign simply does not appear — in the run picker or in its card’s menu — until it
has finished, when its real results exist. Both surfaces ask the campaign’s served panel list, so
neither can offer what the other refuses.
Having a scene is the only extra condition: a campaign is offered as soon as it is running,
without asking how many runs it has recorded. That question has no cheap honest answer while a
campaign runs — the run counts come from campaign.db, which the controller writes only once a
batch has finished, and a batch-mode campaign has exactly one batch — so a preview gated on them
was unreachable for the entire life of exactly the campaigns it exists for. What runs there are is
answered where it can be answered: by the listing that fills the picker. A campaign on its first run
is therefore offered, and says so.
For the same reason there is no verdict to trim to, so the shutdown toggle
reports nothing to trim, and Edit visualization is disabled — saving writes a .vast override
into the campaign’s own _config/, which its remaining runs are configured from, so editing the
view would edit the experiment.
It says so in both places it can be misread: a Preview chip at the top right of the scene, whose
hover explains what is and is not available, and the word preview beside the campaign in the run
picker, where the campaign is actually chosen.
The picker’s rows come from the campaign’s output directories, because the query the Explorer uses answers nothing for a campaign that has not been ingested: one listing for its configurations, then one recursive listing per configuration. That second listing is where the trade is made — a request per configuration either way, and the recursive answer says not only which runs exist but which have written a recording, so it costs response size rather than round trips, bounded by one configuration rather than the whole campaign.
Only runs that can be replayed are offered, and a configuration with none of them is not shown at all. A run still in progress has a directory and no recording; listing it would fill the picker with rows that report they have nothing to show once they are opened, which on a campaign of several configurations is most of the tree. The presence of the recording is exact — it is written once, at a run’s clean stop — so this neither offers a half-written run nor hides a finished one.
The rows carry no verdict: pass/fail lives in each run’s own report, so colouring the dots would
cost a read per run, the shape that does not scale. The dot therefore stays neutral, and a
configuration shows how many runs it has rather than a 0/N that would be indistinguishable from
every run having failed.
When the campaign finishes, nothing swaps under the reader: the Refresh button beside the picker reports that there is something new, and taking it re-reads the campaign with all of its panels.
The run ends at its scenario’s verdict. The gear at the right of the header opens the run view’s settings, and its Include shutdown phase entry decides whether “this run” means the trial or the whole recording. It is off by default — everything after the verdict is teardown: nodes being killed, lifecycle transitions failing because their peer is already gone, TF errors from a publisher that has stopped. It is minutes of wall time, it colors the log red, and it describes nothing that happened during the run.
It governs the view rather than a panel, which is why it sits in the header and neither the playback bar nor the log panel carries a toggle of its own: with the shutdown hidden, the timeline stops at the verdict (so the duration readout is the trial’s) and the log stops there too. Tick the entry and the full recording returns, with a divider on the playback bar marking where the trial ended.
A menu rather than a bare icon because it is a view-wide setting, the same shape the campaign row’s gear uses: the header is otherwise a row of labeled controls, and each further such setting would add another icon to decode. The entries are named in words, and the menu grows without widening the header.
Reset 3D view is the same menu’s second entry, below a divider because it is an action rather than a setting: it puts the 3D scene panel’s camera back where the scene opened — the world’s own baked view — and is over. It is the way back from a lost view, and it exists because there is no way back by hand: the wheel flies, so a few notches aimed at a wall can leave the camera inside geometry or far enough out that the world is a dot. It is enabled while such a view is mounted and disabled, with that reason on hover, in a run view that has no 3D panel.
It sits in the header rather than on the panel for the mirror image of the reason above: the camera belongs to one panel, but that panel is the full-bleed base layer and carries no header of its own, and a button floating over the world would sit in front of the very thing it acts on.
The moment itself is read from scenario_timestamps, written once by postprocessing —
the same row search_run_logs cuts on, so the web UI and the MCP tools cannot disagree
about where a run ended. A run that reached no verdict, and a campaign postprocessed before
the verdict was recorded, leave the control disabled with that reason on hover: nothing is
trimmed, rather than trimmed to a guess.
Which panels appear, where they sit, and where each gets its data are declared in the
.vast under a top-level visualization.results.run_view.panels list — the campaign author defines
the view once and every run of the campaign replays through it:
visualization:
results:
run_view:
panels:
- costmap:
title: Nav2 costmaps
position: { anchor: top-right, width: 440, height: 440 }
minimizable: true
layers:
map: { topic: /map }
global: { topic: /global_costmap/costmap }
local: { topic: /local_costmap/costmap }
poses: { table: poses } # TF source for placing/moving layers
- scenario_tree:
position: { anchor: left, width: 320 }
source: { table: behaviors }
- camera:
title: Camera
position: { fill: true } # everything the docked panels leave over
source: { topic: /camera/image_raw }
Each panel entry is a single-key mapping — the key is the panel type (selecting the
panel plugin) and its value holds that panel’s fields: an optional title, a
position (an anchor — bottom/top/left/right, a corner,
top-center/bottom-center/left-center/right-center, or center — plus
width/height in pixels or a "40%" string; or fill: true instead of an
anchor), the toggles minimizable/minimized/hidden/fixed, and panel-specific
data bindings (which results table or recorded topic each piece of data comes from).
Any field you omit falls back to the panel type’s built-in default, so a bare log:
on its own is a complete panel.
Two panels are there without being declared. The playback transport bar always: a run
view without it has no clock to scrub and every other panel nothing to follow, so it is not a
decision a .vast gets to make or a line it should have to copy. And a scene3d for a
simulator that records a run capture (roqsim does; Gazebo has no scene export and so offers
none) — the panel that replays what those runs always write. Declare either one explicitly only
to change it: an entry of your own keeps its position and its fields, exactly as an authored
execution.env wins over a backend’s. A campaign with no visualization block at all still
opens on a working transport bar.
The transport does not count as something to look at — it is the clock, not content — so the view
offers help authoring panels only when it is genuinely all there is. A simulator that contributes a
scene3d has a run view worth watching and is not asked to declare one; declaring only
playback yourself, to move the bar, still leaves nothing to watch and still gets the notice.
Docked panels reserve the space they occupy, and everything else is placed in what is
left. A top/bottom bar reserves its height and spans the full width; a
left/right column reserves its width and lives in the band between the bars. Both
count in pixels or percent. Combinations that could not be honored are rejected when the
campaign is validated rather than quietly ignored — a width on a full-width top bar,
for instance.
Docked panels always stack vertically, but the two kinds of side differ in what they
reserve. A bar owns the full width, so bars can only stack one below the other and the side
reserves the sum of their heights. A column owns the full height, so several
anchor: left panels tile down one gutter rather than sitting beside each other, and the
side reserves the widest of them, once — which is how a sidebar of two panels leaves a
single 320 px margin, not two.
A dock reserves a few pixels more than its own size, so neighboring panels never touch: the gap sits between a column and what is beside it, between a bar and what is above it, and between the members of one column. Panels still sit flush against the view’s outer edges — it is a gap between panels, not a margin around the page.
Size a column’s members by ratio, by pixels, or not at all:
- nav2_behavior_tree: {position: {anchor: left, width: 320, height: "50%"}}
- scenario_tree: {position: {anchor: left, width: 320}} # takes the rest
A percentage on a column member is a fraction of the column, not of the view — two
members at "50%" come out the same height and tile it exactly, gap included, with no
arithmetic to subtract the playback bar. This
is the only place a percentage is measured against something other than the whole view: a
bar’s height: "8%" and a column’s width: "25%" are both of the view, which is their
natural reading. A member with no height takes whatever the members above it left, so
only the last member of a side may omit it; declaring another panel after it is refused at
validation rather than silently stacking one on top of the other.
The four -center anchors differ from the matching dock in one way that matters:
bottom docks at the very edge and reserves its height, which is what the playback bar
does. bottom-center floats above that reserved band, centered on the free width, and
reserves nothing itself — so it shares the bottom edge with the playback bar instead of
covering it. It needs a declared size (a full-width one is just bottom). The pinned edge
is the one the anchor is named after, so minimized collapses the panel towards that edge
and expands it back away from it. The corners behave the same way, and both float 12 px
inside the reserved bands where a docked column sits flush against the edge.
fill: true is used instead of an anchor: the panel takes the whole rectangle the
docked panels leave over, and needs no width/height — those come from the docks
around it. It sits beneath the floating panels, so corners and -center panels overlay it.
Only one panel per view may declare it; a second would occupy the same rectangle invisibly,
and is refused at validation.
Some panels are contributed by the simulator backend and need no entry at all. A backend
whose runs always record the capture the scene3d panel replays supplies that panel the same
way it supplies the environment that produces the capture — there is nothing to decide, so
there is nothing to declare. Declaring it yourself still wins, which is how you place it
somewhere other than the base layer.
The declared layout is where the panels start, not where they are stuck:
Move — press the mouse on a panel’s title bar, drag, and release to drop it there. A moved panel is raised above the others, and always keeps an edge inside the view so it can be grabbed back.
Resize — drag any edge or corner of a panel. The edge you grab is the one that moves and the opposite one stays put, so a
leftcolumn can be widened from its right edge or its left, and abottom-rightpanel from any of its four sides. Aleft/rightcolumn with no declaredheightspans the view; dragging its bottom edge is what gives it one. An axis a panel gets no size along has no handle — a full-widthtopbar’s width is ignored by the layout, so it is resized by height alone.
Panels that show no title bar cannot be moved — the docked playback transport and a base
layer such as scene3d stay put. A fill: true panel is sized by the docks around it, so
it has no free edge to drag either. Everything else is movable and resizable unless the
.vast says otherwise: fixed: true locks a panel’s geometry outright, and
resizable: false is the narrower opt-out for one that may be moved but not resized.
These are view-local adjustments: they last as long as the view is open, and reloading it
(or switching runs) restores the layout the .vast declares. The space a dock reserves is
the one the .vast declares too, so resizing or minimizing a docked bar or column in the
view does not re-flow the panels around it. To change the layout for good, edit it under
Edit visualization.
The built-in panels:
Playback (playback) — a transport bar spanning the bottom: a click-to-seek
progress bar, an icon play/pause, a fast-forward button, and a current / total
time label. Fast-forward steps the playback speed through 1×, 2×, 4× and 8× and back to 1×,
with the active speed shown beside it; pressed while paused, it also starts playback, so the
button never pauses. The bar owns the clock; every other panel follows it, which is why it is
contributed to every campaign rather than declared — see above. The timeline range comes from the run
capture’s own time base when a scene3d panel declares one (the run’s ground truth, and available
before any postprocessing), else from an explicit visualization.results.run_view.timeline, else from the union of the
postprocessed poses / behaviors / scenario_timestamps timestamps.
That range is the whole recording; where the trial ended is a separate figure, so the shutdown toggle can shorten the timeline and restore it without re-querying anything. While the shutdown phase is shown, the bar draws a full-height divider at the verdict — with it hidden the verdict is the end of the bar, and a line there would mark nothing.
Costmaps (costmap) — an rviz-style top-down view of what nav2 saw: the static
map, the global and local costmaps, the actual path the robot drove, and the robot
marker, all at the current time (scroll to zoom, drag to pan). Each layers entry
binds a name to a costmap topic; poses (the TF table) both places the layers into
the map frame and provides the driven-path trail + robot pose. It requires the
costmap postprocessing step — if the costmaps data is
missing the panel says so rather than drawing nothing.
A layer is left out, and named in the top-left corner (“local: nearest frame 4.3 s away”), when the recording genuinely has no frame near the cursor — before nav2 starts publishing, after it stops, or across a gap mid-run — rather than showing the closest frame it could find as though it were current. Each layer is judged against its own publish rate, so a static map, published once and never again, is never affected.
While scrubbing, layers keep showing their last frame instead of blanking: a replacement is
already being fetched, and the layers differ enough in weight (a full-map global costmap is
~15 KB against a local costmap’s sub-KB) that blanking during the catch-up would make the
heaviest one flicker. Note also that a costmap is placed at the time it was published, so at
speed the robot marker can sit slightly ahead of its window — that offset is the recording’s
own resolution, not drift. This panel ships with the
robovast_nav package (not the core UI) as a package-provided panel — see below — so
it is available whenever robovast_nav is installed; the .vast still references it
as plain - costmap:. The same package draws the same picture onto a rendered video of
the run (the costmap video overlay).
Camera (camera) — a camera that was recorded during the run, played on the
playback clock. This is what a simulator with no 3D scene has instead of one: Gazebo writes
no run capture and has no scene exporter, so a scene3d panel has
nothing to replay there, while a monitor camera spawned into the world gives that run view a
picture of the trial.
It needs no bindings — a bare - camera: is a complete panel whenever the run registered
exactly one video, the same promise scene3d makes. source: { topic: … } picks one when
a run recorded several; source: { path: …, t0: … } is the escape hatch for a video no
producer registered, and needs t0 because a file with no entry in the videos table
carries nothing that says where it sits on the timeline.
The panel is a reader of the clock and never a writer, so it shows no controls of its own: the playback bar owns time and this follows it, including at 2×. Seeking happens only when the element drifts more than about one frame from the cursor, so ordinary playback is not a seek storm. Outside the recording — a camera that came up late, a trial that ran past the last frame — it dims and says “No frames at this time” rather than showing frame 0 as though it were the current moment.
Where the video comes from: a producer writes it into the run directory and registers it in
the videos table. rosbags_to_webm is the first such producer (see the
worked example), but the table is a contract any of them may write.
Two properties worth knowing. The encode is constant-rate — fps is derived so the
first and last frames land exactly on their recorded moments, so only mid-run jitter drifts,
which is sub-second at a monitor camera’s 1 Hz. And seeking is efficient: the file is
served with FileResponse from the run directory on the service’s disk, so the browser
ranges into it.
Scenario tree (scenario_tree) — an rviz-scenario-execution-style behaviour tree
that colors each node by its status (running / success / failure) at the current time.
It reads the behaviors table, written by scenario_execution on every run (no ROS
required). Where the data supports it, each node
also shows its kind (sequence / selector / parallel / decorator), its feedback message at
the current time, and — on hover — its class and the .osc file and line it came from;
when a tree ends in failure the panel names the action responsible, via tip_id.
Double-clicking a node seeks playback to the moment that node next changes status — so on an
inactive wait_for_pick the first double-click lands exactly where it starts running, the next
on where it succeeded or failed, and a further one wraps back to its first change. Playback pauses
on the jump, and only real status transitions count: a node re-reporting RUNNING with a new
feedback message is not a stop.
The panel renders any table in the behaviors schema — point it at another with
source: { table: <name> }. Columns a table does not have are simply not shown, so an
older or differently-produced table still renders.
Run log (log) — everything the run said, following the playback cursor. One row per log
event from every container, joined with /rosout and placed on the run’s clock (see
run_log — everything the run said). Lines not yet logged at the cursor are grayed out with a divider marking
“now”, so the log’s whole shape stays visible while the position in it is unambiguous.
Filtering is instant and client-side, over the whole loaded log: a text box (substring, or a
regular expression with the .* toggle), two severity chips that cycle
off → highlight → only these, and one dropdown listing every container, ROS node and
source this run actually produced, with counts. Clicking a line seeks playback to it, and
the ▲▼ buttons jump to the previous/next warning or error — which is what turns a filter into
navigation. Scrolling away stops the follow and raises a button showing the cursor’s time; click
it (or press Escape) to jump back and resume following.
The log also stops at the scenario’s verdict. In the run view that is the header gear’s
Include shutdown phase entry and this panel shows no control of its own
— one question, one place to answer it. The Explorer’s Log tab has no run view around it, so it
carries a power icon for the same setting in its own filter bar. Either way the cut is on the
verdict’s wall time and not its sim time: the clock map does not extrapolate, so lines after
/clock stopped have no sim time at all, and a sim-time cut is blind to exactly the lines
the toggle exists to remove.
Wall time is also what the log is ordered by, which is why those lines sit at the end where they were logged — and not sim time with the rows lacking one placed first, which would read a missing sim time as “logged before the simulator’s clock started”. It does not mean that: the clock map is silent at both ends of its range, so such an order lands a run’s shutdown at the very top of the log, next to the boot lines.
A line with no sim time is dimmed in the time column, and that is the only marking it gets: the figure is the seconds since the run’s first log line, measured on the wall clock, and hovering it says so. Nothing is prefixed to it, so a column of monospace figures keeps its alignment.
A log covering more than one run (a config’s, or the Explorer’s whole campaign) is ordered by run
first, so it reads as one run after another instead of interleaving runs that each start at zero.
There is no cursor in that view: every run has its own moment 12.5 s, so a single position
cannot point into all of them, and the log is shown plain rather than divided at an arbitrary row.
The footer never stays silent about what is missing: no run_log table (postprocessing predates
it), a run with no clock map (wall time only), how many shutdown lines were hidden and how the
scenario ended, how many lines the filter hid, and whether the load hit its ceiling.
The playback bar itself gains tick marks for every warning and error — full height for errors, half for warnings — so the log’s shape is visible before you scrub into it.
Nav2 behavior tree (nav2_behavior_tree) — the same tree view for nav2’s own
behavior tree, reading the nav2_behaviors table produced by the nav2 BT
postprocessing (rosbags_nav2bt_to_csv + nav2_bt_tree): node status
over time from nav2’s /behavior_tree_log, tree structure from the BT XML nav2 ran.
Declare it as - nav2_behavior_tree: and it brings its own table, title and — when the
table is absent — the nav2 postprocessing steps to add, rather than the scenario’s
bt_log.
This type ships with the robovast_nav package, so it is available whenever that
package is installed, but it is not a second implementation: it renders the built-in panel
above with different defaults, and so gains its behaviour automatically. Both trees can be
shown at once — the scenario’s says what the trial did, nav2’s says why the navigator
recovered. See configs/examples/basic_nav for a complete campaign.
3D scene (scene3d) — the 3D world view, typically the run view’s base layer
(position: { fill: true }): the simulated world’s actual geometry rendered in the browser, with
everything that moved replayed — including articulation, so an arm bends rather than swinging as
one rigid piece.
The mouse bindings:
wheel — fly toward or away from whatever is under the pointer. You steer by aiming: point at a far shelf and scroll, and you arrive at that shelf. The approach slows as you close on it, so a notch crosses open ground quickly and never crosses the surface you are aiming at — and a notch out undoes a notch in exactly.
left-drag — turn about the surface under the pointer. Aimed at a corridor wall a metre away it reads as looking around; aimed at a building across the world it orbits the building.
right-drag — pan sideways and vertically, at roughly the speed of the surface being dragged.
double-click — travel to frame whatever you clicked, without turning the camera.
All three drags are scaled by one number, the distance to the pivot, and the panel re-measures it against the actual geometry whenever a gesture starts. That is what lets a single set of bindings fit a 3 m tabletop and a 65 m building without a mode or a speed setting: a pivot fixed at the distance the world was authored with is right in the opening frame and wrong everywhere you travel to, which is felt as a drag that flings the camera through walls and a wheel that cannot approach one.
The wheel deliberately does not shrink an orbit radius toward a fixed center, which is the usual default and is what makes such a view freeze a short way from that center; here the pivot is re-chosen every gesture and can be flown through. Because it flies without bound, the way back is the header gear’s Reset 3D view entry, which re-frames the camera at the view the world was authored with.
It needs no bindings at all — - scene3d: on its own is a complete panel — because the run’s
capture names the world it used and the service builds the matching geometry on demand. Both
artifacts are specified in Replay artifacts: the scene and the capture.
Geometry is compiled when somebody looks, not when a campaign runs. A descriptor is 13–31 MB and takes
5–9 s to compile, for an artifact whose only consumer is this panel — so a campaign does not ship one.
On the first view the service compiles it inside that campaign’s own pinned image (the world is
generally installed there from a wheel, and a host that merely happens to have the tooling could be a
different version, which renders plausible but wrong geometry) and caches it keyed by world identity:
image digest + world reference + world_overrides. Every later view is a read from disk — and so is
the first view of every other run, and every other campaign that used the same world. A 25-run sweep
compiles once, not 25 times.
Because a build is seconds (≈8 s on a warm cluster node) and can be a couple of minutes when the node must first pull the image, the panel names what it is waiting for rather than spinning: Waiting for a node to build on, Fetching the simulation image onto the node, Starting the build container, Compiling the world geometry. Each is reported by whoever performs it — on a cluster the build runs in a pod on the campaign’s own image, and the pod is the only thing that knows which of those it is on — so the stage is read rather than assumed.
Under the stage, when the cluster has one, comes its own words for the wait: the pod’s
ImagePullBackOff and the registry’s message, say. That is the difference between a cold start and a
wait that will never end, and it is the case to know about for a campaign imported from another
cluster: geometry is compiled in the image that campaign recorded, which is a reference into the
registry it ran against. Where this host cannot pull that image there is no 3D view for that campaign,
and the panel now says so in seconds instead of at the build’s deadline. Nothing else about the campaign
is affected — its logs, tables, plots and capture playback need no image.
The rest of the run view stays usable meanwhile — the capture, the timeline and the table-fed panels need no geometry, so playback and the costmap keep working — and a failure stops polling and shows its reason.
Nothing is listed under the panel. A capture’s tracks name the joints and bodies they drive exactly as
the descriptor spells them, so what gets animated is discovered from the artifact pair; a track matching
nothing is reported, with the capture’s own world and producer, rather than leaving a silently
static world.
Note
The panel does not animate from the postprocessed poses table (rosbags_tf_to_csv): that
would need a rosbag before anything moved, impose a naming contract on the simulator plus a
bind list for its exceptions, and could only place bodies parented to the world — so an
articulated robot would replay rigid. Nor is there a scene.scope/capture.scope to declare:
geometry is resolved by content key, so there is nothing to declare, and nothing to declare
wrongly (a campaign-scope descriptor aimed at a world that varies per configuration renders
confidently wrong geometry, and no validation could catch it). The poses table itself serves
the costmap panel and timeseries.
execution.generate is supported for a campaign that wants its descriptor frozen into its
results — an archive that must replay even without the image — but it is not how the run view
obtains geometry.
2D scene (scene) — a top-down/side 2D plot of “where the thing is right now”: one
column against another (e.g. a quadrotor’s x vs altitude z) from any table with a
time column (source, x, y; trail: false disables the driven path).
Time series (timeseries) — a chart of one or more numeric columns over the run’s
timeline with a cursor at the current time (source + a series list of
{ column, label }).
Every panel binding a source takes decimate_hz (and key) with it, on the same terms as
the vega panel below: a run longer than the row cap is cut at the head unless it
is thinned.
State (state) — the current numeric values of selected columns as labeled
read-outs (source + fields of { column, label, unit }).
Vega chart (vega) — any diagram, declared as a Vega-Lite spec over one of the run’s results tables. Where
timeseries plots columns that already exist, a spec’s transform can derive what the
run never recorded, and any Vega-Lite mark is available. It binds a source (the same
{ table, time_column, filter, decimate_hz, key } as timeseries, so the run scope, the frame
filter and the thinning all happen in SQL) plus a vega_lite spec, and optionally max_rows
(default 5000, which is also the ceiling — see below).
Which of the two to pick: timeseries is a hand-rolled canvas chart — the cheap path for
numeric columns at high sample rates. vega costs a full Vega render but expresses everything
else.
The spec is bound to two named datasets and so declares no data block of its own:
table— the run’s rows for that table;cursor— a single row{t}at the current playback time.
The playback cursor is layered in automatically, into the top-level spec and into each child of a
vconcat/hconcat/concat — but only where it means something: the spec must be layerable
(mark or layer) and must bind the time column to x or y. A boxplot by frame therefore
gets no cursor, and facet/repeat specs are left alone. Reference the cursor dataset
yourself to place it anywhere else.
Three things to know when charting a poses table, because every such spec hits them:
Dotted column names.
rosbags_tf_to_csvwritesposition.x/orientation.yaw, and a Vega-Litefieldreads a dot as a nested path. Either escape it (position\.x) or — usually clearer — hoist it to a flat name in acalculatetransform:datum['position.x'].A TEXT column stays TEXT. The panel coerces each column whose values all parse as finite numbers, so
type: quantitativeworks without aformat.parseblock.A long run needs ``decimate_hz``, not a bigger ``max_rows``. The row cap is a
LIMITapplied afterORDER BYtime, so a run that outgrows it is cut at the head: the chart ends mid-run while looking complete. Raisingmax_rowscannot fix that — the data query clamps at 5000 rows whatever a panel asks for, which is whyvast config validaterejects a larger one.source: {decimate_hz: 5}instead keeps one sample per 1/hz second across the whole run, in SQL. Rule of thumb:hz ≈ 4000 / run seconds; a 460×380 panel resolves nothing past a few hundred points anyway. The panel says so itself when a query is truncated.On a multi-keyed table (
posesis keyed byframe) eitherfilterdown to one series, as the example below does, or name the key —source: {decimate_hz: 5, key: frame}. Without one of those, each time bucket keeps a single row from a single frame and the other frames vanish entirely rather than being thinned. Thinning also assumes a numeric time column: an ISO-8601timestampcasts to 0 and lands the whole run in one bucket.
A worked example over a poses table — derived speed above the raw pose, sharing one time axis, so
both charts get a cursor:
- vega:
title: base_link
position: {anchor: bottom-right, width: 460, height: 380}
source: {table: poses, filter: {frame: base_link}, decimate_hz: 5}
vega_lite:
resolve: {scale: {x: shared}}
transform:
- {calculate: "datum['position.x']", as: px}
- {calculate: "datum['position.y']", as: py}
- window: # previous sample, to difference against
- {op: lag, field: px, as: px0}
- {op: lag, field: py, as: py0}
- {op: lag, field: timestamp, as: t0}
sort: [{field: timestamp}]
- filter: "isValid(datum.t0)" # the first sample has no predecessor
- calculate: >
sqrt(pow(datum.px - datum.px0, 2) + pow(datum.py - datum.py0, 2))
/ max(datum.timestamp - datum.t0, 1e-6)
as: speed
- window: [{op: mean, field: speed, as: speed_avg}] # differencing TF is noisy
frame: [-9, 0]
sort: [{field: timestamp}]
vconcat:
- height: 150
encoding:
x: {field: timestamp, type: quantitative, axis: null}
y: {field: speed_avg, type: quantitative, title: "speed [m/s]"}
mark: {type: line, strokeWidth: 1.5}
- height: 120
transform: [{fold: [px, py], as: [series, value]}]
mark: {type: line, strokeWidth: 1.5}
encoding:
x: {field: timestamp, type: quantitative, title: "t [s]"}
y: {field: value, type: quantitative, title: pose}
color: {field: series, type: nominal}
This is the same authoring language as the campaign-scoped declared plots above; the difference is scope and binding — visualization.results.data_browser.plots runs a SQL query
across the whole campaign and renders in the Data browser, while a vega panel binds one table of
one run and renders in the Run view.
Custom and package-provided panels
The panel types above are the ones bundled into the core UI, but the run view is not
limited to them. A panel can also be loaded at runtime from outside the core UI as a
Module-Federation remote — a small pre-built JavaScript
bundle. This is how the costmap panel ships from robovast_nav rather than the core
UI, and it is also how you can add a bespoke visualization to a run view. Either way, in
the .vast a panel is always referenced by a type name the same way — where the
code lives is invisible to the config:
Package-provided — an installed plugin package registers a panel in the
robovast.panel_typesentry-point group and ships its built bundle as package data. Reference it by its registered type name (- costmap:); it is available to every campaign once the package is installed.User-authored (
custom) — you build your own panel bundle and drop it next to the.vast, referencing it by path:visualization: results: run_view: panels: - custom: remote: panels/my_panel # dir (or remoteEntry.js) relative to the .vast module: ./myPanel # the exposed module (default ./panel) title: My view position: { anchor: right, width: 420 } # any further keys are panel-specific data bindings (as for built-ins)
Writing a panel. A panel is a React component implementing the same contract the
built-ins use — ({ spec, clock, data }) => JSX — so it is time-synced and reads the
run’s results tables exactly like a built-in: clock.t / clock.subscribe(...) for the
current playback time, data.series(table) / data.nearest(table, t) for run rows,
spec.config for the panel’s .vast bindings. A panel needing a specialized endpoint
(as the costmap panel needs nav2 grids) reaches it through the generic run-scoped
data.fetchRun(endpoint, params) — the run view core stays free of panel-specific
knowledge. Build the component as a Module-Federation remote exposing that module, with
react/react-dom marked as shared singletons pinned to the host’s version
(^18); a broken or missing bundle shows an inline error, never a silent blank. See
src/robovast_nav/web for the reference build (the costmap panel) to copy from,
and the developer guide for the internals.
Several panels in one package. A package that ships more than one panel builds them into
a single Module-Federation container exposing one module per panel, and each panel’s type
class sets a shared REMOTE_NAME (the container name) so the service points every type at
the one bundle. Adding a panel is then one more exposes entry plus one panel class — no
new build, and React/vendor chunks stay shared.
Before writing a renderer, check whether a built-in panel already draws your data. A
package whose data is a table in an existing schema should still ship its own type — so a
.vast names it and gets its table, title and empty-state guidance — but that type can
derive from a built-in panel instead of reimplementing one. The host passes its own panel
components to a remote as props.builtins; robovast_nav’s nav2_behavior_tree is a few
lines that render builtins.ScenarioTree with nav2’s defaults, and inherits every later
improvement to it. Write a renderer only when the host cannot draw the data at all — costmap,
whose binary grids need their own endpoint.
Serving a panel’s data. A panel reads the run’s postprocessed rows through data
(fetchRun for anything beyond plain table rows). When that data comes from a table your own
postprocessing step produced and needs custom serving (untruncated blobs, nearest-frame
selection, …), a package can also ship the endpoint: a small class registered in the
robovast.service_endpoints entry-point group, serving GET /campaigns/{id}/<name> from the
campaign’s data — no core change. So an analysis package can own the whole chain end-to-end — postprocessing step →
service endpoint → panel — with nothing in core. The costmap panel is exactly this: its
rosbags_costmap_to_csv step, its costmap endpoint, and its panel all ship in
robovast_nav. (Large binary artifacts don’t even need an endpoint — serve them as ordinary files
via data.runFileUrl(path) for one run’s, or data.campaignFileUrl(path) for one the whole
campaign shares, as the scene3d panel does.) See the developer guide for the endpoint contract.
3D scene data delivery. The scene3d panel renders a scene descriptor — scene.json +
scene.bin + one PNG per texture, a compact browser-renderable export of the simulated world, defined
in Replay artifacts: the scene and the capture and produced for roqsim by roqsim/export_web.py. It is a directory, not a file: the
loader fetches scene.bin and the textures as relative siblings of scene.json.
A campaign does not deliver it. The service resolves it per view:
GET /campaigns/{id}/scene?config_name=&run_id= status only; never starts a build
POST /campaigns/{id}/scene/run the explicit trigger
GET /campaigns/{id}/scene_assets/{key}/{file} the bytes, from the shared cache
The split matters: a GET that started a build would fire on a browser prefetch or a React
strict-mode double render, and each of those would launch an image pull. Status is its own
cheap GET (say why you are about to wait, before you wait), starting work is a POST returning
ActionResult as postprocessing/run is, and the bytes are served like a panel bundle because they
live in the service’s cache rather than in the campaign’s results. The cache key is in the asset path so
one URL prefix addresses the whole entry, which is what makes the loader’s sibling fetches resolve.
Because the key names what an entry was compiled from, and an entry is never rewritten under its key,
an asset URL names its bytes. So the assets are served Cache-Control: private, max-age=31536000,
immutable, and the run view keeps the last parsed scene when the panel is torn down on a run switch:
the next run of the same world is seated in that model — back at rest — with no fetch and no rebuild. Its
status GET is still asked on every switch, since another run may name another world; for a campaign
at rest the service answers it from a memo kept against the campaign’s record files and the run’s
capture. Files under /results carry no such header: their paths name a location, not the bytes in it.
The cache is shared across campaigns and durable (~/.robovast/cache/scenes, overridable with
ROBOVAST_SCENE_CACHE; size-capped by ROBOVAST_SCENE_CACHE_BYTES, evicted whole-entry
least-recently-used). Two consequences worth knowing:
A campaign whose image is gone — garbage-collected, or a mutable tag rebuilt under the same name — cannot have its geometry rebuilt, and the panel says so rather than showing an empty world. A campaign that records only a mutable tag refuses to cache at all, because an entry keyed on a tag may silently describe different bytes later.
A downloaded or shared campaign has no descriptor in it. If a self-contained archive matters more than laziness, keep an
execution.generateentry for that campaign.
Costmap data delivery. A grid reaches the browser through a step of its own, because
the panel needs the frame whole and with the geometry to draw it against. The
rosbags_costmap_to_csv postprocessing step stores each grid losslessly and
compactly — its int8 cells zlib-compressed — into a costmaps table, together with
the geometry (resolution in m/cell, width/height in cells, so the map spans
width×resolution by height×resolution meters, and the origin pose). Record the
costmap topics in the scenario and add the step to postprocessing:
results_processing:
postprocessing:
- rosbags_tf_to_csv: { frames: [base_link, odom] } # base_link=robot/path, odom=local costmap
- rosbags_costmap_to_csv:
topics: [/map, /global_costmap/costmap, /local_costmap/costmap]
The run-view costmap panel fetches the frame nearest the current time from the campaign
costmap endpoint (delivered untruncated) and inflates it in the browser. The same
geometry is visible to an LLM via MCP describe_campaign_data (the costmaps table
description carries the map’s size in meters, resolution, layers, and delivery), so it can
reason about the run without decoding grids.
The same panel on a rendered video. robovast_nav registers the panel a second
time, as a costmap overlay for roqsim render (roqsim’s roqsim.render_overlays
entry-point group), so a video of the recorded simulation carries the costmap view as an
inset in a corner, in step with the picture because both sides carry simulated seconds:
roqsim render --state run.npz --from onset --overlay costmap --out clip.mp4
roqsim render --state run.npz --overlay '{"costmap": {"anchor": "top-right", "width": 0.3,
"layers": {"map": {"topic": "/map"}, "local": {"topic": "/local_costmap/costmap"},
"poses": {"table": "poses"}}}}' --out clip.mp4
It draws what the panel draws – the layers, the driven trail, the robot – plus what the
config view draws for the configuration: the planned path, goal and obstacles its variations
contributed (planned_path, goal, obstacles, each true unless turned off), and
the markers the campaign declares on its map2d panel – the map-frame
declaration, resolved the same way (param: reads the configuration). A goal that is a
scenario constant rather than a varied parameter is therefore stated once, in the .vast,
and both the config view and the video show it. markers on the overlay takes the same
declarations and replaces the campaign’s (markers: [] draws none).
layers is the panel’s binding, so a set that works in the web UI works here; a layer may
name a map file (campaign-relative) instead of a topic. With no layers stated, the
panel’s default layers are taken as far as the run recorded them – a campaign that stored only
its global costmap gets that one, and the choice is logged – while a stated binding is held to
the letter. It reads files, not the
service: costmaps.csv and poses.csv beside the recording, and the campaign’s
_transient/configurations.yaml and frozen _config/<name>.vast, laid out as the campaign
directory is
(<campaign>/<config>/<run>/) – so a run fetched to disk, or a campaign archive, is enough.
A file it needs and cannot find is refused by name, together with the postprocessing step that
writes it; a costmap in a frame the poses do not carry (the local costmap is in odom) is
refused naming the frames present; and a layer whose nearest frame is further from the
cursor than two of its publish periods is withheld and said in the picture, as the panel does
(stale_after sets the window in seconds).
Development
For UI development with hot reload, run the Vite dev server against a running service:
kubectl port-forward svc/robovast-service 8800:8800 # the service to talk to
cd frontend/ui && npm run dev # in another terminal (Vite on :5173)
The dev server proxies the API path prefixes to the service so the browser stays
same-origin (no CORS). Point it at a different service with
ROBOVAST_SERVICE_URL. See Web UI internals in the developer guide for
the app’s structure and how to extend it.