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-workspace-monitoring description: >- How Hydrogen on Linux monitors the workspace machine and code-server: the 15 s state poll, the 8 s backend watch, the stopped floaty, auto-start, editor auto-reload, and the lifecycle dialog. Use when asked why the workspace stopped, about the workspace floaty, Start or Restart workspace, or before changing workspace state code.
Hydrogen Workspace Monitoring (Linux)
Architecture
The workspace is Hydrogen's local code-server-backed dev environment. Hydrogen monitors workspace health at two levels:
- Runtime available — is the workspace runtime itself installed and responding on this machine?
- Workspace healthy — is the workspace present AND Running AND is code-server reachable on its host port?
The second level is a real reachability check, not just "is the workspace present." A resume reality-check (after sleep, or after a Hydrogen rebuild/relaunch) requires code-server to actually answer before Hydrogen trusts the workspace as healthy — a workspace can be Running while code-server is dead.
On Linux the runtime is present when machinectl and systemd-nspawn exist and the
helper answers; the workspace is healthy when the Adom-Workspace machine exists, is
running, and code-server answers on host port 7380.
Status reads (is the image there, is it running) use unprivileged machinectl;
only actions (start, stop, exec, import, remove) go through the root helper.
Health probes read /proc and the shared loopback directly, with no exec.
The VS Code panel (PanelVisualStudioCode.svelte) polls workspace state every
15s and shows appropriate UI for each state. These frontend components are
runtime-agnostic; they front the active runtime via the runtime trait.
Workspace State Poll
PanelVisualStudioCode.svelte calls get_container_status (Tauri command)
every 15s. The command dispatches through the runtime trait to the active
runtime impl. Returns a status struct shaped like:
pub struct ContainerStatus {
pub runtime_available: bool, // machinectl + helper usable
pub workspace_installed: bool, // the machine image is present
pub container_exists: bool, // the machine exists (running or stopped)
pub container_running: bool, // running AND code-server reachable
pub container_id: Option<String>,
pub error: Option<String>,
}
The container_* names are historical.
Every 8 s, once the editor has loaded, the panel also reads GET /workspace/health. Two
misses of editor_will_load (a real HTTP check of code-server) raise a banner over the
editor. A deliberate Stop has its own screen instead.
Floaty States
All floaties appear INSIDE the VS Code panel only — not as full-app modals. They are draggable (grab header to move). The rest of the app (wiki tab, menu, etc.) remains fully interactive.
- Workspace stopped (the machine is not running): "Your Linux workspace has
stopped. Your files are safe; Start brings it back." Start calls
POST /container-start. - Editor not answering (machine running, code-server not serving): a
Reconnect banner. Its button posts
/wake/simulate, which does nothing on Linux (seehydrogen-wake-repair); use Restart workspace instead. - Disk almost full: the message names the drive and asks to free space on that disk.
A missing runtime or a workspace not built yet shows no floaty: that is the
setup cascade's job (see hydrogen-setup). There is no runtime repair button on
Linux.
Separately, a watcher looks every 15 s for VS Code's "Cannot reconnect" dialog
and reloads only the editor pane when code-server is serving (see
hydrogen-wake-repair).
Auto-Start via setup_and_start
The "Start Workspace" path calls Tauri setup_and_start, which delegates to
the active runtime's setup_and_start:
- If the workspace isn't present yet,
fresh_import= download the golden image + provision the workspace + start code-server. - If the workspace is present but code-server is down, it just (re-)starts code-server.
On Linux it first makes sure the host is ready (the helper and its sudoers rule, one pkexec prompt only if missing).
code-server runs as code-server.service inside the machine, so it does not die with
Hydrogen, and Hydrogen re-ensures it on every launch. See hydrogen-workspace-lifecycle
for the full lifecycle detail.
Lifecycle Dialog
ContainerLifecycleDialog.svelte — a draggable floating card (no background
blur) that shows live command output for start/stop/restart operations on the
workspace.
Events
Listens for hydrogen-container-lifecycle CustomEvents on window:
action: 'restart' | 'stop' | 'start'— opens dialog, starts spinneraction: 'step', step: string— appends a log lineaction: 'done'— stops spinner, shows Close button, auto-reloads VS Codeaction: 'stopped'— stops spinner (for stop-only operations)action: 'error', message: string— shows error state
Title
Dynamic based on actionType:
- Restarting: "Workspace Restarting..." → "Restart Complete"
- Stopping: "Stopping Workspace..." → "Workspace Stopped"
- Starting: "Starting Workspace..." → "Workspace Started"
- On error: "Restart/Stop/Start Failed"
VS Code Auto-Reload
After the done event, the dialog polls /workspace/health every 5s for up to 2 minutes
and reloads the editor once editor_will_load is true. After an error it keeps checking
for 15 minutes and closes itself if the workspace answers again.
Tauri Commands
| Command | What it does |
|---|---|
get_container_status |
Returns workspace status — runtime available, workspace present, Running + code-server reachable |
setup_and_start |
Host prep, fresh_import if no machine yet, boot, start code-server |
stop_container |
Stops the workspace |
On Linux stop_container powers off Adom-Workspace (helper, machinectl poweroff, then
terminate if it hangs).
Menu Items (Adom Menu → Workspace Section)
- Restart Container: stop the machine, then re-ensure code-server; emits lifecycle events, shows the dialog
- Stop Container: powers off the machine; emits lifecycle events, shows the dialog, then the stopped floaty
- Start: from the stopped floaty
Settings
hydrogen.launch_on_boot(Launch on boot), default off. On Linux it writes~/.config/autostart/adom-hydrogen.desktop(honoured by GNOME, KDE, Cinnamon).
Related skills
hydrogen-workspace-lifecycle— provision/export/remove/stop, the never-touch-global rule, control endpointshydrogen-container-stats— the title-bar CPU/RAM bars andworkspace_stats()probehydrogen-networking— code-server port, control port
---
name: hydrogen-workspace-monitoring
description: >-
How Hydrogen on Linux monitors the workspace machine and code-server: the 15 s
state poll, the 8 s backend watch, the stopped floaty, auto-start, editor
auto-reload, and the lifecycle dialog. Use when asked why the workspace
stopped, about the workspace floaty, Start or Restart workspace, or before
changing workspace state code.
---
# Hydrogen Workspace Monitoring (Linux)
## Architecture
The workspace is Hydrogen's local code-server-backed dev environment. Hydrogen monitors
workspace health at two levels:
1. **Runtime available** — is the workspace runtime itself installed and
responding on this machine?
2. **Workspace healthy** — is the workspace present AND Running AND is
code-server reachable on its host port?
The second level is a real reachability check, not just "is the workspace
present." A resume reality-check (after sleep, or after a Hydrogen rebuild/relaunch)
requires code-server to actually answer before Hydrogen trusts the workspace as
healthy — a workspace can be Running while code-server is dead.
On Linux the runtime is present when `machinectl` and `systemd-nspawn` exist and the
helper answers; the workspace is healthy when the `Adom-Workspace` machine exists, is
running, and code-server answers on host port **7380**.
Status reads (is the image there, is it running) use unprivileged `machinectl`;
only actions (start, stop, exec, import, remove) go through the root helper.
Health probes read `/proc` and the shared loopback directly, with no exec.
The VS Code panel (`PanelVisualStudioCode.svelte`) polls workspace state every
15s and shows appropriate UI for each state. These frontend components are
runtime-agnostic; they front the active runtime via the runtime trait.
## Workspace State Poll
`PanelVisualStudioCode.svelte` calls `get_container_status` (Tauri command)
every 15s. The command dispatches through the runtime trait to the active
runtime impl. Returns a status struct shaped like:
```rust
pub struct ContainerStatus {
pub runtime_available: bool, // machinectl + helper usable
pub workspace_installed: bool, // the machine image is present
pub container_exists: bool, // the machine exists (running or stopped)
pub container_running: bool, // running AND code-server reachable
pub container_id: Option<String>,
pub error: Option<String>,
}
```
The `container_*` names are historical.
Every 8 s, once the editor has loaded, the panel also reads `GET /workspace/health`. Two
misses of `editor_will_load` (a real HTTP check of code-server) raise a banner over the
editor. A deliberate Stop has its own screen instead.
## Floaty States
All floaties appear INSIDE the VS Code panel only — not as full-app modals.
They are draggable (grab header to move). The rest of the app (wiki tab, menu,
etc.) remains fully interactive.
- **Workspace stopped** (the machine is not running): "Your Linux workspace has
stopped. Your files are safe; Start brings it back." Start calls
`POST /container-start`.
- **Editor not answering** (machine running, code-server not serving): a
Reconnect banner. Its button posts `/wake/simulate`, which does nothing on
Linux (see `hydrogen-wake-repair`); use Restart workspace instead.
- **Disk almost full**: the message names the drive and asks to free space on
that disk.
A missing runtime or a workspace not built yet shows no floaty: that is the
setup cascade's job (see `hydrogen-setup`). There is no runtime repair button on
Linux.
Separately, a watcher looks every 15 s for VS Code's "Cannot reconnect" dialog
and reloads only the editor pane when code-server is serving (see
`hydrogen-wake-repair`).
## Auto-Start via `setup_and_start`
The "Start Workspace" path calls Tauri `setup_and_start`, which delegates to
the active runtime's `setup_and_start`:
- If the workspace isn't present yet, `fresh_import` = download the golden
image + provision the workspace + start code-server.
- If the workspace is present but code-server is down, it just (re-)starts
code-server.
On Linux it first makes sure the host is ready (the helper and its sudoers rule, one
pkexec prompt only if missing).
code-server runs as `code-server.service` inside the machine, so it does not die with
Hydrogen, and Hydrogen re-ensures it on every launch. See `hydrogen-workspace-lifecycle`
for the full lifecycle detail.
## Lifecycle Dialog
`ContainerLifecycleDialog.svelte` — a draggable floating card (no background
blur) that shows live command output for start/stop/restart operations on the
workspace.
### Events
Listens for `hydrogen-container-lifecycle` CustomEvents on `window`:
- `action: 'restart' | 'stop' | 'start'` — opens dialog, starts spinner
- `action: 'step', step: string` — appends a log line
- `action: 'done'` — stops spinner, shows Close button, auto-reloads VS Code
- `action: 'stopped'` — stops spinner (for stop-only operations)
- `action: 'error', message: string` — shows error state
### Title
Dynamic based on `actionType`:
- Restarting: "Workspace Restarting..." → "Restart Complete"
- Stopping: "Stopping Workspace..." → "Workspace Stopped"
- Starting: "Starting Workspace..." → "Workspace Started"
- On error: "Restart/Stop/Start Failed"
### VS Code Auto-Reload
After the `done` event, the dialog polls `/workspace/health` every 5s for up to 2 minutes
and reloads the editor once `editor_will_load` is true. After an error it keeps checking
for 15 minutes and closes itself if the workspace answers again.
## Tauri Commands
| Command | What it does |
|---|---|
| `get_container_status` | Returns workspace status — runtime available, workspace present, Running + code-server reachable |
| `setup_and_start` | Host prep, `fresh_import` if no machine yet, boot, start code-server |
| `stop_container` | Stops the workspace |
On Linux `stop_container` powers off `Adom-Workspace` (helper, `machinectl poweroff`, then
terminate if it hangs).
## Menu Items (Adom Menu → Workspace Section)
- **Restart Container**: stop the machine, then re-ensure code-server; emits lifecycle
events, shows the dialog
- **Stop Container**: powers off the machine; emits lifecycle events, shows the dialog,
then the stopped floaty
- **Start**: from the stopped floaty
## Settings
- `hydrogen.launch_on_boot` (Launch on boot), default off. On Linux it writes
`~/.config/autostart/adom-hydrogen.desktop` (honoured by GNOME, KDE, Cinnamon).
## Related skills
- `hydrogen-workspace-lifecycle` — provision/export/remove/stop, the never-touch-global rule, control endpoints
- `hydrogen-container-stats` — the title-bar CPU/RAM bars and `workspace_stats()` probe
- `hydrogen-networking` — code-server port, control port