main
John Lauer Publish 0.1.0 d8a45ab

name: hydrogen-volume description: >- Where files live in Hydrogen's Linux workspace (the Adom-Workspace systemd-nspawn machine), what survives a restart versus a virgin reset, and how to reach them from the Linux desktop. Use when asked where are my files, did I lose my work, how do I copy a file out, or what happens to my code if I virgin reset.

Hydrogen Workspace Storage: what persists, what doesn't

Your work lives in the Adom-Workspace machine at /home/adom/project. There is no separate volume: the machine's whole rootfs is a plain directory tree on the host disk, and /home/adom/project is part of it.

The filesystem

Property Value
Your work path /home/adom/project
On the host /var/lib/machines/Adom-Workspace/home/adom/project (root-owned pool, mode 0700: read it with sudo or through /mnt/host, below)
Backing store a directory (a btrfs subvolume when /var/lib/machines is on btrfs); no disk image, so there is nothing to compact
Persistence survives machine restart, Hydrogen restart, and host reboot, until the machine is removed

What lives where

Path inside the workspace Notes
/home/adom/project/ Your code. Put everything important here.
~/.local/share/code-server/ Extensions and settings, baked into the image
~/.claude/ Skills (baked, kept current by packages) and Claude credentials
/tmp/ A tmpfs: emptied on every machine stop or restart.
/mnt/host/home, /mnt/host/tmp The host's /home and /tmp, read-write (live host files, not workspace files)
/mnt/host/usr, /mnt/host/opt The host's /usr and /opt, read-only
/etc/, /usr/, system Part of the workspace image; replaced on a re-import

Rule of thumb: if you want it to survive a workspace rebuild, put it under /home/adom/project/.

What survives each virgin-reset choice

When you open Virgin Reset (Hydrogen setup panel), the checkbox toggles control which artifacts get deleted:

Toggle ON means: Result
Install step state setup-steps-workspace.json deleted; next setup re-runs everything. Your project files unaffected.
Workspace machine Removes the Adom-Workspace machine (machinectl remove), including /home/adom/project/. The one destructive option.
Golden workspace image cache Deletes the cached adom-golden.tar.gz (in ~/.local/share/Adom/HydrogenDesktop/cache/) so setup downloads it again. Files unaffected.
Adom session token Re-login required next time. Project files unaffected.
Claude credentials Claude Code requires re-auth. Project files unaffected.

The reset only ever touches Adom-Workspace; other containers on the machine are never stopped or removed.

Getting files in and out

1. Through /mnt/host (simplest)

# Workspace file -> the user's Downloads on this desktop
cp /home/adom/project/myfile.txt /mnt/host/home/<user>/Downloads/

# Desktop file -> workspace
cp /mnt/host/home/<user>/Downloads/myfile.txt /home/adom/project/

<user> is the desktop login name (ls /mnt/host/home). Files you write there are owned by UID 1001 (adom); on the host that UID may belong to someone else or no one, so chmod a+r a file if the user cannot open it.

2. In the editor

The VS Code file tree shows /home/adom/project; drag files in, or right-click > Download.

3. Another of the user's machines

adom-bridge send_files / pull_file with --target <name> reach the user's other PCs through the Adom mesh (see hydrogen-file-transfer). The same verbs reach this computer while Adom Bridge runs here (Hydrogen installs it when a Linux build is published for the user's account).

Backing up

Copy the project out before anything destructive:

tar czf /mnt/host/home/<user>/adom-project-backup.tar.gz -C /home/adom project

Or on the host, a full-machine snapshot: sudo machinectl export-tar Adom-Workspace ~/adom-workspace.tar (stop the workspace first for a consistent copy).

  • hydrogen-container: the machine whose filesystem holds your work
  • hydrogen-workspace-lifecycle: stop, restart, remove
  • ~/.claude/skills/hydrogen-golden-image/SKILL.md — what's baked into adom-golden.tar.gz (extensions, settings, skills) vs. what setup does