> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensormesh.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Install the Operator UI into your cluster, next to the Tensormesh Operator.

The UI installs the same way as the operator, from the same private registry — the **access
token you already have works for both**. If you don't have one, request it from the
Tensormesh team.

<Note>
  Install the **Tensormesh Operator and at least one `LMCacheEngine` first** — the UI is a
  read-only dashboard *over* your engines. It installs fine on an empty cluster but shows
  "No LMCacheEngines found" until engines exist.
</Note>

***

## Prerequisites

* Helm `3.8` or newer (`helm version`)
* A Kubernetes 1.28+ cluster with the [Tensormesh Operator](/operator/installation/helm) installed,
  plus at least one `LMCacheEngine`
* **Prometheus running in the cluster**, with the operator's metrics flowing into it
  (`observability.enabled=true` on the operator chart — see
  [Operator Observability](/operator/observability)). This powers every trend chart.
* **The NVIDIA DCGM exporter, if you run GPUs** — standard on GPU clusters (it ships with the
  NVIDIA GPU Operator, and isn't part of Tensormesh). It drives the per-GPU utilization, memory,
  and hardware-fault cards.
* **An access token from the Tensormesh team** — the operator's token works
* The GHCR image pull secret you created for the operator

***

## Versions

Use the newest chart version below wherever a command says `<version>`. Like the
[operator's compatibility matrix](/operator/installation/compatibility), each row is a
matched set — run the UI chart against the operator versions listed with it.

| UI version | Works with operator |    Status   | As of      |
| ---------- | ------------------- | :---------: | ---------- |
| `0.1.0`    | `v0.5.2`            | ✅ Supported | 2026-08-13 |

***

## Install

<Steps>
  <Step title="Log in to the Registry (One Time)">
    ```bash theme={null}
    # username isn't validated for token auth — any non-empty value works
    echo '<TOKEN_FROM_TENSORMESH>' | helm registry login ghcr.io -u tensormesh --password-stdin
    ```

    If you already logged in to install the operator, skip this step.
  </Step>

  <Step title="Write a Values File">
    ```yaml my-values.yaml theme={null}
    engineNamespace: tensormesh-operator      # where your engines run
    prometheus:
      url: http://kube-prometheus-stack-prometheus.monitoring.svc:9090   # required — powers the charts
    dcgmService: dcgm-exporter.gpu-operator:9400   # GPU clusters — per-GPU cards (name varies by install)
    imagePullSecrets:
      - name: tensormesh-ghcr                 # the operator's pull secret works here too
    ```

    The UI picks up cluster access automatically once it's running inside the cluster — you never
    set a kube API URL or token. See [Configuration](/operator/ui/configuration) for how each value
    maps to what you see, plus multiple clusters.
  </Step>

  <Step title="Install">
    ```bash theme={null}
    helm upgrade --install tmo-ui \
      oci://ghcr.io/tensormesh-production/charts/tensormesh-operator-ui \
      --version <version> -n tensormesh-operator --create-namespace \
      -f my-values.yaml
    ```

    <Warning>
      Replace `<version>` with the newest chart version from the [table above](#versions) —
      **never `latest`**, so you always know exactly what's running.
    </Warning>
  </Step>
</Steps>

***

## Verify

```bash theme={null}
helm test tmo-ui -n tensormesh-operator
```

The bundled test confirms the UI is up and serving. If anything looks off once you open the
dashboard, see [Troubleshooting & FAQ](/operator/ui/troubleshooting).

***

## Open the Dashboard

The install doesn't expose the UI outside the cluster. To open it, port-forward the service:

```bash theme={null}
kubectl -n tensormesh-operator port-forward svc/tmo-ui-tensormesh-operator-ui 8080:80
# open http://localhost:8080
```

For shared team access, enable the ingress (`ingress.enabled=true` with your own hosts and
TLS).

<Warning>
  The UI has **no built-in login** — if you expose it beyond port-forward, put SSO in front at the
  ingress. See [Access & Security](/operator/ui/access-and-security).
</Warning>

***

## What Gets Installed

A single dashboard pod and a service — nothing on your GPU nodes. Its cluster access is
**strictly read-only**: it can look at engines, pods, and metrics, and cannot modify
anything.

***

## Upgrade

Re-run the install with a new `--version` (same values file):

```bash theme={null}
helm upgrade --install tmo-ui \
  oci://ghcr.io/tensormesh-production/charts/tensormesh-operator-ui \
  --version <new-version> -n tensormesh-operator -f my-values.yaml
```

Roll back if needed:

```bash theme={null}
helm history tmo-ui -n tensormesh-operator
helm rollback tmo-ui <revision> -n tensormesh-operator
```

***

## Uninstall

```bash theme={null}
helm uninstall tmo-ui -n tensormesh-operator
```

The UI keeps no cluster state, so nothing is left behind.

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="sliders" href="/operator/ui/configuration">
    Connect metric history, GPU telemetry, and multiple clusters.
  </Card>

  <Card title="Monitoring Your Fleet" icon="table-columns" href="/operator/ui/monitoring-your-fleet">
    Triage what needs attention, drill into nodes and GPUs, and track cache and
    performance trends.
  </Card>
</CardGroup>