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-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).
Related skills
hydrogen-container: the machine whose filesystem holds your workhydrogen-workspace-lifecycle: stop, restart, remove~/.claude/skills/hydrogen-golden-image/SKILL.md— what's baked intoadom-golden.tar.gz(extensions, settings, skills) vs. what setup does
---
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)
```bash
# 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:
```bash
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).
## Related skills
- `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