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-adom-auth description: >- Adom sign-in inside Hydrogen on Linux: the login/logout auth intent flow, where the session token lives (~/.config/hydrogen-desktop/hydrogen-session.txt), and how the session feeds setup. Use when Adom login fails, the session token expired, the user wants to sign in or out of Adom, or clear the Adom session.
Hydrogen -- Authentication Reference
Auth Flow Overview
Hydrogen uses an auth intent flow (no email/password entry in the app). The backend creates a short-lived intent token on the Carbon API, opens the user's default browser to the Adom login page, and polls until the user completes sign-in in the browser.
Sequence
- Hydrogen calls
invoke('auth_intent_start')-> backend POSTs tohttps://carbon.adom.inc/auth/intentswith{"max_age": 7776000}(90-day session). - Carbon returns
{token, confirmation_code, expires_at, auth_url}. - Hydrogen opens the browser to the
auth_urlCarbon returned, falling back tohttps://hydrogen.adom.inc/auth/intent?token={token}(singularintent, token as a query param — NOT/auth/intents/{token}). On Linux the browser opens through Hydrogen's browser launcher, which honours the Browser Picker's choice of browser and profile. - Hydrogen displays the confirmation code on screen and shows a spinner.
- Frontend polls
invoke('auth_intent_poll', {token})every 2 seconds. Backend GETshttps://carbon.adom.inc/auth/intents/{token}/status. - When the user confirms in the browser, the response includes
{state: "authenticated", session_token: "..."}. - The backend saves the session token to Hydrogen's app-data directory on the host
(the
hydrogen-session.txtfile) and a replay copy alongside it. - Frontend redirects to the dashboard.
Source files
- Login page:
src/routes/auth/login/+page.svelte - Auth backend:
src-tauri/crates/hydrogen-setup/src/app_glue.rs(auth_intent_start,auth_intent_poll) andsrc-tauri/crates/hydrogen-app/src/lib.rs(auth_proxy,check_replay_credentials,replay_adom_login). - Auth components:
src/lib/components/auth/(Header, Form, Footer, SubmitButton, Error, Success) - User API:
src/lib/api/authenticated_user.ts
Session Token
Location: Hydrogen's app-data directory on the host (the hydrogen-session.txt
file).
On Linux every auth file is in Hydrogen's state folder ~/.config/hydrogen-desktop/ on
the host (not in the workspace):
| File | Purpose |
|---|---|
hydrogen-session.txt |
The Adom session token. Read by the auth proxy; deleted on logout or a 401. |
replay-session.txt |
Replay copy; lets the login page sign you back in without a browser ("Signing you in... Ns"). |
replay-claude-credentials.json |
Claude Code credentials kept across a virgin reset (see hydrogen-claude-auth). |
From the workspace, the host's home is visible at /mnt/host/home/<user>/, but the
supported way to get the token is the control API below.
A plain-text file containing the Adom session cookie value. Created by either:
- The auth intent flow (on successful poll)
- The auth proxy (when Carbon returns a
set-cookie: session_token=...header)
The auth proxy (invoke('auth_proxy', ...)) reads this file and attaches it
as a Cookie: session_token=... header on every request to carbon.adom.inc.
Token lifecycle
- Created: on login (auth intent or browser set-cookie capture)
- Refreshed: automatically when the auth proxy receives a new set-cookie
- Cleared: on logout (
auth_proxy({path: "/auth/clear-local"})) or on 401 response (backend auto-deletes the file) - Max age: 90 days (set at intent creation)
Reading the token programmatically
BASE="$(cat ~/.adom/hydrogen-control-url)" # normally http://127.0.0.1:47084
curl -s "$BASE/auth-token" # the saved Adom session token
cat /var/run/adom/api-key # the same account's key, written into the workspace
Hydrogen writes /var/run/adom/api-key (mode 644) at every launch and once during setup's
activate-editor step, after sign-in. adom-cli, adom-wiki and the editor use it.
Auth Proxy
The backend command auth_proxy is the gateway for all authenticated requests
to the Adom Carbon API. It:
- Reads the session token from disk
- Attaches it as a cookie to the outgoing request
- Captures any
set-cookieresponse and updates the saved token - On 401, deletes the token and returns
{expired: true} - Supports a special
path: "/auth/clear-local"to delete the token file
Base URL: https://carbon.adom.inc
// Example: get the current user
const result = await invoke('auth_proxy', {
path: '/api/me',
method: 'GET'
});
// result = { status: 200, data: { id: "...", name: "jlauer12", ... }, ok: true }
Credential Replay
On login page mount, Hydrogen checks for saved credentials before starting the full auth intent flow:
invoke('check_replay_credentials')checks if replay files exist on disk.- If the replay-session file exists (has_adom = true), the login page shows "Signing you in... Ns" and counts down.
invoke('replay_adom_login')attempts to authenticate using the saved session token.- If replay succeeds, the user is logged in without opening a browser.
- If replay fails, Hydrogen falls back to the normal auth intent flow.
This makes re-login after a virgin reset instant when the user chose to preserve the Adom session token.
Claude Credentials
Location: Hydrogen's app-data directory on the host (the
replay-claude-credentials.json file).
Stores Claude Code credentials so they survive a virgin reset (see hydrogen-claude-auth).
Virgin reset options for auth
The virgin reset panel (Setup Panel -> Virgin Reset) has per-item toggles:
| Toggle | File | What it clears |
|---|---|---|
| Adom session token | hydrogen-session.txt |
Adom login. Next launch requires re-auth. |
| Claude credentials | replay-claude-credentials.json |
Claude Code OAuth. Next bootstrap re-authenticates Claude. |
These are independent -- you can wipe Claude creds without losing Adom login, or vice versa.
CSS selectors for virgin reset auth options
label.virgin-opt -- each checkbox row
input[type="checkbox"] -- the toggle (bind:checked to virginOpts.adom_token / virginOpts.claude_token)
.virgin-hint -- shows filename (hydrogen-session.txt / replay-claude-credentials.json)
.vp-badge -- status badge ("exists" / "clean")
.vp-exists -- green badge (file exists)
.vp-clean -- gray badge (file gone)
Profile Menu
Location: Top-right corner of the editor nav bar.
Source: src/lib/components/editor/EditorNav.svelte (lines ~2403-2443)
Click the circular user avatar to open a dropdown with two sections.
Menu items
| Item | Icon | Action |
|---|---|---|
| Your profile | mdi:account-circle-outline |
Navigates to /users/{username} |
| Your repositories | mdi:folder-outline |
Navigates to /users/{username}/repositories |
| Your molecules | mdi:atom |
Navigates to /users/{username}/molecules |
| Log out | mdi:logout |
Confirms, then clears session + redirects to login |
CRITICAL: Logout is ONLY in the profile menu (top-right avatar), NOT in the Adom menu (top-left logo). Do not look for logout in the wrong menu.
CSS selectors
| Element | Selector |
|---|---|
| Profile dropdown container | .profile-dropdown-container |
| Avatar button | .profile-dropdown-button |
| Avatar image | .profile-dropdown-button img |
| Dropdown (open) | .profile-dropdown-content.open |
| Menu items | .profile-dropdown-content .dropdown-link |
| Menu item icons | .dropdown-link span |
Eval examples (/eval-in {target:"shell"})
// Open the profile menu
document.querySelector('.profile-dropdown-button')?.click();
// Click "Your profile"
var links = document.querySelectorAll('.profile-dropdown-content .dropdown-link');
if (links[0]) links[0].click();
// Click "Your repositories"
if (links[1]) links[1].click();
// Click "Your molecules"
if (links[2]) links[2].click();
// Click "Log out"
var logoutBtn = Array.from(document.querySelectorAll('.profile-dropdown-content .dropdown-link'))
.find(function(e) { return e.textContent.includes('Log out'); });
if (logoutBtn) logoutBtn.click();
// Note: this triggers a confirm dialog. To auto-confirm, you need to handle the dialog.
// Read the current user's avatar URL
var avatar = document.querySelector('.profile-dropdown-button img');
avatar ? avatar.src : 'no avatar';
// Read the current username from the avatar alt text
avatar ? avatar.alt : 'unknown';
Logout Flow
- User clicks "Log out" in profile menu.
showConfirm('Are you sure you want to log out?', 'Log Out')-- confirmation dialog.- If confirmed (app mode):
invoke('auth_proxy', {path: '/auth/logout', method: 'DELETE'})-- server-side logoutinvoke('auth_proxy', {path: '/auth/clear-local', method: 'POST'})-- deleteshydrogen-session.txt- Clears auth-related domain preferences from
localStorage['hydrogen-url-routing-prefs']
- Redirects to
/auth/login.
Login Page UI
Route: /auth/login
App mode (auth intent)
- Adom logo + "Log in to Hydrogen" header
- Confirmation code in a monospace box (
.confirmation-code) - Spinner + "Waiting for you to sign in..."
- "Open browser again" button (
.retry-button)
Browser mode (email/password)
- Standard form with email + password fields
- "Log In" submit button
- Footer with registration link
Auth intent CSS selectors
| Element | Selector |
|---|---|
| Container | .intent-container |
| Confirmation code | .confirmation-code |
| Spinner | .spinner |
| Status message | .intent-message |
| Hint text | .intent-hint |
| Success message | .intent-success |
| Error message | .intent-error |
| Retry button | .retry-button |
Eval on the login page (/eval-in {target:"shell"})
// Check auth intent state
document.querySelector('.intent-message')?.textContent;
// -> "Waiting for you to sign in..." or "Authenticated! Redirecting..."
// Read the confirmation code
document.querySelector('.confirmation-code')?.textContent;
// Click retry
document.querySelector('.retry-button')?.click();
How Auth Affects Setup Steps
The setup/bootstrap process depends on a valid session token:
The activate-editor step waits for the Adom sign-in (the editor mounts only after login),
then binds the workspace to this launch: environment, the api-key write-through and the
relay. If the token is missing or expired, adom-cli in the workspace cannot authenticate:
sign in again, then run setup again from the Adom menu > Setup Steps.
Control API Auth Endpoints
| Method | Path | Description |
|---|---|---|
| GET | /auth-token |
Read the saved Adom session token (same-origin callers only) |
| POST | /claude-auth |
Start Claude Code OAuth (PKCE) |
| GET | /oauth/callback |
Receives OAuth redirect (auto, do not call) |
| POST | /start-oauth-proxy |
Spin up temp TCP listener for OAuth callback |
| POST/GET | /auth/proxy |
Proxy request to Carbon API with session token |
See the hydrogen-settings skill (API Explorer section) for the full endpoint reference.
Cross-references
- hydrogen-claude-auth -- Claude Code sign-in, separate from Adom
- hydrogen-profile-menu -- where login/logout live in the UI
- hydrogen-settings -- API Explorer (auth endpoints tab)
- hydrogen-networking -- how to reach the control API port
- hydrogen-api -- the control API
- hydrogen-key-values -- the account's cloud key-value store
---
name: hydrogen-adom-auth
description: >-
Adom sign-in inside Hydrogen on Linux: the login/logout auth intent flow, where the
session token lives (~/.config/hydrogen-desktop/hydrogen-session.txt), and how the
session feeds setup. Use when Adom login fails, the session token expired, the user
wants to sign in or out of Adom, or clear the Adom session.
---
# Hydrogen -- Authentication Reference
## Auth Flow Overview
Hydrogen uses an **auth intent** flow (no email/password entry in the app).
The backend creates a short-lived intent token on the Carbon API,
opens the user's default browser to the Adom login page, and polls until
the user completes sign-in in the browser.
### Sequence
1. Hydrogen calls `invoke('auth_intent_start')` -> backend POSTs to
`https://carbon.adom.inc/auth/intents` with `{"max_age": 7776000}`
(90-day session).
2. Carbon returns `{token, confirmation_code, expires_at, auth_url}`.
3. Hydrogen opens the browser to the **`auth_url` Carbon returned**, falling back to
`https://hydrogen.adom.inc/auth/intent?token={token}` (singular `intent`,
token as a query param — NOT `/auth/intents/{token}`).
On Linux the browser opens through Hydrogen's browser launcher, which honours the
Browser Picker's choice of browser and profile.
4. Hydrogen displays the confirmation code on screen and shows a spinner.
5. Frontend polls `invoke('auth_intent_poll', {token})` every 2 seconds.
Backend GETs `https://carbon.adom.inc/auth/intents/{token}/status`.
6. When the user confirms in the browser, the response includes
`{state: "authenticated", session_token: "..."}`.
7. The backend saves the session token to Hydrogen's app-data directory on the host
(the `hydrogen-session.txt` file) and a replay copy alongside it.
8. Frontend redirects to the dashboard.
### Source files
- **Login page**: `src/routes/auth/login/+page.svelte`
- **Auth backend**: `src-tauri/crates/hydrogen-setup/src/app_glue.rs`
(`auth_intent_start`, `auth_intent_poll`) and
`src-tauri/crates/hydrogen-app/src/lib.rs` (`auth_proxy`,
`check_replay_credentials`, `replay_adom_login`).
- **Auth components**: `src/lib/components/auth/` (Header, Form, Footer,
SubmitButton, Error, Success)
- **User API**: `src/lib/api/authenticated_user.ts`
---
## Session Token
**Location**: Hydrogen's app-data directory on the host (the `hydrogen-session.txt`
file).
On Linux every auth file is in Hydrogen's state folder `~/.config/hydrogen-desktop/` on
the host (not in the workspace):
| File | Purpose |
|---|---|
| `hydrogen-session.txt` | The Adom session token. Read by the auth proxy; deleted on logout or a 401. |
| `replay-session.txt` | Replay copy; lets the login page sign you back in without a browser ("Signing you in... Ns"). |
| `replay-claude-credentials.json` | Claude Code credentials kept across a virgin reset (see **hydrogen-claude-auth**). |
From the workspace, the host's home is visible at `/mnt/host/home/<user>/`, but the
supported way to get the token is the control API below.
A plain-text file containing the Adom session cookie value. Created by either:
- The auth intent flow (on successful poll)
- The auth proxy (when Carbon returns a `set-cookie: session_token=...` header)
The auth proxy (`invoke('auth_proxy', ...)`) reads this file and attaches it
as a `Cookie: session_token=...` header on every request to `carbon.adom.inc`.
### Token lifecycle
- **Created**: on login (auth intent or browser set-cookie capture)
- **Refreshed**: automatically when the auth proxy receives a new set-cookie
- **Cleared**: on logout (`auth_proxy({path: "/auth/clear-local"})`) or on
401 response (backend auto-deletes the file)
- **Max age**: 90 days (set at intent creation)
### Reading the token programmatically
```bash
BASE="$(cat ~/.adom/hydrogen-control-url)" # normally http://127.0.0.1:47084
curl -s "$BASE/auth-token" # the saved Adom session token
cat /var/run/adom/api-key # the same account's key, written into the workspace
```
Hydrogen writes `/var/run/adom/api-key` (mode 644) at every launch and once during setup's
activate-editor step, after sign-in. `adom-cli`, `adom-wiki` and the editor use it.
---
## Auth Proxy
The backend command `auth_proxy` is the gateway for all authenticated requests
to the Adom Carbon API. It:
1. Reads the session token from disk
2. Attaches it as a cookie to the outgoing request
3. Captures any `set-cookie` response and updates the saved token
4. On 401, deletes the token and returns `{expired: true}`
5. Supports a special `path: "/auth/clear-local"` to delete the token file
**Base URL**: `https://carbon.adom.inc`
```javascript
// Example: get the current user
const result = await invoke('auth_proxy', {
path: '/api/me',
method: 'GET'
});
// result = { status: 200, data: { id: "...", name: "jlauer12", ... }, ok: true }
```
---
## Credential Replay
On login page mount, Hydrogen checks for saved credentials before starting the
full auth intent flow:
1. `invoke('check_replay_credentials')` checks if replay files exist on disk.
2. If the replay-session file exists (has_adom = true), the login page shows
"Signing you in... Ns" and counts down.
3. `invoke('replay_adom_login')` attempts to authenticate using the saved
session token.
4. If replay succeeds, the user is logged in without opening a browser.
5. If replay fails, Hydrogen falls back to the normal auth intent flow.
This makes re-login after a virgin reset instant when the user chose to
preserve the Adom session token.
---
## Claude Credentials
**Location**: Hydrogen's app-data directory on the host (the
`replay-claude-credentials.json` file).
Stores Claude Code credentials so they survive a virgin reset (see
**hydrogen-claude-auth**).
### Virgin reset options for auth
The virgin reset panel (Setup Panel -> Virgin Reset) has per-item toggles:
| Toggle | File | What it clears |
|--------|------|----------------|
| Adom session token | `hydrogen-session.txt` | Adom login. Next launch requires re-auth. |
| Claude credentials | `replay-claude-credentials.json` | Claude Code OAuth. Next bootstrap re-authenticates Claude. |
These are independent -- you can wipe Claude creds without losing Adom login,
or vice versa.
### CSS selectors for virgin reset auth options
```
label.virgin-opt -- each checkbox row
input[type="checkbox"] -- the toggle (bind:checked to virginOpts.adom_token / virginOpts.claude_token)
.virgin-hint -- shows filename (hydrogen-session.txt / replay-claude-credentials.json)
.vp-badge -- status badge ("exists" / "clean")
.vp-exists -- green badge (file exists)
.vp-clean -- gray badge (file gone)
```
---
## Profile Menu
**Location**: Top-right corner of the editor nav bar.
**Source**: `src/lib/components/editor/EditorNav.svelte` (lines ~2403-2443)
Click the circular user avatar to open a dropdown with two sections.
### Menu items
| Item | Icon | Action |
|------|------|--------|
| Your profile | `mdi:account-circle-outline` | Navigates to `/users/{username}` |
| Your repositories | `mdi:folder-outline` | Navigates to `/users/{username}/repositories` |
| Your molecules | `mdi:atom` | Navigates to `/users/{username}/molecules` |
| Log out | `mdi:logout` | Confirms, then clears session + redirects to login |
**CRITICAL**: Logout is ONLY in the profile menu (top-right avatar), NOT in
the Adom menu (top-left logo). Do not look for logout in the wrong menu.
### CSS selectors
| Element | Selector |
|---------|----------|
| Profile dropdown container | `.profile-dropdown-container` |
| Avatar button | `.profile-dropdown-button` |
| Avatar image | `.profile-dropdown-button img` |
| Dropdown (open) | `.profile-dropdown-content.open` |
| Menu items | `.profile-dropdown-content .dropdown-link` |
| Menu item icons | `.dropdown-link span` |
### Eval examples (`/eval-in {target:"shell"}`)
```javascript
// Open the profile menu
document.querySelector('.profile-dropdown-button')?.click();
// Click "Your profile"
var links = document.querySelectorAll('.profile-dropdown-content .dropdown-link');
if (links[0]) links[0].click();
// Click "Your repositories"
if (links[1]) links[1].click();
// Click "Your molecules"
if (links[2]) links[2].click();
// Click "Log out"
var logoutBtn = Array.from(document.querySelectorAll('.profile-dropdown-content .dropdown-link'))
.find(function(e) { return e.textContent.includes('Log out'); });
if (logoutBtn) logoutBtn.click();
// Note: this triggers a confirm dialog. To auto-confirm, you need to handle the dialog.
// Read the current user's avatar URL
var avatar = document.querySelector('.profile-dropdown-button img');
avatar ? avatar.src : 'no avatar';
// Read the current username from the avatar alt text
avatar ? avatar.alt : 'unknown';
```
---
## Logout Flow
1. User clicks "Log out" in profile menu.
2. `showConfirm('Are you sure you want to log out?', 'Log Out')` -- confirmation dialog.
3. If confirmed (app mode):
- `invoke('auth_proxy', {path: '/auth/logout', method: 'DELETE'})` -- server-side logout
- `invoke('auth_proxy', {path: '/auth/clear-local', method: 'POST'})` -- deletes `hydrogen-session.txt`
- Clears auth-related domain preferences from `localStorage['hydrogen-url-routing-prefs']`
4. Redirects to `/auth/login`.
---
## Login Page UI
**Route**: `/auth/login`
### App mode (auth intent)
- Adom logo + "Log in to Hydrogen" header
- Confirmation code in a monospace box (`.confirmation-code`)
- Spinner + "Waiting for you to sign in..."
- "Open browser again" button (`.retry-button`)
### Browser mode (email/password)
- Standard form with email + password fields
- "Log In" submit button
- Footer with registration link
### Auth intent CSS selectors
| Element | Selector |
|---------|----------|
| Container | `.intent-container` |
| Confirmation code | `.confirmation-code` |
| Spinner | `.spinner` |
| Status message | `.intent-message` |
| Hint text | `.intent-hint` |
| Success message | `.intent-success` |
| Error message | `.intent-error` |
| Retry button | `.retry-button` |
### Eval on the login page (`/eval-in {target:"shell"}`)
```javascript
// Check auth intent state
document.querySelector('.intent-message')?.textContent;
// -> "Waiting for you to sign in..." or "Authenticated! Redirecting..."
// Read the confirmation code
document.querySelector('.confirmation-code')?.textContent;
// Click retry
document.querySelector('.retry-button')?.click();
```
---
## How Auth Affects Setup Steps
The setup/bootstrap process depends on a valid session token:
The activate-editor step waits for the Adom sign-in (the editor mounts only after login),
then binds the workspace to this launch: environment, the api-key write-through and the
relay. If the token is missing or expired, `adom-cli` in the workspace cannot authenticate:
sign in again, then run setup again from the Adom menu > Setup Steps.
---
## Control API Auth Endpoints
| Method | Path | Description |
|--------|------|-------------|
| GET | `/auth-token` | Read the saved Adom session token (same-origin callers only) |
| POST | `/claude-auth` | Start Claude Code OAuth (PKCE) |
| GET | `/oauth/callback` | Receives OAuth redirect (auto, do not call) |
| POST | `/start-oauth-proxy` | Spin up temp TCP listener for OAuth callback |
| POST/GET | `/auth/proxy` | Proxy request to Carbon API with session token |
See the **hydrogen-settings** skill (API Explorer section) for the
full endpoint reference.
---
## Cross-references
- **hydrogen-claude-auth** -- Claude Code sign-in, separate from Adom
- **hydrogen-profile-menu** -- where login/logout live in the UI
- **hydrogen-settings** -- API Explorer (auth endpoints tab)
- **hydrogen-networking** -- how to reach the control API port
- **hydrogen-api** -- the control API
- **hydrogen-key-values** -- the account's cloud key-value store