> For the complete documentation index, see [llms.txt](https://decentralabs-2.gitbook.io/decentralabs-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://decentralabs-2.gitbook.io/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-operator-guide.md). # Lab Manager operator guide This is the starting point for operators who manage a laboratory through `/lab-manager`. The interface is a static web application, but each tab talks to a different Gateway component or control-plane service. The configuration order therefore matters. ## What each tab does | Order | Tab | Main purpose | Processes behind it | | ----- | -------------------- | ------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | | 1 | `Labs` | Publish, edit, and maintain physical laboratories or FMU simulations. | `blockchain-services` through `/lab-admin/**`; local discovery through Ops Worker. | | 2 | `Operations` | Monitor stations, heartbeat, reservations, and timelines. | Ops Worker through `/ops/**`; cancellation through `/lab-admin/**`. | | 3 | `Energy` | Manage credentials, controllers, outlets, policies, and power tests. | Ops Worker through `/ops/api/power/**`. | | 4 | `Income` (Lite only) | Read income totals for this Gateway and its labs. | Provider backend through the Gateway-scoped `/lab-admin/billing/provider-income` route. | | 5 | `Digital Twins` | Synchronize an FMU or physical laboratory with AAS, import a prepared AASX, or link an external shell. | `fmu-runner`, Ops Worker, and BaSyx through `/aas-admin/**`. | | 6 | `Notifications` | Configure and test email/ICS delivery for this Gateway's labs. | Provider backend through the Gateway-scoped `/lab-admin/notifications/**` routes. | The tabs are declared in [Lab Manager](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/web/lab-manager/index.html) and grouped dynamically by [lab-manager-tabs.js](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/web/assets/js/lab-manager-tabs.js). The shared header and tab bar look like this in a Full Gateway. The active panel changes which backend surface is queried; the access-policy badge remains visible so operators can tell whether the dashboard is restricted to localhost or an allowed private CIDR. ![Lab Manager Laboratories tab](https://2324164250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhBavBrPgRBmGJAMRBdoV%2Fuploads%2Fgit-blob-d74e43e665424fc75c718a2917de341325942eb1%2Flab-manager-laboratories.png?alt=media) ## Full, Lite, and permissions | Capability | Full Gateway | Lite Gateway | | --------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | `Labs` | Available when the local backend runs in `provider-consumer` mode. | Available only when `LAB_ADMIN_BACKEND_URL`, `LAB_ADMIN_BACKEND_TOKEN`, and its header are configured. | | `Operations` | Uses the local Ops Worker and stations. | Uses the Lite Gateway's local Ops Worker and stations. | | `Energy` | Uses controllers local to the Gateway. | Uses controllers local to the Lite Gateway. | | `Income` | Hidden. | Read-only report for the authenticated Gateway's department and labs. | | `Digital Twins` | Available when AAS/FMUs are configured. | Disabled by the UI and blocked by the backend. | | `Notifications` | Available when the local backend runs in `provider-consumer` mode. | Available when the configured provider backend runs in `provider-consumer` mode and the Lite has a mapped backend credential. | `LAB_MANAGER_TOKEN` protects the Lab Manager session, `/lab-admin`, `/ops`, and AAS administration routes. Notifications use that existing session. For Lite, the backend trust bundle maps its backend credential to one Gateway ID; the operator does not need the institution-wide Wallet & Billing token. The Lite `Income` tab uses the Lite's configured backend credential. OpenResty replaces any browser-supplied `X-Gateway-ID`, and the backend validates that identity against the credential before returning income for that Gateway. The endpoint is read-only; the browser cannot select another Gateway or access the institution-wide Wallet & Billing report. Network policy still applies even when a token is present. `/ops/` and administrative operations are intended for localhost or explicitly allowed private networks. In Lite mode, the browser may display the interface, but remote routes must be explicitly configured and authorized. Reservation lists and cancellation are also scoped to the current Gateway: the backend matches each lab's `accessURI` to the Gateway identity before returning or cancelling a reservation. This keeps faculties or departments using different Gateways isolated even when they share an institution or provider wallet. ## Identifiers that must not be confused | Identifier | Meaning | Where it is used | | ---------------- | --------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `labId` | Stable laboratory identity in the contract/provider projection. | Energy policies, AAS synchronization/linking, and reservations. | | `accessKey` | Operational reference for the published resource. | `guac:id:` for physical labs; FMU filename/reference for FMUs. | | `reservationKey` | On-chain reservation identifier. | Cancellation, timeline, and session diagnosis. | | `controllerId` | Local identifier for an energy controller. | JSON catalog and policies. | | `credentialRef` | Local reference to an encrypted credential. | APC, SNMP, and NETIO controllers. It is never the secret. | ## Recommended order for a physical laboratory 1. Deploy the Gateway and verify [configuration](/decentralabs-docs/lab-gateway/getting-started-and-deployment/configuration.md) and [health](/decentralabs-docs/lab-gateway/operations-and-verification/operations-and-health.md). 2. Create and test the local Guacamole connection using [Guacamole connections](/decentralabs-docs/lab-gateway/architecture-and-connectivity/guacamole-connections.md). 3. Prepare Lab Station, Wake-on-LAN, WinRM, and heartbeat according to [Gateway and Lab Station operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/gateway-lab-station-operations.md). 4. Open `Labs`, publish the laboratory, and confirm that the `labId` and `accessKey` are the expected values. For a physical lab, the Digital Twins selector obtains calculated eligibility from Ops Worker, which resolves the Guacamole connection and registered host inventory. 5. Configure `Energy` if a smart power strip is present. Never cut power to the Gateway, network switch, or any control-plane equipment with that strip. 6. Return to `Operations`, provision the host, save WinRM credentials, check heartbeat, and run a controlled test. 7. Create a test reservation and inspect the complete timeline: WoL, `prepare-session`, access, `release-session`, and any power actions. The details for steps 3, 4, and 6 are in [Labs and Operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-labs-and-operations.md). The complete energy workflow is in [Lab Manager energy operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-energy-operations.md). ## Recommended order for an FMU or physical laboratory digital twin 1. For an FMU, install and validate the model on Lab Station; see [FMI/FMU support](/decentralabs-docs/lab-gateway/digital-twins/fmi-fmu-support.md). For local execution tests, start `fmu-local-dev` together with `aas`: `docker compose --profile fmu-local-dev --profile aas up -d`. Do not run `fmu-runner` at the same time because both profiles use the `fmu-runner` proxy alias. For a physical lab, first complete the normal `Labs`, `Operations`, and Lab Station setup. 2. Publish the resource from `Labs` and confirm its stable `labId`. FMUs retain their operational `accessKey`; physical labs retain their Guacamole `accessKey`, but neither is selected manually in Digital Twins. 3. Open `Digital Twins` → `Digital Twin Management` and select the laboratory. The selector includes FMUs and physical laboratories associated with an Ops Worker host, and uses the `labId` to associate the operation automatically. A physical laboratory is listed only when its `labId` is linked through its Guacamole `accessKey` to a connection exposed by an Ops Worker host; the selector reads this projection from `GET /ops/api/lab-associations`. This is the mapping required by physical AAS synchronization. 4. Click `Sync AAS` to generate metadata. FMUs use the model description when available, otherwise the registered laboratory description. Physical labs use Gateway/heartbeat data plus the registered description, documentation, and Terms of Use. No separate Documentation or License fields are required. 5. Optionally upload a provider-prepared `.aasx`. The package must contain `urn:decentralabs:lab:{labId}` as a shell ID, unless the shell is associated through `Link Existing AAS`. Use that panel when the authoritative shell is already hosted elsewhere. 6. In `AAS Associations`, verify the laboratory association. The list includes `Generated` shells created by `Sync AAS`, `Imported` shells loaded from an uploaded `.aasx`, and `Linked` shells managed elsewhere. `View` shows the current shell/submodel IDs; `Download` generates an AASX from the current BaSyx resources. `Delete` removes generated/imported resources from BaSyx, while `Unlink` only removes a linked association. 7. Verify shell retrieval through the Gateway, not only directly against BaSyx. The association list is calculated from the current BaSyx shells plus the lightweight metadata retained for imported AASX files and external links. It therefore also shows shells generated before this feature was enabled. Old archive files are not used for downloads and can be removed through the association's `Delete` action after confirming the BaSyx resources are present. The association between a physical laboratory and an Ops Worker host is not stored in `hosts.json`. The worker reads the current provider catalog from `blockchain-services`, resolves `labId → accessKey → Guacamole hostname`, and then matches that hostname to exactly one registered host. This keeps labs published from Marketplace and Lab Manager consistent. ## Notification workflow 1. Open `Notifications` only when changing or testing the configuration. 2. Use the existing Lab Manager session for this Gateway. 3. Choose `NOOP`, `SMTP`, or `GRAPH`, complete the form, and save. 4. Use `Send Test Email` and verify recipients, logs, and ICS calendar data when applicable. The detailed configuration, secrets, and persistence rules are in [Notifications](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-notifications.md). ## First-level diagnosis | Symptom | First check | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | No laboratory appears in selectors | Refresh `Labs`, verify `LAB_MANAGER_TOKEN`, check the publication backend, and for physical labs confirm that the lab uses a valid `guac:id:` and that the matching connection appears under a registered Ops Worker host. | | `Operations` shows a network warning | Access from localhost or an allowed CIDR; check dashboard policy. | | `Digital Twins` is disabled | Confirm that the Gateway is Full and is not running with an external `ISSUER`. | | A tab loads but its data is empty | Identify the responsible route in the opening table and inspect that service, not only the browser. | | The timeline has no events | Use the correct on-chain `reservationKey` and check heartbeat, Ops Worker, and MySQL. | ## Reference documentation * [Labs and Operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-labs-and-operations.md) * [Energy](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-energy-operations.md) * [Notifications](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-notifications.md) * [Deployment architectures](/decentralabs-docs/lab-gateway/getting-started-and-deployment/deployment-architectures.md) * [AAS support](/decentralabs-docs/lab-gateway/digital-twins/aas-support.md) * [FMI/FMU support](/decentralabs-docs/lab-gateway/digital-twins/fmi-fmu-support.md) * [Guacamole session policy](/decentralabs-docs/lab-gateway/architecture-and-connectivity/guacamole-session-policy.md)