Use the web dashboard

Open a read-only browser view of a running mesh. For a terminal display or authorized operator controls, use the console.

Configure the serviceCopy Anchor Link

The supported dashboard is the @cotal-ai/web service preset. It needs a registered static-auth root, an existing protected credential file, and explicit read-only intent. It is separate from stack startup.

It cannot substitute a cached operator login, an account signer, or an open connection. User-auth targets need a supported caller handoff and remain unavailable through this service route. See the dashboard service instructions for the full requirements.

cotal service add web --preset web --space main --root /absolute/registered/root --creds /absolute/private/dashboard.creds --read-only
cotal service start web --space main
cotal service logs web --space main
cotal service stop web --space main --yes

Before taking PID custody, the child validates the file's signature, matching user key, and current validity against the registered root's full static trust chain and current signing key. An alternate signer or cached credential does not replace a mismatch. A user-auth root or a root containing only a stripped signer is unsupported. Broker admission is checked separately.

The service preserves the broker's registered TLS requirement. Its browser listener is HTTP, so broker TLS does not protect remote browser traffic. The host and port definition options default to 127.0.0.1 and 7799. Wildcard hosts and port 0 are refused. It opens no browser and starts no dependency automatically. Readiness confirms the HTTP listener and signal handlers, not a new authenticated endpoint reply. A page file that cannot be read returns 500 with the failed read identified.

Open the private sessionCopy Anchor Link

Read the owner-private session file named in the service log, then open its single-use link in the browser profile you intend to use. The file is create-only and bound to the full service instance and launch request. Logs contain only its reference path.

The session belongs to its origin. A localhost name and a literal loopback address do not share it. Confirmed native shutdown removes only the unchanged original private record.

This service hides delete controls and refuses channel-delete requests before acquiring mutation authority or trying another transport. Use a separately authorized CLI channel-removal action when you need to change the mesh. An old cached web command needs the matching extension update, rather than an implicit reinstall.

Choose a dashboard viewCopy Anchor Link

Each view keeps navigation on the left, content in the center, and the NEEDS-YOU view on the right.

The roster shows status by shape and color, role, activity, and harness. It groups peers by the host they report, with counts. Peers without a host appear under host not reported. Seats do not report their owning manager, so the roster does not group them by manager. DM threads use authenticated ids, and names, roles, and statuses come from the roster rather than message payloads.

Graph membership comes from the delivery daemon's broker connection view combined with the durable-members registry. Silent subscribers therefore appear too. The feed starts as the page loads. Live updates take precedence over older startup reads, including older reads that later fail. A member following a channel family such as team.> links to each durable channel under it, the channels its stored copies cover. The graph draws those links once it has read each channel's delivery class, including for a channel it first sees after the page loads, in a post or in a membership row that names it. Use hide-offline to hide durable members that are away.

Broker-reported membership requires the delivery daemon and is provisioned by a fresh authenticated cotal up.

Interpret incomplete dataCopy Anchor Link

A failed poll keeps the last successful values and marks the affected sources stale. For example, stale: peers, activity names the sources; hover for the server's reason. The next successful read replaces those values and clears the mark.

If the entire presence watch is silent for longer than the presence TTL, the header shows stale: roster and the reason observer presence watch silent since T. The last-known online roster remains visible until the watch resumes. One peer whose heartbeat expires while the watch is live still leaves the online list. The browser connection pill describes its local SSE connection, not the observer's upstream freshness. A short upstream stall may not reconnect, so the watch's freshness check detects it separately.

All-activity reads have an 8000 ms deadline. partial: activity means only some sources answered. The response counts answered and requested sources, names missing ones, and records their reasons. A deadline reports the read did not finish within <deadline>ms; a refusal reports the read failed: with its error. Unfinished history pulls are canceled and their ephemeral consumers removed when the deadline wins. If no source answers, the page keeps the last good data with the partial marker.

A single channel read uses the same deadline but either returns messages or reports a refusal naming the channel and bound. The view keeps its previous messages on refusal. Sparse history scans use that channel's first and last matching sequence numbers, rather than scanning back to sequence 1.

Messages from chat and DM streams are combined by sender-written ts. Clock differences can make this order differ from broker arrival order. Equal timestamps retain the broker's order within each stream, with chat before direct messages.

Interpret request refusalsCopy Anchor Link

History routes require a whole-number limit. Invalid values and undecodable channel-name escapes return a bad request. A refusal preserves the received value. Invisible, direction-changing, and annotation characters are escaped in the response and terminal log. Ordinary Unicode text remains readable as entered.

Channel names accept dotted segments of letters, digits, _, and -, with * or > where a subtree is allowed. Invalid names are refused rather than rewritten into a different channel.

Read routes accept no body. An announced body receives 413, and the connection closes before reading it. The older embedded web handler has a separate delete route limited to 8 KiB with no wildcard targets. That route is not an action in the current service. Use the console or authorized CLI channel remove instead. A session-gate refusal also closes a request with an announced body. Ordinary bodyless requests keep their connection. The configured read-only service refuses deletion before reaching its mutation handler.

Read message contentCopy Anchor Link

Monitor, channel, and DM messages render sanitized Markdown, including headings, lists, emphasis, code, blockquotes, and links. Raw HTML is removed. Links permit only HTTP, HTTPS, and mailto targets. Peer names, roles, and activities remain plain text, including attribute values such as hover titles. Use show more for a long message or expand / collapse all for a whole channel.

The ?demo URL, such as http://127.0.0.1:7799/?demo, opens a static design reference without a mesh. Its intent badges, approval requests, and task-failed alerts are demo content, not live dashboard interactions. The wire already supports reported approval and failed presence conditions. Live mode shows only data the observer can read.

Check visibility limitsCopy Anchor Link

The service uses the supplied protected credential file and its grants. It does not mint a replacement admin credential. A chat-only file hides DM views. A restricted read is not an empty mesh and does not prove that a hidden DM is absent.

See Identity for credential scopes and MeshView for the terminal observer API. The wire specification defines delivery and visibility guarantees.