> 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-labs-and-operations.md).

# Lab Manager: Labs and Operations

This guide covers the two tabs that prepare and operate a physical laboratory or FMU simulation. For the overall view and Full/Lite differences, start with the [Lab Manager operator guide](/decentralabs-docs/lab-gateway/architecture-and-connectivity/lab-manager-operator-guide.md).

## 1. Labs: publish and maintain resources

### Requirements

In Full mode, the backend must run in `provider-consumer` mode, the wallet must be registered as a provider, and the Gateway must have a configured `creatorPucHash` or `PROVIDER_PUC_HASH`. In Lite mode, the tab works only when `/lab-admin` has been explicitly delegated to the remote backend:

```env
LAB_ADMIN_BACKEND_URL=https://full.example.edu
LAB_ADMIN_BACKEND_TOKEN=<unique-token-from-this-lite-trust-bundle>
LAB_ADMIN_BACKEND_TOKEN_HEADER=X-Lab-Manager-Token
```

The Full/backend must register this Lite token against the Lite's Gateway ID and `accessURI` in `LAB_ADMIN_GATEWAY_CREDENTIALS_JSON`. With the trust-bundle script, that registration is automatic. The Labs tab then lists and mutates only labs assigned to this Gateway; an institutional administrator with the normal admin access token can still oversee the full provider catalogue. The publication contract is described in [Lab administration](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/blockchain-services/docs/services/lab-administration/LAB_ADMINISTRATION.md).

### Detect the resource

In `Labs` → `Detected Resources`:

* `Remote lab` lists Guacamole connections discovered from the Gateway.
* `FMU simulation` lists FMU inventory available to the Gateway/Station.
* `Full Setup` generates local metadata and allows local image/document uploads.
* `Quick Setup` uses an external HTTPS metadata URL.
* `Publish and list` publishes and lists the resource; `Create draft` creates it without making it available in the catalog yet.

Detection only pre-fills values. Review `Access URI`, price, availability, and metadata before publishing.

![Lab Manager Labs 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)

### Publish a physical laboratory

1. Select `Remote lab` and an existing Guacamole connection.
2. Confirm that `Connection ID` has the form `guac:id:<connection_id>`. Do not use the visible connection name as the `accessKey`.
3. Confirm that `Access URI` points to the Gateway that owns the connection, for example `https://gateway.example/guacamole`.
4. In `Metadata`, complete at least the name, description, categories, and availability.
5. Configure price, unit, timezone, available days and hours, booking slots or reservation period, concurrent users, and unavailable windows.
6. Optionally add terms of use, images, documents, ISCED-F classification, and Demo access.
7. Click `Publish Lab` and retain the `labId` and transaction hash when an on-chain mutation has taken place.

Test the connection in Guacamole before publishing. Publication does not turn an unreachable connection into a valid session.

### Publish an FMU simulation

1. Select `FMU simulation` and the detected FMU.
2. Confirm the `.fmu` filename, the `/fmu` `accessURI`, and the operational `accessKey`.
3. Review the detected FMI description: FMI version, simulation type, default times, step size, and model variables.
4. Set a positive `Max Concurrent Users` value that does not exceed Lab Station capacity.
5. Complete license, documentation, contact, and the remaining metadata.
6. Publish it as listed or as a draft, depending on the release procedure.

The real model remains on Lab Station. The user receives a reservation-scoped `proxy.fmu`; the original file is not published. See [FMI/FMU support](/decentralabs-docs/lab-gateway/digital-twins/fmi-fmu-support.md) for station validation and execution.

### Full Setup and Quick Setup

`Full Setup` writes metadata under the Gateway content volume and publishes the generated asset URLs. `Quick Setup` does not generate that JSON: it points to an external HTTPS URL that must be allowed by the provider-origin policy. Do not use arbitrary URLs, unsupported IPFS locations, or metadata containing secrets.

### Edit, list, and delete

* Use `Cancel Edit` to leave an edit without submitting changes.
* `Publish Lab` becomes an update action when an existing laboratory is being edited.
* A metadata-only change may be off-chain; an on-chain change returns a transaction and must be verified through its receipt.
* Listing or unlisting changes public availability; it does not delete the resource.
* Deleting a laboratory is destructive: it removes the resource on-chain and starts the durable local-content tombstone hand-off. Before deleting, check for reservations that still need resolution and retain the operation evidence.

Mutable backend operations use idempotency. After a timeout, do not repeat a publication or deletion until the current state and transaction are checked.

### Reservation isolation

