main
John Lauer Publish 0.1.0 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-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:

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 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).

  • [[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