---
name: panel-operations
description: Access and use the web panel bundled in every CitusIO tier, inspect broker and integration state, and follow authorized command workflows within the live tier and identity scope.
---

# Use the bundled operator panel

For administration with the panel closed, read the bundled
[admin operation guide](../references/agent-administration.md) and
[task catalog](../contracts/agent-tasks.json). The catalog binds existing API operation IDs to inputs, authority,
effects, idempotency and completion rules. Use
[admin API operations](../admin-api-operations/SKILL.md) with any agent or HTTP
tools; no supplied client or host language runtime is required. Validation sends
GETs only, submission sends one reviewed POST, and observation reads the original
command ID. Acceptance is pending; require reconciled command evidence for completion.
If a POST response was lost before returning an ID, recovery with the original
task and exact inputs searches retained daemon events/status using GETs only.
It requires a unique full-intent match and never resubmits the command.
Inspect the extracted kit's catalog and version rather than assuming an older
image contains the same operations.

Inspect `/api/v1/admin/identity` for version-1 `availability`: compiled tier,
selected runtime profile, view IDs and workflow IDs. Bind it to the live
dashboard's node, routing generation, writer term, ring generation and
configuration digest. Missing, stale or mismatched scope withdraws command
availability. Tier labels, an old scope or a visible card cannot grant it.
Refresh identity and dashboard together after a scope change. Browser navigation,
deep links and contextual evidence links follow this backend-owned scope.

Every tier includes the same production panel assets. The backend's installed
lane, selected configuration, live capabilities and operator identity determine
the available scope. An unavailable page/action does not mean the panel was
omitted. Changing browser settings cannot enable a higher tier.

## Open the deployed panel

The `gateway` role serves the panel and admin API on the same origin. Start
the explicit node roles using [container-setup](../container-setup/SKILL.md);
the default image command prints skills and exits. No separate panel server,
Node/npm installation, source checkout, CDN or website is required.

Read the extracted kit's `requirements.json` **panel** section and Compose port
mapping. Listener ports are published on the `iotd` namespace owner:

| Selected kit | Panel access | Scope |
| --- | --- | --- |
| Free (legacy Evaluation image lane) | `http://127.0.0.1:8080/` by default | Live production and configured operational views; accepted-memory state. |
| Core Broker | `http://127.0.0.1:8080/` by default | Durable broker, clients, sessions, retained/offline metadata, auth and observability. |
| Integration and Edge | `http://127.0.0.1:8080/` by default | Core views plus configured rules, schemas, bridges and gateways. |
| Enterprise Operations | Site HTTPS origin backed by container port `8081` | Authenticated operational views and capability/role-gated commands, audit and HA facts. |
| Internal all-in-one | The explicitly selected profile; its kit selects the Enterprise pair | Internal scope follows the live profile rather than the compiled maximum. |

Replace the host and port when deployment mappings change. The kit defaults to
loopback exposure. For a remote operator, use the deployment's approved proxy
or tunnel; retain the same origin for HTML, assets and API requests. Enterprise
node B defaults to host port `18081` for its `8081` listener, separately from A.

The Evaluation/Core/Integration examples expose operational reads through a
controlled local boundary and do not authenticate governed mutations. Enterprise
uses the site's reviewed HTTPS/SSO edge and `oauth2-proxy:4180` validation
service. Use that site's login/session flow; the image does not create an IdP
or a login account. Its backend port `8080` stays node-local. Client-supplied
identity headers do not replace authenticated operator identity.

Panel files are at `/usr/share/nginz-iot-panel/browser`; `panel-build.json`
there, and at `/panel-build.json` through the configured origin, identifies the
bundled release pairing. Read image labels `nginz-iot.panel-revision` and
`nginz-iot.panel-version` when recording the exact image. Enterprise metadata
requests use the same authenticated origin.

## Read operational state

1. Open **Overview**. Confirm `env live`, the intended node, compatible release,
   fresh data and dashboard quality. The production bundle has no fixture
   scenario selector. A loaded page alone does not establish node readiness.
2. Read the backend's route/readiness decision before assigning traffic.
   **HA** shows the supporting ownership, frontier and generation facts; the
   browser cannot grant a writer term or fence another node.
3. Open the page matching the task. The primary links are Overview, Triage and
   Command Center; expandable broker, integration and evidence groups contain
   detailed pages. The active page's group opens automatically. Overview shows
   recent operation events and expandable runtime/routing details:

