Adom Hydrogen (Linux)
Public Made by Adomby adom
The Linux platform layer for Adom Hydrogen: Ubuntu, Debian and Fedora, the workspace and the computer.
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, orrestart 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](ormachine-Adom-Workspace.scope) - RAM in use:
memory.currentminusinactive_file; limit:memory.max, else the PC's RAM - CPU:
cpu.statusage_usecdelta, as a percent of all cores - OOM kills inside the workspace:
memory.eventsoom_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 (
warnclass) — 51-80% usage - Red (
dangerclass) — > 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.
Related skills
[[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
---
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 | RAM: 0.7 GB / 16.0 GB` |
| 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:
```bash
# 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:
```json
{ "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.
## Related skills
- `[[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