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-container description: >- Facts about the Hydrogen workspace Claude runs in on Linux: the Adom-Workspace systemd-nspawn machine, Ubuntu 24.04, code-server, the golden image, setup steps instead of bootstrap.sh, bridges and the relay. Use when asked what environment am I in, on adom-cli errors, code-server or extension issues, or bridge and relay questions.
Hydrogen Workspace
You are running inside Adom-Workspace, a systemd-nspawn machine that Hydrogen (ah) runs on the user's Linux desktop. It is a container on the host's own kernel, not a VM. Hydrogen manages it, provides VS Code + Claude Code, and talks to it over the shared loopback.
The workspace — exact facts (don't guess)
| Field | Value |
|---|---|
| Machine name | Adom-Workspace (fixed; machinectl list on the host shows it) |
| Made from | the golden rootfs adom-golden.tar.gz (currently v31-full), unpacked by Hydrogen's root helper into /var/lib/machines/Adom-Workspace on the host |
| Base | Ubuntu 24.04 |
| Init and kernel | systemd as PID 1, on the host's kernel (uname -r shows the host kernel; systemd-detect-virt says systemd-nspawn) |
| Hostname | the host's own name (the helper writes it into the machine at start) |
| code-server | systemd unit code-server.service, --bind-addr 127.0.0.1:7380 --auth none, binary /usr/bin/code-server |
| Extensions dir | ~/.local/share/code-server/extensions/ |
| Settings | ~/.local/share/code-server/User/settings.json |
| Work user | adom (UID 1001, passwordless sudo, home /home/adom); uids are not remapped |
| Workspace | /home/adom/project |
| Host paths | /mnt/host/home (host /home, read-write), /mnt/host/tmp (host /tmp), /mnt/host/usr and /mnt/host/opt (read-only). The workspace itself is a plain directory in the machine's rootfs on the host disk. |
/tmp |
a tmpfs inside the machine (25% of RAM), empty after every machine restart |
| Pre-installed | Node + npm, Python 3.12 with requests, yaml, bs4, lxml, pillow, git, gh, curl, wget, jq, unzip, zip. No C/C++ toolchain. |
| Host side | /usr/libexec/adom-hydrogen/hydrogen-workspace, the root helper Hydrogen runs through sudo -n for start, stop, exec, import and remove |
Confirm with cat /etc/os-release, systemd-detect-virt, code-server --version.
Installing packages (you have passwordless sudo)
Python: Ubuntu 24.04 is PEP-668 "externally-managed", so pip install <x> fails. Prefer sudo apt-get install -y python3-<lib>; otherwise pip install --break-system-packages <lib>, a venv, or pipx. Node: npm i -g <pkg>. System: sudo apt-get install -y <pkg> (add build-essential first if something must compile).
Setup is via Hydrogen's setup-steps, NOT a bootstrap script
Hydrogen provisions the machine through its setup cascade (the hydrogen-setup crate; Linux host prep in hydrogen-runtime/src/runtime/linux.rs). The first step, ensure-workspace, makes the host ready (systemd-container, the helper, its sudoers rule, at most one password prompt), then imports the golden image if the machine does not exist yet. Most tooling is baked into the image, not installed by a step. See hydrogen-setup-steps. Hydrogen never runs bootstrap.sh.
VS Code extension caveats
- The Claude Code extension and
code-serversettings (includingextensions.autoUpdate: true/extensions.autoCheckUpdates: true) are BAKED into the golden image — there is nowrite-vscode-settingsorinstall-claude-extsetup step. Auto-update must stay on so every installed extension auto-updates from the marketplace; the image bakes it on. Do not regress this. - Bare
code-server --install-extension <id>(no version pin) historically resolves to the universal target-platform build. For some extensions (notablyanthropic.claude-codeafter 2.1.89), Anthropic stopped shipping universal builds — so bare install permanently sticks at 2.1.89 even when newer per-arch builds exist. The golden-image bake installs the latest per-arch build pinned, so the workspace ships current. It also heals orphanextensions.jsonentries (entries pointing to deleted dirs cause a permanent "Invalid extensions detected" banner). - The marketplace is Open VSX, through Hydrogen's
/galleryendpoint (EXTENSIONS_GALLERYin code-server's unit environment).
adom-cli is authenticated
Hydrogen auto-injects the user's session token on every launch. To verify:
adom-cli carbon user get
If this returns user data, all adom-cli commands work (containers, repos, orgs, wiki, etc.). If it fails, the user needs to log in via Hydrogen's login page.
Relay server is running
The adom-bridge relay runs in the workspace (adom-relay.service, 8765 WebSocket / 8766 HTTP).
Check health: curl -sf http://127.0.0.1:8766/health
Check desktop connection: adom-bridge ping
The machine shares the host's network namespace, so 127.0.0.1 is the same on both sides.
The host control API is reachable from inside the workspace at 127.0.0.1. The port is dynamic per launch, so read the live URL from ~/.adom/hydrogen-control-url (http://127.0.0.1:<dynamic>): BASE="$(cat ~/.adom/hydrogen-control-url)"; curl "$BASE/health".
Bridges
Hydrogen installs and starts Adom Bridge (ab) on this Linux desktop when a Linux build is published for the user's account. The verbs below work while it runs here (GET /ab/health tells you), or when you address another of the user's machines (for example their Windows PC) through the Adom mesh with adom-bridge --target <name>. Fusion 360 and the window-handle verbs need a Windows machine. Check with adom-bridge ping and adom-bridge targets; see hydrogen-bridges. Host files for a local bridge are plain Linux paths (/home/<user>/...).
Screenshots (zero dialogs, instant)
adom-bridge desktop_screenshot_screen # full screen capture
adom-bridge desktop_screenshot_screen '{"maxWidth":1500}' # resized for Claude vision
adom-bridge desktop_screenshot_window '{"hwnd": N}' # capture specific window
adom-bridge desktop_list_windows # list all windows with handles
Default to maxWidth: 1500, format: "png" for UI screenshots. Use "jpeg" for natural photos, "webp" for smaller files.
Browser automation (Puppeteer)
adom-bridge pup_open_window '{"url": "https://..."}'
adom-bridge pup_screenshot '{"sessionId": "default"}'
adom-bridge pup_eval '{"js": "document.title"}'
adom-bridge pup_navigate '{"url": "..."}'
KiCad bridge
adom-bridge kicad_open_board '{"path": "/path/to/board.kicad_pcb"}'
adom-bridge kicad_screenshot_all
adom-bridge kicad_run_drc '{"path": "..."}'
adom-bridge kicad_window_info
(Paths to host files use the host's native path convention.)
Fusion 360 bridge
adom-bridge fusion_start
adom-bridge fusion_import_step '{"path": "..."}'
adom-bridge fusion_export_step '{"path": "..."}'
File transfer
adom-bridge send_files '{"files": [{"path": "/home/adom/file.txt"}]}'
adom-bridge pull_file '{"remotePath": "<host path>", "localPath": "/tmp/file.txt"}'
Desktop interaction
adom-bridge notify_user '{"message": "Build complete", "duration_ms": 3000}'
adom-bridge desktop_open_url '{"url": "https://..."}'
adom-bridge desktop_open_folder '{"path": "<host folder path>"}'
What's different from Adom cloud containers
| Feature | Adom Cloud | Hydrogen local (Linux) |
|---|---|---|
| Workspace provisioning | Adom platform API | golden rootfs unpacked into a systemd-nspawn machine on the user's PC |
| Relay connection | wss:// through Cloudflare | ws://localhost:8765 (direct, no TLS) |
| Bridge latency | ~50-100ms (internet round-trip) | <1ms (localhost) |
| VSCODE_PROXY_URI | forwarded-port URL template | http://{{port}}.localhost:<proxy port>/ (Hydrogen's reverse proxy); since the network is shared, http://localhost:<port>/ also works directly |
| Socket.IO (collab) | Connected to iron.adom.inc | Disabled (single-user) |
| Service containers | Adjacent containers | Remote via Adom cloud |
Environment variables
ADOM_DESKTOP_MODE=local— indicates Hydrogen local modeVSCODE_PROXY_URI=http://{{port}}.localhost:<proxy port>/(Hydrogen 1.0.224+): the URL template for a forwarded port, served by Hydrogen's own reverse proxy with the app's paths untouched, so web apps that load assets by absolute path (Google Antigravity's side bar) work. The path formhttp://localhost:7380/proxy/<port>/still works when typed by hand. Before 1.0.224 the template was that path form. Code-server's proxyADOM_HD_CONTROL_URL,ADOM_CARBON_URL,ADOM_HYDROGEN_URL,VSCODE_PROXY_URI: written to~/.bashrcand code-server's unit, so AI shells inherit them.Commands Hydrogen runs through its helper also carry
HYDROGEN_HOST=linuxandWSL_DISTRO_NAME=Adom-Workspace(a compatibility name, not a sign of any other runtime).
Related skills
[[hydrogen-container-stats]]— the title-bar CPU/RAM indicator for this workspace[[hydrogen-setup-steps]]— what each setup step did to prepare your workspace[[hydrogen-topology]]: the layers and where commands run[[hydrogen-volume]]: where your files live and how to copy them out[[hydrogen-workspace-lifecycle]]: start, stop, restart, reset
---
name: hydrogen-container
description: >-
Facts about the Hydrogen workspace Claude runs in on Linux: the Adom-Workspace
systemd-nspawn machine, Ubuntu 24.04, code-server, the golden image, setup
steps instead of bootstrap.sh, bridges and the relay. Use when asked what
environment am I in, on adom-cli errors, code-server or extension issues, or
bridge and relay questions.
---
# Hydrogen Workspace
You are running inside **`Adom-Workspace`, a systemd-nspawn machine** that Hydrogen (ah) runs on the user's Linux desktop. It is a container on the host's own kernel, not a VM. Hydrogen manages it, provides VS Code + Claude Code, and talks to it over the shared loopback.
## The workspace — exact facts (don't guess)
| Field | Value |
|-------|-------|
| Machine name | `Adom-Workspace` (fixed; `machinectl list` on the host shows it) |
| Made from | the golden rootfs `adom-golden.tar.gz` (currently `v31-full`), unpacked by Hydrogen's root helper into `/var/lib/machines/Adom-Workspace` on the host |
| Base | Ubuntu 24.04 |
| Init and kernel | systemd as PID 1, on the host's kernel (`uname -r` shows the host kernel; `systemd-detect-virt` says `systemd-nspawn`) |
| Hostname | the host's own name (the helper writes it into the machine at start) |
| code-server | systemd unit `code-server.service`, `--bind-addr 127.0.0.1:7380 --auth none`, binary `/usr/bin/code-server` |
| Extensions dir | `~/.local/share/code-server/extensions/` |
| Settings | `~/.local/share/code-server/User/settings.json` |
| Work user | `adom` (UID 1001, passwordless sudo, home `/home/adom`); uids are not remapped |
| Workspace | `/home/adom/project` |
| Host paths | `/mnt/host/home` (host `/home`, read-write), `/mnt/host/tmp` (host `/tmp`), `/mnt/host/usr` and `/mnt/host/opt` (read-only). The workspace itself is a plain directory in the machine's rootfs on the host disk. |
| `/tmp` | a tmpfs inside the machine (25% of RAM), empty after every machine restart |
| Pre-installed | Node + npm, Python 3.12 with `requests`, `yaml`, `bs4`, `lxml`, `pillow`, git, gh, curl, wget, jq, unzip, zip. **No C/C++ toolchain.** |
| Host side | `/usr/libexec/adom-hydrogen/hydrogen-workspace`, the root helper Hydrogen runs through `sudo -n` for start, stop, exec, import and remove |
Confirm with `cat /etc/os-release`, `systemd-detect-virt`, `code-server --version`.
## Installing packages (you have passwordless sudo)
**Python: Ubuntu 24.04 is PEP-668 "externally-managed"**, so `pip install <x>` fails. Prefer `sudo apt-get install -y python3-<lib>`; otherwise `pip install --break-system-packages <lib>`, a venv, or `pipx`. **Node:** `npm i -g <pkg>`. **System:** `sudo apt-get install -y <pkg>` (add `build-essential` first if something must compile).
## Setup is via Hydrogen's setup-steps, NOT a bootstrap script
Hydrogen provisions the machine through its setup cascade (the `hydrogen-setup` crate; Linux host prep in `hydrogen-runtime/src/runtime/linux.rs`). The first step, `ensure-workspace`, makes the host ready (systemd-container, the helper, its sudoers rule, at most one password prompt), then imports the golden image if the machine does not exist yet. Most tooling is baked into the image, not installed by a step. See `hydrogen-setup-steps`. Hydrogen never runs `bootstrap.sh`.
## VS Code extension caveats
- The Claude Code extension and `code-server` settings (including `extensions.autoUpdate: true` / `extensions.autoCheckUpdates: true`) are BAKED into the golden image — there is no `write-vscode-settings` or `install-claude-ext` setup step. Auto-update **must** stay on so every installed extension auto-updates from the marketplace; the image bakes it on. Do not regress this.
- Bare `code-server --install-extension <id>` (no version pin) historically resolves to the **universal** target-platform build. For some extensions (notably `anthropic.claude-code` after 2.1.89), Anthropic stopped shipping universal builds — so bare install permanently sticks at 2.1.89 even when newer per-arch builds exist. The golden-image bake installs the latest per-arch build pinned, so the workspace ships current. It also heals orphan `extensions.json` entries (entries pointing to deleted dirs cause a permanent "Invalid extensions detected" banner).
- The marketplace is Open VSX, through Hydrogen's `/gallery` endpoint (`EXTENSIONS_GALLERY` in code-server's unit environment).
## adom-cli is authenticated
Hydrogen auto-injects the user's session token on every launch. To verify:
```bash
adom-cli carbon user get
```
If this returns user data, all adom-cli commands work (containers, repos, orgs, wiki, etc.). If it fails, the user needs to log in via Hydrogen's login page.
## Relay server is running
The adom-bridge relay runs in the workspace (`adom-relay.service`, 8765 WebSocket / 8766 HTTP).
Check health: `curl -sf http://127.0.0.1:8766/health`
Check desktop connection: `adom-bridge ping`
The machine shares the host's network namespace, so `127.0.0.1` is the same on both sides.
The host control API is reachable from inside the workspace at `127.0.0.1`. The port is dynamic per launch, so read the live URL from `~/.adom/hydrogen-control-url` (`http://127.0.0.1:<dynamic>`): `BASE="$(cat ~/.adom/hydrogen-control-url)"; curl "$BASE/health"`.
## Bridges
Hydrogen installs and starts Adom Bridge (ab) on this Linux desktop when a Linux build is published for the user's account. The verbs below work while it runs here (`GET /ab/health` tells you), or when you address another of the user's machines (for example their Windows PC) through the Adom mesh with `adom-bridge --target <name>`. Fusion 360 and the window-handle verbs need a Windows machine. Check with `adom-bridge ping` and `adom-bridge targets`; see `hydrogen-bridges`. Host files for a local bridge are plain Linux paths (`/home/<user>/...`).
### Screenshots (zero dialogs, instant)
```bash
adom-bridge desktop_screenshot_screen # full screen capture
adom-bridge desktop_screenshot_screen '{"maxWidth":1500}' # resized for Claude vision
adom-bridge desktop_screenshot_window '{"hwnd": N}' # capture specific window
adom-bridge desktop_list_windows # list all windows with handles
```
Default to `maxWidth: 1500, format: "png"` for UI screenshots. Use `"jpeg"` for natural photos, `"webp"` for smaller files.
### Browser automation (Puppeteer)
```bash
adom-bridge pup_open_window '{"url": "https://..."}'
adom-bridge pup_screenshot '{"sessionId": "default"}'
adom-bridge pup_eval '{"js": "document.title"}'
adom-bridge pup_navigate '{"url": "..."}'
```
### KiCad bridge
```bash
adom-bridge kicad_open_board '{"path": "/path/to/board.kicad_pcb"}'
adom-bridge kicad_screenshot_all
adom-bridge kicad_run_drc '{"path": "..."}'
adom-bridge kicad_window_info
```
(Paths to host files use the host's native path convention.)
### Fusion 360 bridge
```bash
adom-bridge fusion_start
adom-bridge fusion_import_step '{"path": "..."}'
adom-bridge fusion_export_step '{"path": "..."}'
```
### File transfer
```bash
adom-bridge send_files '{"files": [{"path": "/home/adom/file.txt"}]}'
adom-bridge pull_file '{"remotePath": "<host path>", "localPath": "/tmp/file.txt"}'
```
### Desktop interaction
```bash
adom-bridge notify_user '{"message": "Build complete", "duration_ms": 3000}'
adom-bridge desktop_open_url '{"url": "https://..."}'
adom-bridge desktop_open_folder '{"path": "<host folder path>"}'
```
## What's different from Adom cloud containers
| Feature | Adom Cloud | Hydrogen local (Linux) |
|---------|-----------|-----------------|
| Workspace provisioning | Adom platform API | golden rootfs unpacked into a systemd-nspawn machine on the user's PC |
| Relay connection | wss:// through Cloudflare | ws://localhost:8765 (direct, no TLS) |
| Bridge latency | ~50-100ms (internet round-trip) | <1ms (localhost) |
| VSCODE_PROXY_URI | forwarded-port URL template | `http://{{port}}.localhost:<proxy port>/` (Hydrogen's reverse proxy); since the network is shared, `http://localhost:<port>/` also works directly |
| Socket.IO (collab) | Connected to iron.adom.inc | Disabled (single-user) |
| Service containers | Adjacent containers | Remote via Adom cloud |
## Environment variables
- `ADOM_DESKTOP_MODE=local` — indicates Hydrogen local mode
- `VSCODE_PROXY_URI=http://{{port}}.localhost:<proxy port>/` (Hydrogen 1.0.224+): the URL template for a forwarded port, served by Hydrogen's own reverse proxy with the app's paths untouched, so web apps that load assets by absolute path (Google Antigravity's side bar) work. The path form `http://localhost:7380/proxy/<port>/` still works when typed by hand. Before 1.0.224 the template was that path form. Code-server's proxy
- `ADOM_HD_CONTROL_URL`, `ADOM_CARBON_URL`, `ADOM_HYDROGEN_URL`, `VSCODE_PROXY_URI`: written to `~/.bashrc` and code-server's unit, so AI shells inherit them.
- Commands Hydrogen runs through its helper also carry `HYDROGEN_HOST=linux` and `WSL_DISTRO_NAME=Adom-Workspace` (a compatibility name, not a sign of any other runtime).
## Related skills
- `[[hydrogen-container-stats]]` — the title-bar CPU/RAM indicator for this workspace
- `[[hydrogen-setup-steps]]` — what each setup step did to prepare your workspace
- `[[hydrogen-topology]]`: the layers and where commands run
- `[[hydrogen-volume]]`: where your files live and how to copy them out
- `[[hydrogen-workspace-lifecycle]]`: start, stop, restart, reset