Labs Serve UI

The Labs Serve UI is the bundled local web interface for runnable Biosimulant labs. It is served by the open-source biosimulant Python package and does not require a separate frontend package or Python extra.

Start the UI

pipx install biosimulant
biosimulant labs init ./serve-check --name "Serve Check"
biosimulant labs serve ./serve-check

labs serve accepts a lab source tree, a .bsilab package, or a registry reference. It opens the browser at the root URL:

http://127.0.0.1:8765/

For scripts, servers, and CI runners, skip the browser and pick a port:

biosimulant labs serve ./serve-check --no-open --port 8766

--host defaults to 127.0.0.1.

/ui and /ui/ redirect to / for compatibility with the older local UI. There is no supported /ui/api surface. Use the root URL in new links and scripts.

What persists

Model, world, runtime, and wiring edits are saved to lab.yaml, which stays the source of truth.
Canvas layout is saved to wiring-layout.json.
Runs, logs, results, and run artifacts are saved under .biosimulant/runs/ in the lab directory and are loaded again when the server restarts. A run that was still active when the server stopped is marked as interrupted.

API Envelope

Local UI endpoints return:

{ "ok": true, "data": {}, "error": null }

Errors return:

{ "ok": false, "data": null, "error": { "message": "..." } }

The artifact download endpoint returns the file itself, not this envelope.

Endpoints

Endpoint	Method	Purpose
`/api/lab`	GET	Current lab manifest, manifest-derived model metadata, runtime metadata status, and layout
`/api/runs`	GET	Run history for this lab
`/api/runs`	POST	Start a local run
`/api/runs/{id}`	GET	Run status and metadata
`/api/runs/{id}/results`	GET	Collected run results and visuals
`/api/runs/{id}/artifacts/{artifact_id}`	GET	Download a file recorded for the run, such as a `structure3d` source
`/api/runs/{id}/logs?since_seq=...`	GET	Run log entries
`/api/runs/{id}/cancel`	POST	Request cancellation
`/api/lab/models/{alias}`	PUT	Persist model alias/parameter updates to `lab.yaml`
`/api/lab/world`	PUT	Persist world IO, runtime, and wiring updates to `lab.yaml`
`/api/lab/layout`	PUT	Persist canvas layout to `wiring-layout.json`

Run Overrides

POST /api/runs accepts optional parameters and simulation_config fields. World input names are mapped through manifest.io.inputs[].maps_to; direct alias.port keys are also accepted. Per-model parameter overlays apply only to that run.

/api/lab returns quickly from the local manifest so the canvas can render while runtime-derived port metadata is prepared in the background. Check runtime_metadata_status for pending, running, ready, or failed.