---
name: hd-volume
description: How HD's machine workspace storage is laid out — what's persistent, what's ephemeral, where your work lives, what survives a workspace restart vs a virgin reset, and how to access your workspace files from your Mac host. Use when the user asks "where are my files", "did I lose my work", "how do I copy a file out of the workspace", or "what happens to my code if I virgin reset". Trigger words — machine filesystem, hd volume, where are my files, workspace files, persistent storage, lost my work, /home/adom/project, machine filesystem, machine export, copy file out of workspace, where is my code, workspace backup, machine remove.
---

# HD Workspace Storage — what persists, what doesn't

Machine-runtime version (default). Legacy Docker container runtime (`HD_RUNTIME=docker`) is in the docker/ bucket.

Your work lives on the `Adom-Workspace` machine's filesystem at `/home/adom/project` — a systemd-nspawn machine rootfs under the `hd-builder` Lima VM (e.g. `/var/lib/machines/Adom-Workspace`). There is **no Docker named volume** — `/home/adom/project` sits directly in the machine's own ext4 filesystem. ALL your work belongs under that path. It persists for as long as the machine stays registered.

## The filesystem

| Property | Value |
|----------|-------|
| Machine name | `Adom-Workspace` (fixed) |
| Your work path | `/home/adom/project` (plain directory in the machine's ext4 fs) |
| Backing store | The machine's rootfs directory inside the Lima VM (`hd-builder`), e.g. `/var/lib/machines/Adom-Workspace/` on the VM disk |
| On-disk location (Mac) | N/A on macOS — it lives inside the `hd-builder` Lima VM's disk image, not directly on the Mac. Reach it via the relay or `limactl shell hd-builder` + nsenter (see below) |
| Persistence | Survives workspace restart, HD restart, and Mac reboot. Persists as long as the machine stays **registered** (`machinectl`). |

There is **no named volume to delete separately** — the project files and the OS image are one and the same ext4 filesystem. The only thing that wipes `/home/adom/project` is removing the machine.

## What lives WHERE

| Path inside the machine | Persists across a tarball re-import? | Notes |
|------------------------|---------------------------------------|-------|
| `/home/adom/project/` | **Yes** — HD exports `/home/adom` before re-importing the golden image on a version bump, then restores it | This is your code. Put everything important here. |
| `~/.local/share/code-server/extensions/` | **Yes** within the machine — BAKED into the golden image, restored on tarball re-import | Not a setup step; baked at image-build time |
| `~/.local/share/code-server/User/settings.json` | **Yes** within the machine — BAKED into the golden image | Not a setup step; baked at image-build time |
| `~/.claude/` (skills, credentials) | Skills are BAKED into the golden image (restored on re-import); credentials are restored by the `claude-auth` setup step from a host-side backup | HD skills are baked FLAT into `~/.claude/skills/<name>/` |
| `/tmp/` | **No** | Ephemeral |
| `/etc/`, `/usr/`, system stuff | Lives in the same ext4 fs, but is overwritten on a tarball version bump | Treat as part of the workspace image |

**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 (HD setup panel), the checkbox toggles control which artifacts get deleted:

| Toggle ON means: | Result |
|------------------|--------|
| Install step state | `setup-steps-macos.json` deleted; next setup re-runs everything. Your project files unaffected. |
| Workspace machine | **`machinectl remove Adom-Workspace`. This wipes the ENTIRE machine including `/home/adom/project/`. This is the destructive option.** No reboot needed; the wipe is immediate. |
| Workspace image | Deletes the cached `adom-golden.tar.gz`, so setup re-downloads it on next run. Your machine (and your code, if still registered) is unaffected. |
| Adom session token | Re-login required next time. Project files unaffected. |
| Claude credentials | Claude Code requires re-auth. Project files unaffected. |

**The only toggle that destroys your work is "Workspace machine" (the `machinectl remove`).** All others are safe for your code. (Note: the "image" reset just deletes the cached `adom-golden.tar.gz` — NOT a 390MB Docker image like the legacy runtime.)

⚠️ The reset only ever targets `Adom-Workspace`. It NEVER touches the Lima VM itself or any other machine registered on the host.

## Accessing workspace files from the Mac

There is **no Finder share** into the machine (no macOS equivalent of the old `\\wsl$` Explorer share). Reach your files via the relay or by shelling into the Lima VM.

### 1. `limactl shell hd-builder` + nsenter + cp
```bash
# Drop into the Lima VM, enter the machine namespace as the adom user, and operate on files
limactl shell hd-builder -- sudo nsenter -t <leader> -a -S 1001 -G 1001 -- bash -lc \
  'ls -la /home/adom/project'
```
Use `limactl copy` to move files between the Mac and the VM disk, then `nsenter` + `cp` to land them in the machine's `/home/adom/project`.

### 2. From inside the machine, there is no `/mnt/c` drive mount
N/A on macOS — there are no Windows drive mounts. Use the relay instead (see below).

### 3. `adom-desktop send_files` / `pull_file` (from inside the workspace, via the relay)
```bash
# Send a workspace file to your Mac desktop's Downloads folder
adom-desktop send_files '{"filePaths":["/home/adom/project/myfile.txt"],"targetApp":"general","destinationFolder":"."}'

# Pull a Mac file into the workspace's /tmp
adom-desktop pull_file '{"filePaths":["/Users/john/Downloads/myfile.txt"],"saveTo":"/tmp"}'
```

### 4. Open the workspace's `/home/adom/project/` in VS Code's File Explorer
Just use the built-in code-server tree — the project folder is what's open, so anything you create/edit there hits the machine fs directly.

## Backing up your workspace

Persistence and backup for the machine is `machinectl export-tar` / `machinectl import-tar` (run inside the `hd-builder` Lima VM) — NOT a Docker volume tar. Before a destructive operation (the workspace-machine virgin-reset / `machinectl remove`):

```bash
# Export the whole machine to a tarball inside the Lima VM
limactl shell hd-builder -- sudo machinectl export-tar Adom-Workspace /tmp/adom-workspace-backup.tar
# (then limactl copy /tmp/adom-workspace-backup.tar back to the Mac if you want it off-VM)

# Restore it later (re-register the machine from the backup)
limactl shell hd-builder -- sudo machinectl import-tar /tmp/adom-workspace-backup.tar Adom-Workspace
```

This is exactly the mechanism HD's own tarball-migration uses: on a tarball version bump it `machinectl export-tar`s `/home/adom` first, then re-imports the new base and restores your work.

Or, for just a few files, copy them out first via the relay or `limactl shell hd-builder` + nsenter + cp.

## Why a machine filesystem (no named volume, no bind mount)?

HD keeps your work directly inside the `Adom-Workspace` ext4 filesystem rather than a Docker named volume or a bind mount of a Mac path. This:
- Gives native Linux ext4 I/O — much faster than crossing the macOS ↔ VM filesystem boundary
- Avoids line-ending and permission issues that bind mounts of host paths often have
- Lets HD wipe + re-import the base image (on a tarball bump) without losing your code — it `machinectl export-tar`s `/home/adom` first

There is no Finder share into the machine on macOS — use the relay (`adom-desktop send_files`/`pull_file`) or `limactl shell hd-builder` + nsenter + cp to move files in and out.

## Related skills

- `hd-container` — the `Adom-Workspace` machine whose filesystem holds your work
- `hd-topology` — the three-tier topology; tier 3 is this Adom-Workspace machine
- `hd-golden-image` — what's baked into `adom-golden.tar.gz` (extensions, settings, skills) vs. what setup does