`Operations` only shows actionable or upcoming reservations for laboratories assigned to the current Gateway. The assignment is derived from the lab's on-chain `accessURI`, so two Gateways in the same institution remain isolated. The Gateway overwrites the browser-supplied scope header with its configured identity, and `blockchain-services` checks the scope again before listing or cancelling a reservation. A cancellation for a lab assigned to another Gateway is rejected, even when both Gateways use the same provider wallet.

## 2. Operations: prepare the station

### Inventory and Guacamole candidates

In `Operations` → `Lab Station Ops`, the interface shows:

* hosts configured in `ops-worker/hosts.json` and `ops-data/hosts.json`;
* the station address, last heartbeat, current readiness/local-session/local-mode state, and the last forced-logoff and power-action information;
* the number of matching remote-access connections; and
* Guacamole connections that are not yet associated with an Ops host.

Click `Refresh` after changing the inventory. The UI starts a heartbeat stream for each host with WinRM credentials and ready TLS trust when the browser and endpoint support it. Hosts created through the Lab Manager are editable with the pencil action next to their name; the address remains read-only.

![Lab Manager Operations tab](https://2324164250-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FhBavBrPgRBmGJAMRBdoV%2Fuploads%2Fgit-blob-e8bacff88b162f2a50c2ea24e053397e4e41d1c5%2Flab-manager-operations.png?alt=media)

### Discover and provision a host

For a Guacamole connection without an Ops host:

1. Run `Check Lab Station`.
2. Review the address, candidate name, MAC address, and Lab Station signals.
3. Click `Configure` and complete:
   * `Name`: stable host identifier;
   * `Address`: detected private address (read-only);
   * `MAC`: required for WoL;
   * `Heartbeat path`: discovered automatically; for current Lab Station releases it is normally `C:\Lab Station\labstation\data\telemetry\heartbeat.json`.
4. Save the host and reload the inventory.

The station form stores only the host configuration. At runtime the worker reads the provider catalog, follows each physical lab's Guacamole `accessKey`, and associates the connection with exactly one registered host; one station can therefore serve multiple labs while other connections on the same station remain administrative.

For a provisioned host, use the pencil action to change its name, MAC, or heartbeat path. Static entries from `ops-worker/hosts.json` must still be edited in that catalog.

### Store WinRM credentials

Click the `missing` or `configured` WinRM credential status in the host card, open `Set WinRM Credentials`, and save the user and password for its `credential_ref`. The password is stored in the encrypted Ops Worker credential store, not in `hosts.json`.

Until both credentials and certificate trust are ready, heartbeat streaming is not started for that host.

The host card reports credentials and certificate trust separately:

* `WinRM credentials: missing` means no user/password is stored;
* `WinRM TLS trust: missing` means credentials exist but no valid Station certificate has been saved in the Gateway's per-host trust store;
* `WinRM TLS trust: ready` means the Gateway can parse the local certificate and it is currently within its validity period; and
* `expired`, `not yet valid`, or `invalid` identify a certificate that cannot be used.

`ready` describes the local trust prerequisite. A successful heartbeat is still needed to prove network reachability, authentication, and that the certificate served by the Station matches the trusted certificate.

### Manage WinRM TLS trust

Click the `WinRM TLS trust` status in the host card to open its certificate panel. The panel is the single entry point for this host's trust lifecycle:

1. Select the public certificate exported by Lab Station, normally `C:\ProgramData\DecentraLabs\Lab Station\winrm-server.cer`.
2. Click `Preview certificate` and check the displayed host, validity dates, SAN/CN and SHA-256 fingerprint.
3. Check the explicit fingerprint confirmation and click `Save certificate`. Saving replaces the existing certificate only after the server validates it against the selected host.
4. Use `Verify connection` to run an immediate heartbeat, or `Remove trust` to delete the host-specific trust material.

The panel reports `missing`, `ready`, `expired`, `not yet valid`, or `invalid` independently from the credential status. Error responses include a stable code and request ID; internal exceptions and certificate contents are not shown.

Heartbeat failures use these stable codes:

| Code                        | Meaning                                                           | Operator action                                                                                                      |
| --------------------------- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| `WINRM_AUTH_FAILED`         | Lab Station rejected the stored WinRM credentials.                | Recheck or replace the host's `WinRM credentials`, then use `Verify connection`.                                     |
| `WINRM_HEARTBEAT_NOT_FOUND` | The configured heartbeat file could not be read from Lab Station. | Check the station path and `heartbeat_path` for the host; keep the returned `requestId` for logs.                    |
| `WINRM_HEARTBEAT_INVALID`   | The heartbeat file was read but is not valid JSON.                | Inspect the station's `status-json` output and file contents, then retry after correcting the station-side artifact. |

These two prerequisites are independent. Until WinRM credentials are saved, the Lab Manager does not open a heartbeat stream for the host. If credentials exist but certificate trust is missing or invalid, the host remains unable to produce a heartbeat until the certificate is saved or corrected through the trust panel or the recovery procedure. Use the `WinRM credentials` and `WinRM TLS trust` statuses on the host card to decide which step is missing; do not treat an incomplete host as a Station or Gateway failure.

For technical bootstrap or recovery, the public certificate exported by Lab Station can also be copied directly to the Gateway host:

```
ops-data/winrm-certificates/<lower-case-winrm-trust-ref>/server.cer
```

For example, the certificate for `PC-Siemens` is copied from `C:\ProgramData\DecentraLabs\Lab Station\winrm-server.cer` to the directory for the host's `winrm_trust_ref` (for example, `ops-data/winrm-certificates/pc-siemens/server.cer`). The ops worker discovers the file when it starts or when the host catalog is reloaded, validates its format and dates, calculates the fingerprints, generates the local PEM trust copy when necessary and uses it only for that host's WinRM sessions. `GET /ops/api/hosts` reports the resulting `winrmTrustStatus`, fingerprint and certificate metadata.

If the certificate is missing, malformed or expired, the heartbeat reports a specific trust error instead of treating the failure as an authentication problem. Do not disable TLS validation or configure `TrustedHosts`.

WinRM must use HTTPS/TLS on port `5986`, and the address must belong to `WINRM_MANAGEMENT_CIDRS`. Do not publish the listener or Ops Worker to the Internet.

### Manual actions and heartbeat

For each host, operators can:

* request an immediate heartbeat;
* send Wake-on-LAN;
* execute only Lab Station commands allowed by `OPS_ALLOWED_COMMANDS`;
* enable or disable local mode according to the operating procedure; and
* inspect preparation state, the last operation, power state, and WoL NIC data.

Heartbeat streaming starts automatically only for hosts with configured WinRM credentials and ready TLS trust. A missing or invalid certificate prevents the authenticated heartbeat even when the Station is powered on. If a stream error includes a `requestId`, keep it for the Ops Worker logs; the browser message is not a substitute for the host-card credential and TLS trust statuses.

Destructive or power actions require an authorized maintenance window and a clear operational reason. For the Windows command contract, see \[winrm-command-contract.md]\(../../../Lab Station/docs/winrm-command-contract.md).

### Actionable Reservations

`Actionable Reservations` lists bookings that the provider can still cancel, including service failures that remain inside the attestation period. Before cancelling:

1. open the reservation details and verify the laboratory and dates;
2. select a backend-approved reason;
3. confirm that cancellation is actually necessary; and
4. retain the response, transaction hash, and any service-credit return or reputation impact.

The UI uses `/lab-admin/reservations/actionable` and `/lab-admin/reservations/{reservationKey}/cancel`. The backend revalidates ownership, state, timing, and attestation conditions when signing. A concurrent reservation change must fail safely.

### Recent Operations and Reservation Timeline

`Recent Operations` shows recent Ops Worker activity with pagination. Use it to identify WoL, WinRM, preparation, release, and scheduler failures.

`Reservation Timeline` requires the on-chain `reservationKey`, normally the reservation hash. It displays:

* summary and local phases;
* heartbeat, WoL, `prepare-session`, and `release-session` operations;
* power operations when a policy exists; and
* the latest station state.

Local states such as `CONFIRMED`, `ACTIVE`, and `COMPLETED` are operational projections. They do not replace the reservation's on-chain states.

## 3. Physical-laboratory acceptance flow

Before considering the laboratory ready:

* the Guacamole connection works over the private network;
* Lab Station launches the application and publishes heartbeat;
* WoL wakes the host from an approved state;
* WinRM authenticates and accepts `prepare-session` and `release-session`;
* the published `labId` matches the host and, if present, the energy policy;
* a test reservation reaches Guacamole without a manual login screen; and
* the timeline contains enough evidence to diagnose the session.

## References

* [Guacamole connections](/decentralabs-docs/lab-gateway/architecture-and-connectivity/guacamole-connections.md)
* [Gateway and Lab Station operations](/decentralabs-docs/lab-gateway/architecture-and-connectivity/gateway-lab-station-operations.md)
* [Laboratory connectivity](/decentralabs-docs/lab-gateway/architecture-and-connectivity/laboratory-connectivity.md)
* [Lab administration API](https://github.com/DecentraLabsCom/lite-lab-gateway/tree/main/blockchain-services/docs/services/lab-administration/LAB_ADMINISTRATION.md)
* [Operations and health](/decentralabs-docs/lab-gateway/operations-and-verification/operations-and-health.md)