<!-- Source: https://docs.biosimulant.com/references/library/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.

```bash
pipx install biosimulant
biosimulant labs serve ./my-lab
```

The canonical UI URL is the root path:

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

`biosimulant labs serve` opens the browser by default. Use `--no-open` for
headless scripts or remote shells.

## Compatibility Redirect

`/ui` and `/ui/` redirect to `/` for compatibility during the transition from
the older local UI. There is no supported `/ui/api` surface.

## API Envelope

Local UI endpoints return:

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

Errors return:

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

## Endpoints

| Endpoint | Method | Purpose |
|---|---:|---|
| `/api/lab` | GET | Current lab manifest, manifest-derived model metadata, runtime metadata status, and layout |
| `/api/runs` | GET | In-memory run history for this serve process |
| `/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}/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`.

## Persistence

- `lab.yaml` is the source of truth for manifest edits.
- `wiring-layout.json` stores canvas positions.
- Run history does not persist across server restarts.