main
John Lauer Publish 0.1.0 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:

  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:

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).

  • 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).
  • 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