main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-golden-image description: >- What the pre-baked golden workspace image contains on Linux (the rootfs Hydrogen unpacks into the Adom-Workspace systemd-nspawn machine), how package updates keep it current, the tarball pin, and where the Linux skill set comes from. Maintainer reference for where the CLIs and skills came from. disable-model-invocation: true

Hydrogen Workspace = a pre-baked golden image, kept current by packages

On Linux, Hydrogen unpacks the golden rootfs adom-golden.tar.gz (from Adom's public golden-image GitHub release, SHA256-verified, cached at ~/.local/share/Adom/HydrogenDesktop/cache/adom-golden.tar.gz) into /var/lib/machines/Adom-Workspace and boots it as a systemd-nspawn machine. It is the same image the other Hydrogen platforms run (currently v31-full); only the runtime around it differs. It is PRE-BAKED: the Adom toolchain is already inside the tarball.

A new image ships every week or so, each the previous one with the current adom-wiki pkg update baked in. From v27 on there is no forced re-image (NO_FORCED_MIGRATION_FROM = 27), so an existing workspace stays on its image and packages keep it current. A fresh install simply gets the newer image.

The pin is the truth, this page is a snapshot. The version actually shipped lives in three consts in runtime/wsl.rs (TARBALL_VERSION, TARBALL_URL_PLACEHOLDER, TARBALL_SHA256_PLACEHOLDER). If they disagree with this page, they win and this page is stale. An earlier era (v24-thin, 2026-08-13 to v26) shipped a MINIMAL image that installed everything live at setup; describing that as current tells a user their 695 MB image is empty.

What the tarball contains:

  • Ubuntu base + systemd (PID 1), the adom user, the folder contract (~/project is the workspace root)
  • code-server (the VS Code backend) + its systemd unit
  • systemd units for the relay and shotlog
  • the adom-wiki CLI at ~/.local/bin/adom-wiki
  • the Adom toolchain itself: adom/core, the Adom CLIs, the hydrogen-* skills, and the editor extensions (adom-theme, adom-vscode, anthropic.claude-code)
  • a first-boot oneshot that mints the per-import /etc/adom-distro-id

Version files inside the workspace: /etc/adom-golden-version (the rootfs you run), /etc/adom-tarball-version (what Hydrogen imported). The units are code-server.service, adom-relay.service and adom-shotlog.service; the adom user is UID 1001.

How updates work

  • adom/hook runs adom-wiki pkg update on agent activity; the Adom sidebar's Packages section runs it on demand. The image is not touched.
  • update-packages is not part of the normal setup cascade any more; the os-baseline step only fills small OS gaps.
  • The image itself changes only when Hydrogen ships a new pinned tarball, and an existing workspace gets it only through a Virgin Reset (re-import).

Where the Linux skills come from

The image has the generic adom/hydrogen-bootstrap skill set plus a desktop package that was written for another platform. On Linux, Hydrogen applies its own Linux skill set (the Linux render of skills/public-facing/shared/, embedded in the app, hydrogen-setup/src/linux_skills.rs) after every package convergence and at every launch: each Linux skill is written over the package copy of the same name, and that package's skills with no Linux version are removed (unless another installed package also delivers them). A later adom-wiki pkg update that re-delivers them is undone at the next apply.

"Command not found" / missing tools

The image intentionally ships no long-tail tooling. Get tools on demand: apt-get install <tool> (via sudo where available), apt python3-<lib> for Python libraries (PEP-668: prefer apt; pip --break-system-packages or a venv otherwise), and adom-wiki discover search -q <capability> for Adom packages.

Answering common user questions

  • "Where did all these skills come from?" Baked into the image, kept current by the package registry, with the Linux set applied by Hydrogen. They live flat in ~/.claude/skills/.
  • "How do I update the workspace?" → you almost never need to; the registry updater converges packages continuously. A tarball-version bump (rare, OS level) comes through ah and needs a re-import.