| Task | Page and interpretation |
| --- | --- |
| Find a connection, session or subscription | **Devices** and **Broker**; filter the collection and inspect its own freshness/page. |
| Inspect retained or offline state | **Broker**; summaries omit message bodies. Use the approved MQTT/application workflow for payload verification. |
| Diagnose identity or policy posture | **Auth**; inspect policy generation, denials and caches. Provision credentials through the private configuration process. |
| Follow a rule/schema or sink failure | **Rules**, **Bridges**, **Gateways**; inspect configured availability, rejects, backlog, retries and dead letters. A broker ACK is not sink commitment. |
| Investigate a readiness incident | **Triage**, **Observe** and **HA**; correlate fresh backend facts before choosing an operational action. |
| Review changes and evidence | **Config**, **Audit**, **Support** and **Command Center**; distinguish previews, accepted requests and completed work. |

Unavailable and disabled capabilities remain unavailable even if their page is
visible. An empty bridge table is expected for the kit's Core profile, which
selects no bridge. A compiled gateway is not necessarily configured/listening.
Managed Cloud is planned and is not enabled by these images.

Dashboard refresh and collection refresh are separate. Dashboard polling pauses
in hidden tabs and revalidates on return; refresh the owning collection when
needed. Filters/pagination limit the visible rows. **Audit** can remain on a
historical page; use **Follow latest events** to return to the tail.

## Use governed commands when available

The shipped non-Enterprise examples keep mutations blocked. In a governed
deployment, check the live identity/capabilities and the workflow's preflight
reason. The supported role scopes are:

| Role | Governed scope |
| --- | --- |
| `viewer` | Read operational facts. |
| `operator_admin` | Node drain, selected bridge drain and support bundle; support is also an API v1 compatibility permission. |
| `config_admin` | Configuration preflight. |
| `support_admin` | Support bundle creation. |

The backend still enforces readiness, governance, RBAC and audit requirements.
Configuration preflight does not apply configuration. These workflows do not
provide general credential editing, rule deployment or arbitrary sink changes.

In **Command Center**, select the explicit target, inspect the routing version,
write-authority cycle, audit impact and idempotency key, then choose **Review
command** and **Confirm request** only for the authorized operation. Disabled
**Preflight unavailable** actions require resolving their reported gate.
Command cards follow the verified role and the backend workflow catalog.
Changing role, write authority, installed scope or fencing invalidates an open confirmation;
review again under the current identity. Operational evidence remains readable
when the role has no command workflows.

Record the command and audit IDs. HTTP success and `accepted_pending` mean
acceptance. Wait for backend `reconciled` evidence before claiming completion.
If polling pauses or the browser reloads, use **Pending command recovery ledger**
and **Observe status** to follow the existing command. Discarding browser
evidence does not cancel a backend command. Do not submit a duplicate request
to obtain status. Review support artifacts before sharing them.

During an outage, retained evidence is marked stale and cannot authorize a new
command. Session expiry withdraws the verified role. A fresh matching cycle can
restore availability without replaying a request; inspect the original command
ID even when current write authority has been withdrawn.

## Resolve access or display problems

- **No page:** check the gateway role and published owner port. Enterprise uses
  the authenticated `8081` edge. Replacing a namespace owner requires recreating
  its dependent joins; see [container-operations](../container-operations/SKILL.md).
- **401/403:** establish the site's valid SSO session and required role, or
  recognize that the selected example permits reads only. Preserve the edge's
  identity and CSRF boundary.
- **Stale, partial, incompatible or invalid data:** refresh and check the
  origin's API/daemon freshness and bundled release pairing. Mutations stay
  disabled until the required live validation succeeds; a contract or
  secret-bearing-response fault can remain latched.
- **HTML loads but data/assets fail:** keep API and assets on the same origin,
  inspect failed browser requests and proxy paths, and verify the image's
  bundled asset/build metadata. Offline use does not require fetching a new UI.
- **429:** respect the configured read/command bounds and normal polling cadence.
  Retain the failure details rather than removing the boundary.

Record image/panel identities, node, timestamp, page/command ID, redacted outcome
and the first unfinished action. Keep browser cookies, authorization headers,
raw logs, private inputs and payloads out of handoff reports.