Monitoring

Monitor your entire Banyan cluster — engine health, agents, deployments, and containers — from a web browser, the terminal, or your existing Prometheus setup.

Web dashboard

Open the dashboard in your browser:

banyan-cli dashboard --web

  Banyan Dashboard

  Local:   http://localhost:3000
  Engine:  http://10.200.0.1:9091

  Press Ctrl+C to stop

The CLI starts a local web server, opens your browser, and proxies API calls to the engine. The dashboard is embedded in the CLI binary — no npm, no Node.js runtime, no separate installation.

Pages

Page	What it shows
Overview	Stat cards (engines, agents, deployments, containers, tasks), containers table, recent events
Agents	All agents with CPU, memory, disk, subnet, tags. Click to see agent detail
Deployments	All deployments with health, services, tags. Click to see services and containers
Containers	Flat container list with status, CPU, memory, sparklines. Filter by name, service, or agent
Engine	Engine status, uptime, CPU/memory/disk with progress bars
Events	Full event log with severity badges and timestamps
Logs	Container log viewer — select a container, fetch recent lines, auto-refresh

Click any row to drill into its detail page. Agent names, deployment names, and container names are cross-linked — click an agent name on a container row to jump to that agent’s detail page.

Press Ctrl+K (or Cmd+K on Mac) to open the command palette. Type to search across pages, agents, deployments, and containers. Arrow keys to navigate, Enter to select.

Custom port

banyan-cli dashboard --web --port 8080

Running for your team

To make the dashboard available to your team, run it as a systemd service behind a reverse proxy:

[Unit]
Description=Banyan Web Dashboard
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/banyan-cli dashboard --web --port 3000
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now banyan-dashboard

Then configure nginx or caddy to reverse proxy to localhost:3000.

Terminal dashboard

Open the dashboard:

banyan-cli dashboard

The dashboard connects to your engine and shows live cluster state, updating every 5 seconds. Everything runs in your terminal — no browser, no Grafana, no configuration files.

Views

Switch views by pressing the corresponding number key:

Key	View	What it shows
`1`	Overview	Engine health, cluster summary, agents, deployments, and recent events — all on one screen
`2`	Agents	All connected agents with CPU, memory, disk usage, and container count
`3`	Deploys	Deployments grouped by name, with health status and version history
`4`	Containers	Every container across the cluster — status, image, agent, and replica info
`5`	Engine	Detailed engine metrics with CPU, memory, and disk progress bars
`6`	Events	Full event log — every cluster event from newest to oldest, with scrolling

Key	Action
`↑` / `k`	Move up
`↓` / `j`	Move down
`Enter`	Drill into agent or deployment details
`Esc`	Go back (clears filter first if active)
`p`	Open command palette
`/`	Filter current list
`e`	Export current list to CSV
`r`	Refresh data
`?`	Show keyboard shortcuts
`q`	Quit

Lists scroll automatically when they’re longer than the screen — navigate to the bottom and the view follows, like htop.

Filtering

Press / on any list view (Agents, Deploys, Containers, Events) to start typing a filter. The list narrows in real time as you type — matching against names, statuses, tags, and other visible fields. Press Enter to lock the filter, or Esc to cancel. Press Esc again to clear an applied filter.

Filtering is case-insensitive. For example, typing worker on the Agents view shows only agents with “worker” in their name.

Export to CSV

Press e on any list view to export the current data to a CSV file in the working directory. If a filter is active, only the filtered rows are exported. The filename includes the view name and timestamp — banyan-agents-2026-02-27-143022.csv.

Command palette

Press p to open the command palette. Type to search across all available actions. The palette is organized into sections:

Actions — page-specific actions like Filter and Export CSV. These only appear when you’re on a list view.
Navigate — switch between views (Overview, Agents, Deploys, Containers, Engine, Events).
Commands — global actions like Refresh and Quit.

Refresh interval

The default refresh is 5 seconds. For a slower refresh:

banyan-cli dashboard --refresh 30s

Prometheus metrics

The engine exposes a /metrics endpoint in Prometheus format. When the engine starts, it prints:

Prometheus metrics available at :9090/metrics

Add Banyan to your Prometheus config

Add a scrape target to your prometheus.yml:

scrape_configs:
  - job_name: banyan
    static_configs:
      - targets: ["your-engine-host:9090"]  # Replace with your engine's address

Reload Prometheus, and metrics start flowing.

Available metrics

All metrics use the banyan_ prefix.

Engine

Metric	Type	Description
`banyan_engine_uptime_seconds`	Gauge	Seconds since engine started
`banyan_engine_cpu_usage_ratio`	Gauge	Engine host CPU usage (0.0–1.0)
`banyan_engine_memory_used_bytes`	Gauge	Engine host memory in use
`banyan_engine_memory_total_bytes`	Gauge	Engine host total memory
`banyan_engine_disk_used_bytes`	Gauge	Engine host disk usage
`banyan_engine_disk_total_bytes`	Gauge	Engine host total disk

Cluster

Metric	Type	Labels	Description
`banyan_cluster_agents_total`	Gauge		Total registered agents
`banyan_cluster_agents_connected`	Gauge		Currently connected agents
`banyan_cluster_deployments_total`	Gauge	`status`	Deployments by status (running, stopped, etc.)
`banyan_cluster_containers_total`	Gauge		Total containers across all agents
`banyan_cluster_containers_healthy`	Gauge		Currently healthy containers
`banyan_cluster_tasks_total`	Gauge	`status`	Tasks by status

Per-agent (labeled by agent)

Metric	Type	Description
`banyan_agent_cpu_usage_ratio`	Gauge	Agent CPU usage (0.0–1.0)
`banyan_agent_memory_used_bytes`	Gauge	Agent memory in use
`banyan_agent_memory_total_bytes`	Gauge	Agent total memory
`banyan_agent_disk_used_bytes`	Gauge	Agent disk usage
`banyan_agent_disk_total_bytes`	Gauge	Agent total disk
`banyan_agent_containers_total`	Gauge	Containers on this agent
`banyan_agent_info`	Gauge	Agent metadata (status, subnet) — value is always 1

Per-deployment (labeled by deployment)

Metric	Type	Labels	Description
`banyan_deployment_replicas_desired`	Gauge	`service`	Desired replica count per service
`banyan_deployment_replicas_healthy`	Gauge	`service`	Healthy replica count per service
`banyan_deployment_info`	Gauge	`status`, `strategy`	Deployment metadata — value is always 1

Events

Metric	Type	Labels	Description
`banyan_events_total`	Counter	`type`	Cumulative event count by type

Example queries

Check if all agents are connected:

banyan_cluster_agents_connected == banyan_cluster_agents_total

Find unhealthy deployments:

banyan_deployment_replicas_healthy < banyan_deployment_replicas_desired

Memory usage per agent as a percentage:

banyan_agent_memory_used_bytes / banyan_agent_memory_total_bytes * 100

Alert when an agent goes down:

# Example Prometheus alert rule
groups:
  - name: banyan
    rules:
      - alert: BanyanAgentDown
        expr: banyan_cluster_agents_connected < banyan_cluster_agents_total
        for: 1m
        labels:
          severity: warning
        annotations:
          summary: "Banyan agent disconnected"

Custom metrics port

The engine serves metrics on port 9090 by default. To change it, set the metrics_port field in your engine config at /etc/banyan/banyan.yaml:

engine:
  metrics_port: "8080"

What’s next

CLI Reference — dashboard for all flags and keyboard shortcuts
Redeployment to update running apps with zero downtime