> ## Documentation Index
> Fetch the complete documentation index at: https://notes.kodekloud.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Driving the Nomad UI
> Guide showing how Nomad web UI mirrors HTTP API and CLI for safe cluster inspection, viewing topology, allocations, logs, and enforcing ACL based permissions
Tidepool used to be a team of six engineers. They just hired Nadia, their first support engineer, and her first ticket is simple: a customer reports that exports are failing.
Nadia would normally interrupt Maya, but Maya is unavailable. All Nadia needs to know is whether the relevant job is running and healthy — but she's not comfortable with the terminal and doesn't want to risk breaking anything by running commands she doesn't fully understand.
Fortunately, the cluster already exposes everything she needs via Nomad's web UI. Nomad's HTTP API listens on port `4646`, and the same API powers a full web interface at the `/ui` path. There's nothing to install or enable — open it in a browser, for example at `http://localhost:4646/ui`.
You can perform the same checks from the command line (for example, with `nomad` subcommands that call the HTTP API), but the web UI queries the exact same API and enforces the same permissions. It's the same cluster state, just a different lens.
Nomad starts with a topology view, which is available under the Cluster section of the navigation.
The topology view visualizes every client machine and every allocation running on each node. It also shows each node's total memory and CPU capacity and displays percentages beside those metrics.
The percentages shown represent how much capacity has been reserved by allocations, not the current runtime utilization. These numbers reflect reserved resources (scheduling reservations) and should not be interpreted as live CPU or memory load.
For a support engineer like Nadia, the topology view is useful for a quick, non-invasive check: are expected nodes present, are allocations placed where they should be, and are any nodes or allocations reported as unhealthy? From there she can follow the same investigative path Maya would use in the terminal.
Open the job in the UI to see the job's configured count and the list of allocations beneath it. Clicking an allocation shows:
* Which client node the allocation is running on
* The allocation's resource reservations (CPU, memory)
* The event history (task started, task exited, restarting, etc.)
You can also view task-level details. The UI provides live log streaming per task and lets you jump to the end of the logs — the same output you would get from:
```bash theme={null}
nomad alloc logs
```
For interactive troubleshooting, the UI exposes an exec page that opens a real interactive shell into a running task over a WebSocket connection — essentially the browser equivalent of `nomad alloc exec`:
```bash theme={null}
nomad alloc exec -task /bin/sh
```
Security and access control are the reason remote shells are not universally available. Nomad’s ACL system issues tokens and associates each token with policies that define permitted actions. The web UI asks for a token and enforces the same ACL policy checks as the HTTP API.
In Nadia’s case, her token grants read-only access to jobs and allocations. She can view any screens required for diagnosis, but the exec page refuses her because her token does not include the `alloc:exec` capability. The behavior is identical whether she uses the UI or the CLI — permissions are tied to the token, not the tool.
Be careful when granting `alloc:exec` or similar high-privilege capabilities. Exec access provides an interactive shell inside tasks, which can expose sensitive data or allow accidental changes to running services.
Think of the UI as a graphical, picture-based presentation of the same API data and permission checks the CLI uses. The UI is an excellent, safe-first tool for quick cluster inspection and troubleshooting. Maya still prefers the terminal for scripting and repeatable automation, but when a machine is misbehaving, the topology view and the UI are fast, clear, and low-risk for initial investigation.
Quick reference: UI vs CLI common actions
| Action | UI location / behavior | CLI equivalent |
| - | -: | - |
| View topology and node allocations | Cluster → Topology | `nomad node status`, `nomad alloc status` |
| See job count and allocations | Job page → Allocations list | `nomad job status ` |
| Stream or tail logs | Task → Logs (live stream / jump to end) | `nomad alloc logs ` |
| Open an interactive shell in a task | Task → Exec (WebSocket shell) | `nomad alloc exec -task /bin/sh` |
| Permissions enforced | UI asks for token; enforces ACLs | CLI reads token from `NOMAD_TOKEN` or `~/.nomad-token` |
Links and references
* Nomad UI and HTTP API documentation: [https://www.nomadproject.io/docs](https://www.nomadproject.io/docs)
* Nomad ACLs and policies: [https://www.nomadproject.io/docs/acl](https://www.nomadproject.io/docs/acl)
* Nomad CLI reference: [https://www.nomadproject.io/docs/commands](https://www.nomadproject.io/docs/commands)
With these tools and controls in place, Nadia can confidently inspect the failing export job without touching production systems, and escalate to Maya with a clear summary if deeper intervention is required.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.