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-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-Workspacesudo machinectl start Adom-Workspacesudo 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:
GET /wsl/statusand/workspace/health(ormachinectl status Adom-Workspaceon the host).- Running but editor dead: Restart Container, or relaunch Hydrogen.
- Verify code-server answers on 127.0.0.1:7380.
- Last resort (destructive, the user's decision): back up
/home/adom/project, then Virgin Reset with "Workspace machine".
Related skills
- hydrogen-workspace-monitoring — the 15s poll, floaty states, lifecycle dialog, auto-start
- hydrogen-container-stats — title-bar CPU/RAM bars +
workspace_stats()probe hydrogen-volume: what a reset deletes and how to back up
---
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".
## Related skills
- [hydrogen-workspace-monitoring](../hydrogen-workspace-monitoring/SKILL.md) — the 15s poll, floaty states, lifecycle dialog, auto-start
- [hydrogen-container-stats](../hydrogen-container-stats/SKILL.md) — title-bar CPU/RAM bars + `workspace_stats()` probe
- `hydrogen-volume`: what a reset deletes and how to back up