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_improvement criterion 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_improvement can be “about to fire”. It counts rounds, so its distance is real; target_objective and metric fire 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 batches criterion (the rounds still to come) or a runs one (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 or no_improvement shows 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 declared budget criterion 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 than 100%: 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 reads 99% 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 the stopping ones, the best objective, and the objective-over-rounds chart.

    The scope matters on the hover because a runs budget 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 budget kinds can fill the ring. They are monotone resource caps, so a share of them means something; the three stopping kinds are result-dependent early exits and are not a share of the same thing — no_improvement resets 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.8 beside now 0.1, with a ✓ once it has fired. The comparison is published (BudgetItem.op) because a bare 0.1 / 0.8 silently implies >=, so a metric written <= 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_improvement counting up from zero to its patience (a static row claiming “2 of 3 strikes” survives the reset that rules it out of the ring). A metric and a target_objective get none — knowing a metric fires at <= 0.8 says 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-HHMMSS stamp, 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 .vast it 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 -1 when its priority is not the default 0, and paused when 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 as vast campaign priority|pause|resume (Job Queueing). The entries appear only on a service with a queue, which it reports as can_schedule in /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) and variation (the campaign’s configurations are being expanded), then running → finishing → postprocessing → finished (or failed / stopped). A build that fails is shown as a failed campaign in the list rather than vanishing, and its builder output is in that campaign’s own log under a BUILD divider. The per-batch run bar also distinguishes finished runs (the solid fill) from those currently running (a lighter segment on top), with the exact running N · pending M counts 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 still pending or blocked has 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 the metrics.k8s.io/pods grant – 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 a calibration chip beside its status and named for its node; and while a cluster campaign is in its postprocessing phase it carries the conversion of its rosbags, marked with a postprocessing chip and named rosbag 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’s POSTPROCESSING section 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 as killed (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’s tar.gz straight from the service’s /data/campaigns/{id}/archive route, 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’s vast campaign rerun --check prints), 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 the results_processing.postprocessing block (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 .vast that ran), the edit is written into that file in place: the results_processing.postprocessing block 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 of vast 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 of vast workspace run. Upload to share when done streams a raw, pre-postprocessing tar.gz to 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 .vast editor with live validation, a generated-configuration preview, and a per-configuration view the .vast declares. 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.

Importing from the share

Import from Share, the second entry in the campaign list’s import menu, opens what the configured share holds — read by the service with the service’s own credentials, since a browser has none of its own. Pressing Import on a row has the service fetch that archive, so the bytes never come through your browser, and the dialog closes: the campaign appears in the list at phase importing and its own row is the progress from then on. One import per visit; a refusal instead keeps the dialog open, because a refused import creates no row to be reported on.

It is a menu entry rather than a panel below the campaign list: on a deployment with a hundred campaigns such a panel is off the bottom of the page, collapsed, which is a poor place for the only feature that brings somebody else’s work in — hence a menu entry, a search box, and newest first.

Newest campaign first, ordered by the timestamp inside each campaign id. Not by when the archive was written: no share provider reports a modification time, and when the campaign ran is the more useful fact anyway. The id carries it in plain sight, which is why there is no separate date column.

One row per campaign, and the row says which archive it will fetch. A campaign can be on the share twice — the campaign-end upload writes a raw archive before postprocessing, a later export adds a postprocessed one, and nothing removes the first. The dialog takes the postprocessed archive where there is one, because it arrives complete; a raw one is postprocessed after it lands, so that campaign runs on into a second phase. To name a specific variant, use the CLI: vast share import <campaign-id>.raw.tar.gz.

Campaigns already here are listed too, marked already here with their Import disabled. They are not filtered out, so that a link to a campaign you already have still explains itself.

Copy link on a row copies a URL that opens this dialog with that campaign in the search box — hand it to a colleague and they only have to press Import. The same string works in a terminal: vast share import '<link>' reads it. The link carries this deployment’s address, which is right for colleagues on the same one and wrong for anybody else; a bare campaign id is the portable form.

The share is deliberately not treated as a subset of what this deployment has — the two overlap, and an archive with no campaign here is the ordinary case this dialog exists for, not an anomaly to be filtered out. Nothing about the share is cached on a campaign either: it is another system’s state, and a copy of it would be wrong the first time somebody deleted an archive out of band. When this deployment has no share at all, the menu entry is greyed out — but only then. A listing that is still loading, or one that failed because the share is unreachable, leaves it enabled and the dialog says which happened; greying it out would report a network problem as a deployment without a share.

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 > 1 carries 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 .vast reserved. 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 behaviors table that scenario_execution writes 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 = 1 then 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_bytes is 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

visualization.panels

visualization.results.run_view.panels

visualization.timeline

visualization.results.run_view.timeline

evaluation.visualization

visualization.results.explorer.notebooks

evaluation.plots

visualization.results.data_browser.plots

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.yaml

a 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, then vast ui to open it (On this machine). If nothing answers, vast ui says so and exits rather than starting anything.

  • Published — deploy and publish it with vast cluster setup --ingress-host, then open https://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 open http://127.0.0.1:8800. Because that is the conventional port, vast ui and 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_usage reports both readings as cpu_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/0 on 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 hostPath on, 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_id column;

  • 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 left column can be widened from its right edge or its left, and a bottom-right panel from any of its four sides. A left/right column with no declared height spans the view; dragging its bottom edge is what gives it one. An axis a panel gets no size along has no handle — a full-width top bar’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_csv writes position.x / orientation.yaw, and a Vega-Lite field reads a dot as a nested path. Either escape it (position\.x) or — usually clearer — hoist it to a flat name in a calculate transform: datum['position.x'].

  • A TEXT column stays TEXT. The panel coerces each column whose values all parse as finite numbers, so type: quantitative works without a format.parse block.

  • A long run needs ``decimate_hz``, not a bigger ``max_rows``. The row cap is a LIMIT applied after ORDER BY time, so a run that outgrows it is cut at the head: the chart ends mid-run while looking complete. Raising max_rows cannot fix that — the data query clamps at 5000 rows whatever a panel asks for, which is why vast config validate rejects 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 (poses is keyed by frame) either filter down 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-8601 timestamp casts 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_types entry-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.generate entry 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.