main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-workspace-lifecycle description: >- Lifecycle of Hydrogen's Adom-Workspace systemd-nspawn machine on Linux: import, start, stop, restart, remove, the root helper, code-server as a systemd unit, and the rule to touch only Adom-Workspace. Read before any workspace operation. Use when the workspace is broken, unhealthy, or needs a restart.

Hydrogen: Linux Workspace Lifecycle

The workspace is Adom-Workspace, a systemd-nspawn machine on the host kernel, its rootfs at /var/lib/machines/Adom-Workspace, its settings in /etc/systemd/nspawn/Adom-Workspace.nspawn (written by Hydrogen; edits are overwritten). Hydrogen drives it through one root helper, /usr/libexec/adom-hydrogen/hydrogen-workspace, run as sudo -n (the .deb/.rpm installs a sudoers rule for it; an AppImage asks once through pkexec). The helper manages only Adom-Workspace and refuses any other name.

ABSOLUTE RULE: touch only Adom-Workspace

The user may run other containers (machinectl list, Docker, Podman, LXC). Never stop, remove or restart anything else, never systemctl restart systemd-machined, and never kill systemd-nspawn processes by name. Allowed, scoped (on the host):

  • sudo machinectl poweroff Adom-Workspace / terminate Adom-Workspace
  • sudo machinectl start Adom-Workspace
  • sudo machinectl export-tar Adom-Workspace <file>.tar (backup)
  • sudo machinectl remove Adom-Workspace (destructive wipe)

Prefer Hydrogen's own controls and API below; they also keep Hydrogen's state right.

Lifecycle

Import (fresh setup)

Setup step ensure-workspace: make the host ready (systemd-container package, the helper, its sudoers rule), download adom-golden.tar.gz (SHA256-verified, cached in ~/.local/share/Adom/HydrogenDesktop/cache/), and the helper unpacks it into /var/lib/machines/Adom-Workspace (numeric owners, xattrs; a btrfs subvolume on btrfs; restorecon on SELinux hosts).

Start

The helper boots the machine on the first command into it (machinectl start, waits until systemd inside is up). At every start it also installs the adom_hydrogen nft table (workspace ports closed to the LAN), sets the hostname to the host's, and re-applies the editor fixes.

code-server is a systemd unit in the machine

code-server.service (127.0.0.1:7380), adom-relay.service and adom-shotlog.service belong to the machine's systemd; Hydrogen attaches to them and does not hold its own copies, so a Hydrogen restart does not kill the editor. Readiness means code-server answers on 7380, not just "machine running".

Restart

Adom menu > Restart Container (or POST /container-restart): stop the machine, then setup_and_start again. VS Code disconnects for about 10 s. /tmp inside is emptied.

Stop

Adom menu > Stop Container, or POST /container-stop. Hydrogen latches "user stopped" so its own probes do not boot the machine again; Start clears it. Files persist.

Remove (DESTRUCTIVE)

Only through the Setup panel's Virgin Reset with "Workspace machine" checked (type to confirm): machinectl remove Adom-Workspace, which deletes /home/adom/project too. POST /wsl/unregister is refused on purpose (a headless wipe is not allowed).

Control API

Read the live URL: BASE="$(cat ~/.adom/hydrogen-control-url)" (same 127.0.0.1 inside and outside the workspace).

Endpoint What it does
GET /wsl/status registered? running? code-server reachable? (name kept for compatibility; answers for the nspawn machine)
GET /workspace/health the deep check: editor_will_load and which layer failed
GET /container-status state for the menu and badges
POST /container-restart, /container-stop, /container-start lifecycle; {"dry_run":true} says what would happen
GET /container-stats Live CPU/RAM/disk from the workspace_stats() probe (see hydrogen-container-stats)

Diagnosing Workspace Problems

  • Editor stuck or "restart needed" badge: GET /workspace/health. If code-server is dead, Restart Container.
  • VS Code "Cannot reconnect" dialog: Hydrogen notices it over a serving backend and reloads the editor pane itself (at most three times in a row, 45 s apart). If it stays, Restart Container.
  • Setup says the helper or systemd-container is missing: reinstall the Hydrogen package (.deb/.rpm) or approve the password prompt, then Retry.
  • Machine did not boot: on the host sudo machinectl terminate Adom-Workspace, then Retry in Setup. Logs: journalctl -u systemd-nspawn@Adom-Workspace.
  • Half-built import: sudo machinectl terminate Adom-Workspace; sudo machinectl remove Adom-Workspace, then Retry (this deletes the machine: only for a workspace that never finished setup).

Recovery Checklist

When the workspace is broken, follow this order:

  1. GET /wsl/status and /workspace/health (or machinectl status Adom-Workspace on the host).
  2. Running but editor dead: Restart Container, or relaunch Hydrogen.
  3. Verify code-server answers on 127.0.0.1:7380.
  4. Last resort (destructive, the user's decision): back up /home/adom/project, then Virgin Reset with "Workspace machine".