bootstrap

Hydrogen Desktop (macOS / Lima)

Public Made by Adom

by adom

The macOS platform layer for Hydrogen Desktop.

bootstraphydrogen-desktophdmacosmaclimanspawn
Overview Files Skills Discover Packages Releases Dependencies Issues Breadcrumbs Pull Requests Activity
hd-mac-bootstrap / skills / hd-container-stats / SKILL.md
Download

name: hd-container-stats description: HD's workspace stats indicator in the top-right of the title bar — two thin progress bars (CPU + RAM) labelled "Container" plus an info tooltip on hover that shows the workspace name, CPU vs total cores, RAM usage vs limit, disk usage, image/machine, ID, and creation date. Polls once per second when running, every 5 seconds when stopped. Status badges show stopped / starting / restarting / restart-needed states. Use this skill when the user asks about CPU/RAM usage, the resource bars in HD's title bar, workspace disk usage, the "restart needed" badge, why bars are red/yellow, or what's in the tooltip. Trigger words — container stats, workspace stats, container cpu, container ram, container disk, resource bars, cpu bar, ram bar, container tooltip, container indicator, top bar stats, restart needed badge, container stopped badge, container starting, workspace_stats, machine stats, machine runtime stats.

HD Workspace Stats Indicator

This is the machine-runtime version (default). The legacy Docker equivalent (HD_RUNTIME=docker) is in the docker/ bucket.

The top-right of HD's title bar (next to the audio/video icons and your profile avatar) shows a tiny Container block with two horizontal progress bars — CPU% and RAM% — that animate in real-time. Hovering brings up a tooltip with the full workspace details. Under the machine runtime these numbers now reflect the Adom-Workspace machine, not a Docker container — but the UI is unchanged, so the header still reads "Container".

How often it polls

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

  • Every 1 second when the workspace is running — for live, smooth bar animation
  • 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'). This command no longer reaches into Docker directly — it dispatches through the runtime trait: WorkspaceRuntime::get_stats → MacosVmRuntime::get_stats → workspace_stats(), a machine health/stat probe of the Adom-Workspace machine. (Under HD_RUNTIME=docker the same command routes to the Docker impl instead.) The probe runs with short timeouts so a hung Lima VM or machine can't freeze the UI.

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.

What the bars show

Bar What it measures Source
CPU % of the machine's available CPU being consumed (1.0 = 1 full vCPU). Capped at 100% display workspace_stats() machine probe
RAM % of the machine's memory in use vs its limit workspace_stats() machine probe

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 Adom-Workspace (the machine name)
CPU + RAM totals `CPU: 1.7% of 16 cores
Disk Disk: 1.3 GB (machine disk usage)
Image Image: Ubuntu 24.04 (Adom-Workspace) (the imported machine image)
ID Adom-Workspace (the registered machine 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)
  • Workspace runtime is broken — restart from the menu (when the machine/code-server is unreachable, e.g. after sleep/hibernate)

Status badge in the header

The Container text in the section header gets an inline status badge depending on state:

Badge Meaning Color
(no badge) Running normally normal
stopped Machine registered but not running red
starting HD is starting the machine / code-server yellow
restarting HD is restarting the machine yellow
restart needed The machine or code-server is unreachable (usually a Lima/machine hiccup after Mac wake) red

When restart needed shows, open the Adom menu → Restart Workspace (see the hd-ui skill for the Adom menu). A "Restart" here is machinectl terminate Adom-Workspace + re-ensure code-server — NOT docker restart.

How it works under the hood

  • Polling frequency: see "How often it polls" above — 1s when running, 5s when not.
  • Backend command: Tauri invoke('get_container_stats') → WorkspaceRuntime::get_stats. In machine mode that is MacosVmRuntime::get_stats → workspace_stats(). NO docker exec, NO cgroup file reads, NO bollard stats() — those were the Docker-runtime mechanism and do not run on the machine path.
  • Two health levels (workspace_stats() checks both): (1) is the Lima VM (hd-builder) up + the Adom-Workspace machine booted; (2) is Adom-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.
  • Rate-limited error logging: the "needs restart" log line is printed at most once every 30 seconds, even though the frontend polls every 1s, so the log stays readable.

The benign [docker] unhealthy log line

You will sometimes see this in HD's log even on the machine path:

[docker] Container runtime unhealthy — exec failed, needs restart

On the machine path this is BENIGN NOISE. It's a leftover hd-docker heartbeat with no container bound to it — there is no Docker container in machine mode, so "exec failed" is expected and meaningless. It does NOT mean your workspace is broken.

The real machine health signal to watch for is:

[macos] Workspace unhealthy …

That line (not the [docker] one) reflects the actual Adom-Workspace machine state. And the authoritative "which runtime am I on" line is [app] Active workspace runtime: MacosMachine.

API access

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

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

(Reach the control API at the adom-host gateway — vz does NOT mirror loopback, so the machine's /etc/hosts maps adom-host to the gateway where HD's host listener lives. The port is dynamic per launch; read the live URL from ~/.adom/hd-control-url — already pointing at the gateway host — rather than hardcoding it.)

Returns JSON like:

{
  "ok": true,
  "container_name": "Adom-Workspace",
  "container_id": "Adom-Workspace",
  "container_created": "2026-05-24T20:18:09Z",
  "image": "Ubuntu 24.04 (Adom-Workspace)",
  "cpu_percent": 1.7,
  "cpu_cores": 16,
  "mem_usage_mb": 716,
  "mem_limit_mb": 16384,
  "mem_percent": 4.4,
  "disk_usage_mb": 1300
}

Or if the workspace is in a broken state:

{ "ok": false, "needs_restart": true, "error": "Workspace needs restart" }

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)
Bar percentage label .resource-bar-value
Hover tooltip container .resource-bars-tooltip
One tooltip line .resource-bars-tooltip-row

Common questions

"Why is CPU showing 200% / 1600%?" It's not — the displayed % is capped at 100 for the bar fill, but the tooltip shows the real number. CPU of 100% of 16 cores means 1 full vCPU pegged.

"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 machine all the time. ~700 MB baseline is normal.

"The 'restart needed' badge appeared — what happened?" Almost always a Lima/machine hiccup after Mac wake/sleep, leaving the machine or code-server unreachable. Click Restart Workspace in the Adom menu (top-left). HD will machinectl terminate Adom-Workspace, re-ensure code-server, and the badge clears.

"The log says [docker] … unhealthy — is my workspace broken?" No. On the machine path that line is a benign leftover heartbeat with no container bound. Look at [macos] Workspace unhealthy … for the real signal. See "The benign [docker] unhealthy log line" above.

"Disk is 1.3 GB — does that include my project files?" Yes — on the machine path there is no separate Docker volume; /home/adom/project lives inside the machine, so the Disk: figure is the machine's on-disk size including your project.