<!-- Source: https://docs.biosimulant.com/references/labs-serve -->

# 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

```bash
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:

```text
http://127.0.0.1:8765/
```

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

```bash
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:

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

Errors return:

```json
{ "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`.

## See Also

- [Visualization Contract](/references/visualization)
- [Write a lab.yaml](/how-to/write-lab-manifest)