main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-container-stats description: >- Hydrogen's title-bar workspace stats indicator on Linux: the CPU and RAM bars (app half and workspace half), their tooltip (cores, RAM, disk, image), polling, the cgroup numbers, and the stopped/starting/restart-needed badges. Use when asked about container stats, the resource bars, workspace disk usage, OOM kills, or the restart needed badge.

Hydrogen Workspace Stats Indicator

The top right of Hydrogen's title bar shows a small block titled Adom with a CPU bar and a RAM bar. Each bar has two segments: Hydrogen itself (the app and its panes) and the workspace (the Adom-Workspace systemd-nspawn machine). Hovering shows the details.

How often it polls

There's an active polling loop in Hydrogen's title bar that asks the runtime for fresh stats on a timer:

  • Every 2 seconds when the workspace is running
  • Every 5 seconds when it's stopped, starting, restarting, or restart needed — saves cycles when nothing's changing

Each poll calls Tauri invoke('get_container_stats'), which dispatches through the runtime trait (WorkspaceRuntime::get_stats) to the active host's probe. The probe runs with short timeouts so a hung host subsystem can't freeze the UI.

On Linux that probe is workspace_stats() in the hydrogen-runtime crate, whose numbers come from its linux_stats module.

If you ever want to lighten the load (e.g. on a battery-constrained laptop), the relevant code is in EditorNav.svelte's pollStats() closure — adjust the pollInterval ternary.

Where the numbers come from on Linux

The machine shares the host kernel, so the workspace's own /proc/meminfo, /proc/stat and the kernel OOM counter describe the whole PC, not the workspace. Never quote those as workspace numbers. Hydrogen reads the workspace's cgroup instead:

  • cgroup: /sys/fs/cgroup/machine.slice/[email protected] (or machine-Adom-Workspace.scope)
  • RAM in use: memory.current minus inactive_file; limit: memory.max, else the PC's RAM
  • CPU: cpu.stat usage_usec delta, as a percent of all cores
  • OOM kills inside the workspace: memory.events oom_kill
  • Disk: a background du -sxm / inside the machine, at most every 10 minutes (reads 0 until the first run lands)

What the bars show

Bar What it measures
CPU % of all the PC's cores the workspace is using (from the cgroup). Capped at 100% display
RAM % of the workspace's memory in use vs its limit

Both bars share the same color-threshold rules:

  • Teal / green — ≤ 50% usage (normal)
  • Yellow (warn class) — 51-80% usage
  • Red (danger class) — > 80% usage

What the tooltip shows

When you hover over the bars, a tooltip appears with:

Line Example
Container the workspace name
CPU + RAM totals `CPU: 1.7% of 16 cores
Disk Disk: 1.3 GB (workspace disk usage)
Image Image: systemd-nspawn: Adom-Workspace
ID the registered workspace identifier
Created 5/24/2026, 3:18:09 PM (locale-formatted)

If the workspace is in a non-healthy state, the tooltip shows a single red line instead:

  • Workspace is stopped: start from the menu (when stopped)
  • Container runtime is broken, restart from the menu (when the machine or code-server is unreachable)

Status badge in the header

The Adom header carries a status word: workspace stopped (red), workspace starting / workspace restarting (yellow), workspace restart needed (red: the machine or code-server is unreachable), or disk almost full (the filesystem holding /var/lib/machines is nearly full). No word means it is running normally.

Fix: Adom menu > Restart Container (stops the machine through machinectl and starts it again; see hydrogen-workspace-lifecycle).

How it works under the hood

  • Polling frequency: see "How often it polls" above: 2 s when running, 5 s when not.
  • Backend command: Tauri invoke('get_container_stats') → WorkspaceRuntime::get_stats, routed to the active host runtime's probe.
  • Two health levels the probe checks: (1) is the host runtime itself available; (2) is the workspace registered + running with code-server reachable on host port 7380. If either fails, the probe returns a needs-restart signal instead of stats and the UI shows the red "restart needed" badge.

The authoritative "which runtime am I on" log line is [app] Active workspace runtime: ... (on Linux it names the nspawn host runtime).

API access

If you want the same stats data your AI can hit directly via the control API:

# From inside the workspace — query the control API on the host
curl -s "$(cat ~/.adom/hydrogen-control-url)/container-stats"

(Read the live URL from ~/.adom/hydrogen-control-url rather than hardcoding it — the port is dynamic per launch.)

Key fields on Linux:

Field Meaning
runtime "nspawn_host"
container_name, container_id Adom-Workspace
image "systemd-nspawn: Adom-Workspace"
image_note, image_version the golden image version (for example v31-full)
stats_source "cgroup"
cpu_percent, cpu_cores, mem_usage_mb, mem_limit_mb, mem_percent, oom_kills the workspace's own numbers
disk_usage_mb the cached du result
machine_mem_total_mb, machine_mem_avail_mb, machine_cpu_percent the whole PC
app Hydrogen's own process tree
host_disk free/total MB of the filesystem holding /var/lib/machines (df), behind the "disk almost full" badge
internet_reachable can the workspace reach the internet

Or if the workspace is in a broken state:

{ "ok": false, "needs_restart": true, ... }

CSS selectors

Element Selector
The whole indicator block .resource-bars
Header with title + status badge .resource-bars-header
Title text ("Container") .resource-bars-title
One bar row (CPU or RAM) .resource-bar-item
Bar fill .resource-bar-fill (modifier classes: .warn, .danger)
App segment of a bar .seg-app
Bar percentage label .resource-bar-value
Hover tooltip container .resource-bars-tooltip
One tooltip line .resource-bars-tooltip-row

Common questions

"Why does RAM stay constant at ~4% even when I'm doing nothing?" Code-server, the relay, the adom-vscode HTTP API, etc. all run in the workspace all the time. ~700 MB baseline is normal.

"The workspace shows OOM kills." Those are kills inside the workspace's cgroup. Kills of host programs (KiCad and others) are not counted here.

"Disk is 1.3 GB — does that include my project files?" Yes — /home/adom/project lives inside the workspace, so the Disk: figure includes your project.

  • [[hydrogen-workspace-monitoring]] — the 15s state poll + floaty states behind these badges
  • [[hydrogen-container]] — workspace context: relay, bridges, env vars
  • [[hydrogen-workspace-lifecycle]]: start, stop, restart, reset
  • [[hydrogen-networking]]: code-server on 7380, the control port