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-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
(
~/projectis 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/hookrunsadom-wiki pkg updateon agent activity; the Adom sidebar's Packages section runs it on demand. The image is not touched.update-packagesis not part of the normal setup cascade any more; theos-baselinestep 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.
---
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.