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-api description: >- Reference for Hydrogen's control API on Linux: drive the workspace, Claude Code, VS Code, workspace tabs and setup steps over HTTP; GET /_manifest is the live catalog. Use when calling a Hydrogen endpoint, finding the control port, using the API Explorer, or checking which endpoints are destructive.
Hydrogen Control API Reference
The control API is large and grows. This file quoted "~159 endpoints" in its body and "~200" in its own frontmatter while the router carried 274: two stale numbers that did not even agree with each other, in the one document whose job is to be accurate about the API. So it no longer quotes a count at all. Don't trust a static count or list in this file to stay exhaustive — the API is self-documenting, with two live sources of truth you should hit first:
| Source | What it gives you | Where |
|---|---|---|
GET /_manifest |
THE complete catalog — every registered route (path, method, args, category, description, visibility). Curated entries carry richer descriptions; the rest are auto-generated from the router (scripts/gen-manifest.py), so it never drifts. Discover here first — don't guess paths. |
hydrogen-control/src/lib.rs /_manifest arm |
| API Explorer window | The human face of /_manifest: every endpoint grouped by category tab, with a runnable Try + Copy URL. Open from the Adom menu, or POST /api-explorer/open. |
Adom menu ▸ API Explorer |
Workspace control (:47083) |
A SEPARATE server (hydrogen-proxy), and its ~30 routes are NOT in /_manifest: /tabs, /tabs/find, /active-tab, /splits, /swaps, /moves, /nav, /window-mode, /caption, /recording, /screenshot, /audio, /sharing, /notification. This is the surface the in-container AI reaches through adom-cli. Enumerating /_manifest alone will NOT show you these. |
hydrogen-proxy/src/lib.rs |
GET /test/help |
The /test/* diagnostics (setup-steps state, cascade reset). Gated behind HD_TEST_API_ENABLED=1: 404 by default (expected, not a bug). |
hydrogen-control/src/lib.rs /test/help arm |
On Linux, routes that do nothing here say so in their /_manifest description ("Not available
on Linux.").
⛔ Safety — the API enforces this, and tells you in-band
The API itself now labels, warns about, and gates dangerous endpoints (single source of
truth: safety.rs in hydrogen-control). Three tiers:
catastrophic: irreversibly destroys real user state:/setup/panel/(run-virgin-reset|wipe-keep-auth),/config-reset,/claude/wipe-creds,*-delete. Headless calls (no browser Origin header — i.e. YOU) get HTTP 409confirmation_requiredand NOTHING happens until you re-call with?confirm=1. Only add?confirm=1when the user explicitly asked for exactly that action — never to make an error go away.destructive— kills/restarts/re-runs real state (recoverable but real):/app/(restart|relaunch-frontend),/reload-vscode,/container(-stop|-restart),/workspace/apply-updates,/setup/(run-all|run-step|state| force-close|trigger|countdown),/claude/tabs/close-all,/updater/install. Never call these speculatively or in a sweep.disruptive: the user SEES it (a window opens, focus moves, typing lands in their real chat):/hbw/open(and/hbw/closeto close one by label),/api-explorer/open,/open-url,/open-in-profile,/window/foreground,/ai-cursor/*,/ui/toast,/claude/(trigger-auth|open-with-message|inject*|send|submit|new-chat-and-send|type-and-submit)(the send/submit ones SPEND a real user turn). Run only when the user actually wants that action, and clean up after yourself.
How the API tells you:
- Before calling: every
GET /_manifestentry carriessafety+safety_note. Check them before you POST anything unfamiliar. Unlabeled = safe. - When you call: responses from these endpoints include a
_safetyblock. READ IT — it says exactly what you just did to the user's machine. - The 409 gate is your last chance to stop; it is not an error to route around.
A safe GET/POST returns within a couple seconds with a 2xx or a clean 4xx {ok:false,...}.
If you must probe an endpoint you're unsure about, POST an empty {} body and treat a
graceful validation error as "it works" — a 500 or a hang is the bug.
Base URL: http://127.0.0.1:<dynamic>, the same loopback address from inside the
workspace (the workspace machine shares the host's network) and on the host. The port is
dynamic per launch; read the live URL from ~/.adom/hydrogen-control-url: see "Finding the
Control Port" below.
Finding the Control Port
The control API port is dynamic (default 47084, auto-resolves conflicts).
# From the workspace: Hydrogen rewrites this file every launch. USE THIS.
CTRL="$(cat ~/.adom/hydrogen-control-url)"; curl -sf "$CTRL/health"
# On the host: the live port map
cat ~/.config/hydrogen-desktop/ports.json
# No file access (remote tool, browser)? Probe the DISCOVERY responder: fixed candidate
# ports tried in order. Take the FIRST that answers with
# service == "hydrogen-desktop-discovery"; its control_url is the live control API:
for p in 47080 48080 49180 50280; do
R=$(curl -sf --max-time 2 "http://127.0.0.1:$p/") && echo "$R" | grep -q hydrogen-desktop-discovery && break
done
⭐ From the workspace, read ~/.adom/hydrogen-control-url (e.g. http://127.0.0.1:<control>) — a
file, NOT an env var (your non-interactive Bash shells don't source .bashrc/profile.d). Hydrogen
rewrites it with the live dynamic port every launch. This is the channel for the UI command bus,
the live ports map, Claude control, etc. — distinct from adom-cli (ADOM_HYDROGEN_URL → SSE),
which is unchanged for web-hydrogen parity.
Calling gotchas (learned the hard way)
- Never hardcode the port. It's dynamic (47084 is only the default and it auto-resolves
conflicts). Read
~/.adom/hydrogen-control-urlfrom the workspace, orGET /ports. Hardcoding 47084 is what makes tools show Hydrogen as "down" when it's actually up on another port. - Calling from a REMOTE container (hc/cloud)? Use
adom-bridge hd_api, the relay's pass-through verb:hd_api {"method":"POST","path":"/...","body":{...}}. It auto-discovers the port; never shell curl through the relay (quoting gets mangled). Long-blocking calls (typed injection) can outlive the relay timeout: the work still completes on Hydrogen's side, so verify state instead of re-firing. This reaches this computer while Adom Bridge runs here (Hydrogen installs and starts it when a Linux build is published for the user's account). - Getting files OUT:
POST /screenshot {"b64":true}returns the PNG inline asdataUrl(the file itself is saved on the host under~/.config/hydrogen-desktop/shots/). To hand a workspace file to the host, copy it to/mnt/host/tmp/(the host's/tmp). - Confirm it's really the control API, not the SPA. In dev, the frontend file server
answers 200 with HTML for any path — so a bare 200 doesn't prove you hit Hydrogen's API. Check
GET /healthreturns JSON withservice:"hydrogen-desktop-control". - Driving Hydrogen from a page Hydrogen serves? Use relative fetches, not Tauri IPC. Tauri
invokeis unavailable on remote http origins; a same-originfetch('/ports')/fetch('/_manifest')works and sidesteps port discovery entirely. - No CDP on Linux. WebKitGTK has no Chrome DevTools Protocol; nothing listens on the
cdpport./eval,/eval-in,/cdp-evalrun over Hydrogen's frame bus (see hydrogen-eval);/targets,/iframe-evaland/webview/framesreturn nothing useful here.
Health & Status
| Method | Path | Description |
|---|---|---|
| GET | /health |
Hydrogen alive check — returns {ok, port, service} |
| GET | /buildinfo |
Running build git SHA + build metadata (the only trustworthy "did my build ship?" check) |
| GET | /ports |
The 4 editable PortConfig ports (proxy, control, cdp, code_server) |
| GET | /ports/all |
LIVE full port map: host listeners + every listener inside the workspace machine |
Driving Hydrogen's UI (command bus)
Open/close/toggle any Hydrogen menu, dialog, or panel. See the hydrogen-ui skill.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /ui/actions |
— | List every drivable UI action {id,label,description,group} (+ _hints) |
| POST | /ui/invoke |
{"id":"ports.open"} |
Run a UI action; returns {ok,value} only after the frontend ran it |
| GET | /auth-token |
Hydrogen session token | |
| GET | /setup-status |
Setup snapshot (legacy container/image/volume fields answered from the machine) |
|
| GET | /diagnostics/all |
Run all diagnostic checks | |
| GET | /diagnostics/{name} |
Run a single diagnostic check |
Workspace Management
These endpoints manage the workspace: the Adom-Workspace systemd-nspawn machine. The
paths keep their historical container spelling; there is no container.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /container-status |
Runtime present, machine present and running | |
| GET | /container-stats |
— | CPU, memory, disk usage |
| POST | /container-restart, /container-stop |
Restart / stop the machine (your own shell dies with it) | |
| POST | /workspace/exec |
{"command":"..."} |
The way to run a command in the workspace as adom |
| POST | /container-exec |
{"command":"..."} |
Older alias path for the same job |
| POST | /container/restart |
— | Alias for /container-restart |
| POST | /direct/command |
{...} |
Direct-connect command channel into the workspace |
| GET | /workspace/health |
Deep health: machine, code-server, host reachability | |
| GET | /wsl/status |
Name kept for compatibility: machine present and running, code-server reachable |
/container-delete, /image-delete, /volume-delete, /container-pull-image answer that there
is nothing to do on Linux; a wipe is the Setup panel's Virgin Reset.
WebView & VS Code
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /eval |
{"js":"..."} |
JS eval in main Hydrogen webview |
| POST | /eval-in |
{"target":"workbench","js":"..."} |
JS in any surface (frame bus on Linux) |
| POST | /click |
{"selector":"..."} |
Click an element of the shell page by selector |
| POST | /query |
{"selector":"..."} |
Query DOM elements |
| POST | /reload-vscode |
— | Reload the VS Code iframe |
| POST | /vscode/hide-activity-items |
— | Hide activity-bar items (persisted, overflow-proof) |
| GET/POST | /devtools |
Opens the WebKit Web Inspector (also Ctrl+Shift+I) |
AI cursor (visible cursor for demos / clicking)
Distinct from /click and /mouse-click — this renders a visible AI cursor,
glides it, and can click. Use for demos or when the user should see where the AI clicks.
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /ai-cursor/move |
{"x":N,"y":N} |
Move (glide) the visible AI cursor to coordinates |
| POST | /ai-cursor/click |
{"x":N,"y":N} |
Move the visible AI cursor there + click |
| POST | /ai-cursor/hide |
— | Hide the visible AI cursor |
On Linux /mouse-click does not move the pointer or click, and /ai-cursor/click shows the
cursor but its click is sent over CDP, so it does not land: click with /click {selector} or an
/eval-in that calls el.click().
Screenshot primitives
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /capture/viewport |
— | Capture the Hydrogen webview viewport (PNG) |
| POST | /shot |
{...} |
Screenshot primitive (see hydrogen-self-screenshot for the full workflow) |
Port hints
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /adom-port-hints |
— | Read the workspace port-hints map |
| POST | /adom-port-hints |
{...} |
Write/merge the workspace port-hints map |
Claude Code
Status / auth state (GET)
| Method | Path | Description |
|---|---|---|
| GET | /claude/status |
Install state, auth, active session, version |
| GET | /claude/auth-check |
Deep auth check — file exists, token, expiry |
| GET | /claude/auth-status |
Auth-status detail |
| GET | /claude/auth-page-state |
Which auth screen the panel shows: continue-in-browser | subscription-button | chat; returns oauth_url + at_browser_auth_gate |
| GET | /claude/detect-auth-failure |
Scan webview contexts for auth button/errors |
| GET | /claude/sessions |
List active Claude sessions |
Auth actions (POST)
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /claude/find-auth-button |
— | Find + highlight the sign-in button WITHOUT clicking (validation) |
| POST | /claude/start-auth |
— | Find + highlight + CLICK the "Claude.ai Subscription" button to begin OAuth |
| POST | /claude/trigger-auth |
— | Alias for start-auth |
| POST | /claude/detect-state |
— | Detect current auth/panel state |
| POST | /claude/authorize-in-browser |
Not available on Linux: finish the claude.ai consent in the browser yourself. The /claude/uia-* routes are not available either. |
|
| POST | /claude/authorize-tab-enter |
— | Approve the Adom OAuth tab via Enter (branded picker flow) |
| POST | /claude/inject-creds |
— | Push host backup credentials into the workspace |
| POST | /claude/wipe-creds |
{"backup":B} |
Wipe Claude credentials (destructive); backup:false keeps the host backup so reinject can restore |
Panel / conversation control (POST unless noted)
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /claude/open |
— | Open Claude Code panel (claude-vscode.editor.open) |
| POST | /claude/ensure-open |
— | Ensure the panel is open (strict readiness; recovery if not rendered) |
| POST | /claude/open-with-message |
{"message":"..."} |
Open + pre-fill message |
| POST | /claude/focus |
— | Focus Claude panel |
| POST | /claude/new-conversation |
— | Start a fresh conversation (shows sign-in panel when unauthenticated) |
| POST | /claude/new-chat-and-send |
{"text":"...","typed":B,"submit":B,"delay_ms":N} |
Open fresh conversation, wait for compose box, type + (default) submit |
| POST | /claude/submit |
— | Find + click send button |
| POST | /claude/send |
{"message":"..."} |
Send message to Claude |
| POST | /claude/inject |
{"message":"..."} |
Inject text into the compose box |
| POST | /claude/inject-message |
{"message":"..."} |
Inject into conversation |
| POST | /claude/type-and-submit |
{"message":"...","delay_ms":N} |
Type char-by-char (human-paced) + submit |
| POST | /claude/remote-control |
{"name":"..."} |
Turn on Claude Code Remote Control (submits /remote-control slash command) |
| POST | /claude/highlight-open-button |
{"duration":N} |
Glow animation on Claude button |
| POST | /claude/clear-open-highlight |
— | Clear the open-button highlight |
OAuth & Auth
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /claude-auth |
— | Full PKCE OAuth flow — opens browser, sets up callback |
| GET | /oauth/callback |
— | OAuth callback handler (receives auth code) |
| POST | /auth/proxy |
varies | Proxy auth requests to carbon.adom.inc |
| POST | /open-url |
{"url":"..."} |
Open URL (triggers browser picker) |
| POST | /start-oauth-proxy |
{"port":N} |
Start OAuth callback proxy on a port |
| GET | /browser-profiles |
— | List browsers + profiles with avatars |
| POST | /open-in-profile |
{"url":"...","browser":"...","profileDir":"..."} |
Open URL in specific browser profile |
| POST | /browser-picker/opened |
{...} |
Frontend reports the browser picker was opened |
| GET | /browser-picker/last-open |
— | Last browser-picker open event |
Because the network is shared, an OAuth callback on localhost:<port> in the workspace is
reachable from the host browser directly.
Setup Steps & Setup Panel
State / trigger / step control
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /setup/state |
— | Get current setup state (never-run | in-progress | complete) |
| POST | /setup/state |
{"state":"..."} |
Set setup state |
| POST | /setup/step/<id> |
{"continue_after":B} |
⭐ Run one step by id (forces panel visible first); continue_after:true runs this step + every step after it |
| POST | /setup/force-close |
— | Force-close setup panel |
| POST | /setup/countdown |
{"seconds":N,"message":"..."} |
Show countdown overlay |
| GET | /setup/trigger |
— | Read trigger file |
| DELETE | /setup/trigger |
— | Delete trigger file |
| POST | /config-reset |
— | Reset Hydrogen config |
To run steps: use
POST /setup/step/<id>or relaunch Hydrogen to auto-run the cascade.
Setup panel control
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /setup/panel/show |
— | Force the setup panel visible |
| POST | /setup/panel/hide |
— | Hide the setup panel |
| POST | /setup/panel/show-virgin-reset |
— | Show panel + expand the Virgin Reset section |
| POST | /setup/panel/virgin/show |
— | Show the Virgin Reset section only |
| POST | /setup/panel/virgin/hide |
— | Hide the Virgin Reset section |
| POST | /setup/panel/set-virgin-options |
{"options":{...}} |
Set the virgin-reset checkboxes |
| POST | /setup/panel/run-virgin-reset |
— | ⭐ The ONLY allowed virgin-reset trigger — UI-visible by construction (shows panel + checkboxes + progress before deleting anything) |
| POST | /setup/panel/wipe-keep-auth |
— | Synchronous wipe that KEEPS Adom + Claude tokens |
| POST | /setup/screenshot-mode |
{"enabled":B} |
Toggle per-step screenshot capture (default OFF) |
| GET | /setup/screenshot-mode |
— | Whether per-step screenshot mode is on |
Workspace Tabs
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /workspace/tabs |
— | List all workspace tabs |
| GET | /workspace/tabs/find?name=X |
— | Find tab by name (404 if not found) |
| POST | /workspace/tabs |
{tab spec} |
Add a new tab |
| POST | /workspace/tabs/activate |
{tabId} or {name} or {panelId, tabIndex} |
Bring one tab to the front |
| POST | /workspace/tabs/remove |
{tabId} or {name} or {panelId, tabIndex} |
Close one tab (/workspace/tabs/close is the same) |
| POST | /workspace/tabs/move |
{tabId or name, targetPanelId} |
Move a tab to another pane |
| POST | /workspace/swap |
{panelA, panelB} |
Swap two panes |
| POST | /workspace/split |
{panelId, direction, position?, ratio?, panelType?, displayName?, initialState?} |
Split a pane; answers the new panelId |
| POST | /workspace/resize |
{splitId, ratio} |
Set a split's proportion (0.1 to 0.9) |
| POST | /workspace/close-panel |
{panelId} |
Close a pane and its tabs |
| GET | /workspace/get |
(none) | The whole live layout tree: panes, splits (id and ratio), tabs |
The whole layout API is on the desktop control port (the same on Windows and Linux): drive it with
curl from the host or through Adom Bridge, no workspace needed. Each route is the twin of an
adom-cli hydrogen workspace verb (get, active-tab, remove-tab, move-tab, swap, split,
resize, close-panel) on the same live tree, and every answer's _hints.adom_cli names it.
The VS Code pane holds the user's AI threads (John 2026-11-15). A call that covers, hides,
replaces or removes it (closing its pane, removing or moving the VS Code tab, moving or activating
another tab in front of it, adding a tab to its pane by name) is allowed, but its answer carries
_hints.vscode: a strong warning and, in undo, the exact call that puts VS Code back. Read it,
and undo unless you had a very good reason. Hydrogen's own placement never does this: a new tab
with no pane named (the dock, webview open-or-refresh, POST /workspace/tabs without
panelId) opens in another pane, or, when VS Code's pane is the only one, in a new right-hand
split at half the width.
Example, from the host:
C=http://127.0.0.1:47084
curl -s $C/workspace/tabs # tabs with tabId, panelId, name
curl -s -X POST $C/workspace/split -d '{"panelId":"desktop-pane-left","direction":"horizontal","panelType":"adom/a1b2c3d4-0031-4000-a000-000000000031","displayName":"Notes","initialState":{"url":"about:blank"}}'
curl -s -X POST $C/workspace/tabs/move -d '{"name":"Wiki","targetPanelId":"<new pane id>"}'
curl -s -X POST $C/workspace/tabs/activate -d '{"name":"Wiki"}'
curl -s -X POST $C/workspace/tabs/remove -d '{"name":"Notes"}'
curl -s -X POST $C/workspace/close-panel -d '{"panelId":"<new pane id>"}'
System
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /system/reboot-state |
Always null on Linux: Hydrogen setup never needs a reboot here | |
| POST | /system/reboot |
Not available on Linux: Hydrogen does not reboot this computer |
/recording/native/* answers that native recording is not available on Linux.
App lifecycle & window
| Method | Path | Body | Description |
|---|---|---|---|
| POST | /app/restart |
— | Restart the Hydrogen app (kills + respawns the binary) |
| POST | /app/relaunch-frontend |
— | Relaunch the Hydrogen GUI (kill+respawn) while it is responsive |
| POST | /window/foreground |
— | Bring the Hydrogen window to the foreground (unminimize + focus) |
The desktop's window manager may refuse to raise the window for /window/foreground.
Diagnostics (/test/*)
Setup-cascade and state diagnostics. Gated behind HD_TEST_API_ENABLED=1 (return 404 /
"test API disabled" otherwise). GET /test/help self-lists the whole cluster.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | /test/help |
— | Self-lists every /test/* endpoint |
| GET | /test/window-tree |
Not available on Linux | |
| POST | /test/click-uia |
Not available on Linux | |
| GET | /test/setup-steps |
— | Raw setup-steps.json + derived summary (alias: /test/install-steps) |
| POST | /test/reset-cascade |
— | Delete install-steps.json + emit setup-reset event |
| GET | /test/probe-dialogs |
Not available on Linux |
Key Patterns
container-exec
Runs as user adom inside the workspace. Use full paths (/home/adom/
not ~/). Tilde doesn't expand through the exec chain.
POST /container-exec {"command":"ls /home/adom/project"}
Re-run a setup step after completion
The trigger file poller STOPS when all steps are done. Re-run one step by id (or relaunch Hydrogen to auto-run the cascade):
POST /setup/step/<id>
Complete route index
The index below lists the routes every platform's router carries. On Linux some of them answer that they are not available here; their
/_manifestdescription says so.
Every route Hydrogen for Linux serves, 332 across 23 categories, grouped the way the
API Explorer groups them. Routes that do nothing on Linux are left out, as they are from
/_manifest and the API Explorer here. Generated from the same table /_manifest serves, so it
cannot drift from the code; scripts/check-manifest-fresh.sh fails the build if it does.
/_manifest remains the richer source at runtime: it carries each route's args, its
description, and a safety flag (destructive / disruptive) that this flat index does not.
Read a route's safety from /_manifest before calling it, not from this list.
AI Accounts (14)
POST /agents/apikeyGET /agents/barGET /agents/catalogPOST /agents/installPOST /agents/loginPOST /agents/login-inputPOST /agents/login-stopGET /agents/login-urlPOST /agents/logoutPOST /agents/presentPOST /agents/setup-donePOST /agents/setup-resetGET /agents/setup-stateGET /agents/status
AI Threads (39)
GET /ai-threadsPOST /ai-threads/activatePOST /ai-threads/answerPOST /ai-threads/closeGET /ai-threads/dom-debugPOST /ai-threads/dom-eventGET /ai-threads/dom-eventsPOST /ai-threads/focusGET /ai-threads/historyPOST /ai-threads/hook-eventPOST /ai-threads/injectPOST /ai-threads/inspectPOST /ai-threads/installGET /ai-threads/install/logPOST /ai-threads/issue-injectGET /ai-threads/issue-queueGET /ai-threads/namesPOST /ai-threads/newPOST /ai-threads/new-tuiPOST /ai-threads/pickGET /ai-threads/promptsPOST /ai-threads/renamePOST /ai-threads/reorderPOST /ai-threads/repo-linkGET /ai-threads/repo-linksPOST /ai-threads/resumePOST /ai-threads/run-promptGET /ai-threads/run-prompt/statusGET /ai-threads/settingsPOST /ai-threads/settingsGET /ai-threads/tabsPOST /ai-threads/tagGET /ai-threads/tagsGET /ai-threads/toolsPOST /ai-threads/uninstallGET /ai-threads/waitPOST /ai-threads/walkGET /ai-threads/walk-reportGET /ai-threads/wiki-repos
Adom Bridge (19)
GET /ab/direct-apiGET /ab/discovery-fileGET /ab/embeddedGET /ab/healthGET /ab/liveness-beaconGET /ab/permissionsPOST /ab/permissions/requestPOST /ab/permissions/revokeGET /ab/processGET /ab/relayGET /ab/settingsPOST /ab/settingsPOST /ab/showPOST /ab/toast-ackPOST /ab/verbGET /ab/workspace-directPOST /direct/commandGET /direct/healthGET /direct/status
Auth & User (7)
GET /auth-tokenGET /auth/browser-statusGET /auth/proxyPOST /auth/proxyDELETE /user/avatarPOST /user/avatarPOST /user/refresh
Browser & Open (11)
GET /browser-picker/last-openPOST /browser-picker/openedDELETE /browser-picker/prefsGET /browser-picker/prefsPUT /browser-picker/prefsGET /browser-profilesPOST /open-in-profilePOST /open-urlGET /webview-can-embedGET /webview-proxyGET /wiki-proxy
Claude (46)
POST /claude-authGET /claude/auth-checkGET /claude/auth-page-stateGET /claude/auth-statusPOST /claude/authorize-tab-enterPOST /claude/clear-open-highlightPOST /claude/cli-auth/codePOST /claude/cli-auth/startGET /claude/contextsGET /claude/conversation-stateGET /claude/conversationsPOST /claude/cross-evalGET /claude/detect-auth-failurePOST /claude/detect-statePOST /claude/ensure-openPOST /claude/find-auth-buttonPOST /claude/focusPOST /claude/highlight-open-buttonPOST /claude/injectPOST /claude/inject-credsPOST /claude/inject-messagePOST /claude/new-chat-and-sendPOST /claude/new-conversationPOST /claude/openPOST /claude/open-with-messagePOST /claude/remote-controlPOST /claude/sample-promptGET /claude/sample-promptsPOST /claude/sample-prompts/refreshPOST /claude/sendGET /claude/sessionsPOST /claude/start-authGET /claude/statusPOST /claude/submitGET /claude/tabsPOST /claude/tabs/activatePOST /claude/tabs/close-allPOST /claude/tabs/close-empty-groupsPOST /claude/tabs/close-untitledPOST /claude/tabs/merge-groupsPOST /claude/trigger-authPOST /claude/type-and-submitPOST /claude/wipe-credsPOST /config-resetGET /oauth/callbackPOST /start-oauth-proxy
Container / Docker (legacy) (15)
POST /container-deletePOST /container-execPOST /container-pull-imagePOST /container-restartPOST /container-startGET /container-statsGET /container-statusPOST /container-stopGET /container/diskGET /container/envGET /container/logsGET /container/portsPOST /container/restartPOST /image-deletePOST /volume-delete
Dock (6)
GET /dock/appsPOST /dock/closePOST /dock/launchPOST /dock/refreshPOST /dock/resetPOST /dock/result
Editor State Machine (ESM) (4)
POST /editor/audit-promptPOST /editor/barsPOST /editor/normalizeGET /editor/state
Eval & Automation (17)
POST /ai-cursor/clickPOST /ai-cursor/hidePOST /ai-cursor/movePOST /cdp-evalPOST /clickGET /devtoolsPOST /devtoolsPOST /evalPOST /eval-inPOST /files/injectPOST /iframe-evalPOST /mouse-clickPOST /queryPOST /reload-vscodeGET /targetsPOST /vscode/commandPOST /vscode/hide-activity-items
Health & Build (17)
GET /_manifestPOST /app/relaunch-frontendPOST /app/restartGET /buildinfoGET /cdp-infoGET /consoleGET /diagnosticsGET /diagnostics/allGET /doctorPOST /doctorGET /healthGET /logs/tailGET /portsGET /ports/allPOST /ports/checkPOST /ports/setPOST /report/problem
Hydrogen Browser Window (11)
GET /hbw/chromePOST /hbw/chrome-togglePOST /hbw/closePOST /hbw/navPOST /hbw/openGET /hbw/speedPOST /hbw/speedGET /hbw/stateGET /hbw/tipGET /hbw/tip-statePOST /hbw/tooltip
Other (2)
POST /proxy/restartPOST /telemetry/webview-gpu
Permissions (3)
POST /permission/dismissPOST /permission/requestPOST /permission/resolve
Screenshots & Recording (13)
POST /annotateGET /annotate/hotkeyPOST /annotate/hotkeyGET /capture/availabilityGET /capture/viewportGET /recording/native/capabilitiesPOST /recording/native/resetGET /recording/native/sourcesPOST /recording/native/startGET /recording/native/statusPOST /recording/native/stopPOST /screenshotPOST /shot
Settings (2)
GET /settings/external-changesPOST /settings/rebroadcast
Setup Cascade (25)
GET /setup-statusPOST /setup/countdownGET /setup/flagsPOST /setup/flagsPOST /setup/force-closePOST /setup/panel/hidePOST /setup/panel/run-virgin-resetPOST /setup/panel/set-virgin-optionsPOST /setup/panel/showPOST /setup/panel/show-virgin-resetPOST /setup/panel/virgin/hidePOST /setup/panel/virgin/showPOST /setup/panel/wipe-keep-authPOST /setup/run-allPOST /setup/run-stepGET /setup/screenshot-modePOST /setup/screenshot-modeGET /setup/statePOST /setup/statePOST /setup/stepDELETE /setup/triggerGET /setup/triggerPOST /setup/virgin-resetPOST /virgin-resetGET /virgin-reset-progress
System (6)
GET /adom-port-hintsPOST /adom-port-hintsGET /gpuPOST /gpuGET /system/nonceGET /system/reboot-state
Test & Dev (10)
POST /debug/show-auth-captionPOST /debug/zorder-probePOST /dev/emit-eventPOST /test/dump-statePOST /test/focusGET /test/helpGET /test/install-stepsPOST /test/reset-cascadePOST /test/screenshot-hd-windowGET /test/setup-steps
UI & Windows (23)
POST /api-explorer/openPOST /demo/runGET /dock-launch.htmlGET /favicon.icoGET /orbital-loader.htmlPOST /panel-webview/fullscreenGET /panes/memoryPOST /panes/reload-errorsPOST /ui/_bus-pongPOST /ui/_resultPOST /ui/_syncGET /ui/actionsPOST /ui/invokePOST /ui/toastPOST /ui/toast-ackGET /webview/framesPOST /webview/link-interceptedGET /webview/port-checkGET /welcome.htmlGET /widget-launch.htmlPOST /window/closePOST /window/foregroundPOST /window/show
Wake & Repair (5)
POST /wake/configPOST /wake/previewPOST /wake/preview/hidePOST /wake/simulateGET /wake/status
Widgets (8)
GET /widgetsPOST /widgets/cardPOST /widgets/closePOST /widgets/menuPOST /widgets/navigatePOST /widgets/openPOST /widgets/refreshGET /widgets/status
Workspace & Updates (29)
POST /migration/approvedPOST /migration/dismissedPOST /updater/checkPOST /updater/installPOST /updater/show-bannerGET /updater/statusPOST /workspace/apply-updatesPOST /workspace/check-updatesPOST /workspace/execGET /workspace/healthPOST /workspace/migration/approvePOST /workspace/migration/declineGET /workspace/statsGET /workspace/tabsPOST /workspace/tabsGET /workspace/tabs/POST /workspace/tabs/GET /workspace/tabs/findPOST /workspace/vscode-settingsPOST /workspaces/applyGET /workspaces/benchesPOST /workspaces/demoPOST /workspaces/menuPOST /workspaces/offerPOST /workspaces/refreshPOST /workspaces/resetPOST /workspaces/saveGET /workspaces/statusPOST /workspaces/unload
Workspace control (~30 routes, a SEPARATE server on the proxy port, absent from /_manifest)
Reached at /api/workspaces/editor/<owner>/<repo>/current/..., which the handler strips
before matching. A bare GET /tabs on the proxy 404s; that is correct, not a fault.
/tabs/tabs/find/tabs/alert/active-tab/splits/swaps/moves/nav/reload/window-mode/caption/recording/screenshot/audio/sharing/notification/probe
---
name: hydrogen-api
description: >-
Reference for Hydrogen's control API on Linux: drive the workspace, Claude Code, VS Code,
workspace tabs and setup steps over HTTP; GET /_manifest is the live catalog. Use when
calling a Hydrogen endpoint, finding the control port, using the API Explorer, or
checking which endpoints are destructive.
---
# Hydrogen Control API Reference
The control API is large and grows. This file quoted "~159 endpoints" in its body and
"~200" in its own frontmatter while the router carried **274**: two stale numbers that did
not even agree with each other, in the one document whose job is to be accurate about the
API. So it no longer quotes a count at all. Don't trust a static count or list in
this file to stay exhaustive — the API is **self-documenting**, with two live
sources of truth you should hit first:
| Source | What it gives you | Where |
|---|---|---|
| `GET /_manifest` | **THE complete catalog** — every registered route (`path`, `method`, `args`, `category`, `description`, `visibility`). Curated entries carry richer descriptions; the rest are auto-generated from the router (`scripts/gen-manifest.py`), so it never drifts. **Discover here first — don't guess paths.** | `hydrogen-control/src/lib.rs` `/_manifest` arm |
| **API Explorer window** | The human face of `/_manifest`: every endpoint grouped by category tab, with a runnable **Try** + Copy URL. Open from the Adom menu, or `POST /api-explorer/open`. | Adom menu ▸ API Explorer |
| **Workspace control** (`:47083`) | A SEPARATE server (`hydrogen-proxy`), and its ~30 routes are **NOT in `/_manifest`**: `/tabs`, `/tabs/find`, `/active-tab`, `/splits`, `/swaps`, `/moves`, `/nav`, `/window-mode`, `/caption`, `/recording`, `/screenshot`, `/audio`, `/sharing`, `/notification`. This is the surface the in-container AI reaches through `adom-cli`. Enumerating `/_manifest` alone will NOT show you these. | `hydrogen-proxy/src/lib.rs` |
| `GET /test/help` | The `/test/*` diagnostics (setup-steps state, cascade reset). **Gated behind `HD_TEST_API_ENABLED=1`**: 404 by default (expected, not a bug). | `hydrogen-control/src/lib.rs` `/test/help` arm |
On Linux, routes that do nothing here say so in their `/_manifest` description ("Not available
on Linux.").
## ⛔ Safety — the API enforces this, and tells you in-band
The API itself now labels, warns about, and gates dangerous endpoints (single source of
truth: `safety.rs` in hydrogen-control). Three tiers:
- **`catastrophic`**: irreversibly destroys real user state:
`/setup/panel/(run-virgin-reset|wipe-keep-auth)`, `/config-reset`, `/claude/wipe-creds`,
`*-delete`.
**Headless calls (no browser Origin header — i.e. YOU) get HTTP 409 `confirmation_required`
and NOTHING happens** until you re-call with `?confirm=1`. Only add `?confirm=1` when the
user explicitly asked for exactly that action — never to make an error go away.
- **`destructive`** — kills/restarts/re-runs real state (recoverable but real):
`/app/(restart|relaunch-frontend)`, `/reload-vscode`,
`/container(-stop|-restart)`, `/workspace/apply-updates`, `/setup/(run-all|run-step|state|
force-close|trigger|countdown)`, `/claude/tabs/close-all`, `/updater/install`.
Never call these speculatively or in a sweep.
- **`disruptive`**: the user SEES it (a window opens, focus moves, typing lands in their
real chat): `/hbw/open` (and `/hbw/close` to close one by label), `/api-explorer/open`,
`/open-url`, `/open-in-profile`, `/window/foreground`, `/ai-cursor/*`, `/ui/toast`,
`/claude/(trigger-auth|open-with-message|inject*|send|submit|new-chat-and-send|type-and-submit)`
(the send/submit ones SPEND a real user turn). Run only when the user actually wants that
action, and clean up after yourself.
How the API tells you:
- **Before calling:** every `GET /_manifest` entry carries `safety` + `safety_note`. Check
them before you POST anything unfamiliar. Unlabeled = safe.
- **When you call:** responses from these endpoints include a `_safety` block. READ IT —
it says exactly what you just did to the user's machine.
- **The 409 gate** is your last chance to stop; it is not an error to route around.
A safe GET/POST returns within a couple seconds with a 2xx or a clean 4xx `{ok:false,...}`.
If you must probe an endpoint you're unsure about, POST an empty `{}` body and treat a
graceful validation error as "it works" — a 500 or a hang is the bug.
**Base URL:** `http://127.0.0.1:<dynamic>`, the same loopback address from inside the
workspace (the workspace machine shares the host's network) and on the host. The port is
dynamic per launch; read the live URL from `~/.adom/hydrogen-control-url`: see "Finding the
Control Port" below.
## Finding the Control Port
The control API port is dynamic (default 47084, auto-resolves conflicts).
```bash
# From the workspace: Hydrogen rewrites this file every launch. USE THIS.
CTRL="$(cat ~/.adom/hydrogen-control-url)"; curl -sf "$CTRL/health"
# On the host: the live port map
cat ~/.config/hydrogen-desktop/ports.json
# No file access (remote tool, browser)? Probe the DISCOVERY responder: fixed candidate
# ports tried in order. Take the FIRST that answers with
# service == "hydrogen-desktop-discovery"; its control_url is the live control API:
for p in 47080 48080 49180 50280; do
R=$(curl -sf --max-time 2 "http://127.0.0.1:$p/") && echo "$R" | grep -q hydrogen-desktop-discovery && break
done
```
⭐ **From the workspace, read `~/.adom/hydrogen-control-url`** (e.g. `http://127.0.0.1:<control>`) — a
file, NOT an env var (your non-interactive Bash shells don't source `.bashrc`/`profile.d`). Hydrogen
rewrites it with the live dynamic port every launch. This is the channel for the UI command bus,
the live ports map, Claude control, etc. — distinct from `adom-cli` (`ADOM_HYDROGEN_URL` → SSE),
which is unchanged for web-hydrogen parity.
## Calling gotchas (learned the hard way)
- **Never hardcode the port.** It's dynamic (47084 is only the default and it auto-resolves
conflicts). Read `~/.adom/hydrogen-control-url` from the workspace, or `GET /ports`. Hardcoding
47084 is what makes tools show Hydrogen as "down" when it's actually up on another port.
- **Calling from a REMOTE container (hc/cloud)? Use `adom-bridge hd_api`,** the relay's
pass-through verb: `hd_api {"method":"POST","path":"/...","body":{...}}`. It auto-discovers
the port; never shell curl through the relay (quoting gets mangled). Long-blocking calls
(typed injection) can outlive the relay timeout: the work still completes on Hydrogen's side, so
verify state instead of re-firing.
This reaches this computer while Adom Bridge runs here (Hydrogen installs and starts it when
a Linux build is published for the user's account).
- **Getting files OUT:** `POST /screenshot {"b64":true}` returns the PNG inline as `dataUrl` (the
file itself is saved on the host under `~/.config/hydrogen-desktop/shots/`). To hand a
workspace file to the host, copy it to `/mnt/host/tmp/` (the host's `/tmp`).
- **Confirm it's really the control API, not the SPA.** In dev, the frontend file server
answers 200 with HTML for *any* path — so a bare 200 doesn't prove you hit Hydrogen's API. Check
`GET /health` returns JSON with `service:"hydrogen-desktop-control"`.
- **Driving Hydrogen from a page Hydrogen serves? Use relative fetches, not Tauri IPC.** Tauri `invoke`
is unavailable on remote http origins; a same-origin `fetch('/ports')` / `fetch('/_manifest')`
works and sidesteps port discovery entirely.
- **No CDP on Linux.** WebKitGTK has no Chrome DevTools Protocol; nothing listens on the `cdp`
port. `/eval`, `/eval-in`, `/cdp-eval` run over Hydrogen's frame bus (see **hydrogen-eval**);
`/targets`, `/iframe-eval` and `/webview/frames` return nothing useful here.
## Health & Status
| Method | Path | Description |
|---|---|---|
| GET | `/health` | Hydrogen alive check — returns `{ok, port, service}` |
| GET | `/buildinfo` | Running build git SHA + build metadata (the only trustworthy "did my build ship?" check) |
| GET | `/ports` | The 4 editable PortConfig ports (proxy, control, cdp, code_server) |
| GET | `/ports/all` | LIVE full port map: host listeners + every listener inside the workspace machine |
## Driving Hydrogen's UI (command bus)
Open/close/toggle any Hydrogen menu, dialog, or panel. See the `hydrogen-ui` skill.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/ui/actions` | — | List every drivable UI action `{id,label,description,group}` (+ `_hints`) |
| POST | `/ui/invoke` | `{"id":"ports.open"}` | Run a UI action; returns `{ok,value}` only after the frontend ran it |
| GET | `/auth-token` | Hydrogen session token |
| GET | `/setup-status` | Setup snapshot (legacy `container`/`image`/`volume` fields answered from the machine) |
| GET | `/diagnostics/all` | Run all diagnostic checks |
| GET | `/diagnostics/{name}` | Run a single diagnostic check |
## Workspace Management
These endpoints manage the workspace: the `Adom-Workspace` systemd-nspawn machine. The
paths keep their historical `container` spelling; there is no container.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/container-status` | | Runtime present, machine present and running |
| GET | `/container-stats` | — | CPU, memory, disk usage |
| POST | `/container-restart`, `/container-stop` | | Restart / stop the machine (your own shell dies with it) |
| POST | `/workspace/exec` | `{"command":"..."}` | **The** way to run a command in the workspace as `adom` |
| POST | `/container-exec` | `{"command":"..."}` | Older alias path for the same job |
| POST | `/container/restart` | — | Alias for `/container-restart` |
| POST | `/direct/command` | `{...}` | Direct-connect command channel into the workspace |
| GET | `/workspace/health` | | Deep health: machine, code-server, host reachability |
| GET | `/wsl/status` | | Name kept for compatibility: machine present and running, code-server reachable |
`/container-delete`, `/image-delete`, `/volume-delete`, `/container-pull-image` answer that there
is nothing to do on Linux; a wipe is the Setup panel's Virgin Reset.
## WebView & VS Code
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/eval` | `{"js":"..."}` | JS eval in main Hydrogen webview |
| POST | `/eval-in` | `{"target":"workbench","js":"..."}` | JS in any surface (frame bus on Linux) |
| POST | `/click` | `{"selector":"..."}` | Click an element of the shell page by selector |
| POST | `/query` | `{"selector":"..."}` | Query DOM elements |
| POST | `/reload-vscode` | — | Reload the VS Code iframe |
| POST | `/vscode/hide-activity-items` | — | Hide activity-bar items (persisted, overflow-proof) |
| GET/POST | `/devtools` | | Opens the WebKit Web Inspector (also Ctrl+Shift+I) |
### AI cursor (visible cursor for demos / clicking)
Distinct from `/click` and `/mouse-click` — this renders a **visible** AI cursor,
glides it, and can click. Use for demos or when the user should see where the AI clicks.
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/ai-cursor/move` | `{"x":N,"y":N}` | Move (glide) the visible AI cursor to coordinates |
| POST | `/ai-cursor/click` | `{"x":N,"y":N}` | Move the visible AI cursor there + click |
| POST | `/ai-cursor/hide` | — | Hide the visible AI cursor |
On Linux `/mouse-click` does not move the pointer or click, and `/ai-cursor/click` shows the
cursor but its click is sent over CDP, so it does not land: click with `/click {selector}` or an
`/eval-in` that calls `el.click()`.
### Screenshot primitives
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/capture/viewport` | — | Capture the Hydrogen webview viewport (PNG) |
| POST | `/shot` | `{...}` | Screenshot primitive (see **hydrogen-self-screenshot** for the full workflow) |
### Port hints
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/adom-port-hints` | — | Read the workspace port-hints map |
| POST | `/adom-port-hints` | `{...}` | Write/merge the workspace port-hints map |
## Claude Code
### Status / auth state (GET)
| Method | Path | Description |
|---|---|---|
| GET | `/claude/status` | Install state, auth, active session, version |
| GET | `/claude/auth-check` | Deep auth check — file exists, token, expiry |
| GET | `/claude/auth-status` | Auth-status detail |
| GET | `/claude/auth-page-state` | Which auth screen the panel shows: `continue-in-browser` \| `subscription-button` \| `chat`; returns `oauth_url` + `at_browser_auth_gate` |
| GET | `/claude/detect-auth-failure` | Scan webview contexts for auth button/errors |
| GET | `/claude/sessions` | List active Claude sessions |
### Auth actions (POST)
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/claude/find-auth-button` | — | Find + highlight the sign-in button WITHOUT clicking (validation) |
| POST | `/claude/start-auth` | — | Find + highlight + CLICK the "Claude.ai Subscription" button to begin OAuth |
| POST | `/claude/trigger-auth` | — | Alias for start-auth |
| POST | `/claude/detect-state` | — | Detect current auth/panel state |
| POST | `/claude/authorize-in-browser` | | Not available on Linux: finish the claude.ai consent in the browser yourself. The `/claude/uia-*` routes are not available either. |
| POST | `/claude/authorize-tab-enter` | — | Approve the Adom OAuth tab via Enter (branded picker flow) |
| POST | `/claude/inject-creds` | — | Push host backup credentials into the workspace |
| POST | `/claude/wipe-creds` | `{"backup":B}` | Wipe Claude credentials (destructive); `backup:false` keeps the host backup so reinject can restore |
### Panel / conversation control (POST unless noted)
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/claude/open` | — | Open Claude Code panel (`claude-vscode.editor.open`) |
| POST | `/claude/ensure-open` | — | Ensure the panel is open (strict readiness; recovery if not rendered) |
| POST | `/claude/open-with-message` | `{"message":"..."}` | Open + pre-fill message |
| POST | `/claude/focus` | — | Focus Claude panel |
| POST | `/claude/new-conversation` | — | Start a fresh conversation (shows sign-in panel when unauthenticated) |
| POST | `/claude/new-chat-and-send` | `{"text":"...","typed":B,"submit":B,"delay_ms":N}` | Open fresh conversation, wait for compose box, type + (default) submit |
| POST | `/claude/submit` | — | Find + click send button |
| POST | `/claude/send` | `{"message":"..."}` | Send message to Claude |
| POST | `/claude/inject` | `{"message":"..."}` | Inject text into the compose box |
| POST | `/claude/inject-message` | `{"message":"..."}` | Inject into conversation |
| POST | `/claude/type-and-submit` | `{"message":"...","delay_ms":N}` | Type char-by-char (human-paced) + submit |
| POST | `/claude/remote-control` | `{"name":"..."}` | Turn on Claude Code Remote Control (submits `/remote-control` slash command) |
| POST | `/claude/highlight-open-button` | `{"duration":N}` | Glow animation on Claude button |
| POST | `/claude/clear-open-highlight` | — | Clear the open-button highlight |
## OAuth & Auth
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/claude-auth` | — | Full PKCE OAuth flow — opens browser, sets up callback |
| GET | `/oauth/callback` | — | OAuth callback handler (receives auth code) |
| POST | `/auth/proxy` | varies | Proxy auth requests to carbon.adom.inc |
| POST | `/open-url` | `{"url":"..."}` | Open URL (triggers browser picker) |
| POST | `/start-oauth-proxy` | `{"port":N}` | Start OAuth callback proxy on a port |
| GET | `/browser-profiles` | — | List browsers + profiles with avatars |
| POST | `/open-in-profile` | `{"url":"...","browser":"...","profileDir":"..."}` | Open URL in specific browser profile |
| POST | `/browser-picker/opened` | `{...}` | Frontend reports the browser picker was opened |
| GET | `/browser-picker/last-open` | — | Last browser-picker open event |
Because the network is shared, an OAuth callback on `localhost:<port>` in the workspace is
reachable from the host browser directly.
## Setup Steps & Setup Panel
### State / trigger / step control
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/setup/state` | — | Get current setup state (`never-run` \| `in-progress` \| `complete`) |
| POST | `/setup/state` | `{"state":"..."}` | Set setup state |
| POST | `/setup/step/<id>` | `{"continue_after":B}` | ⭐ Run one step by id (forces panel visible first); `continue_after:true` runs this step + every step after it |
| POST | `/setup/force-close` | — | Force-close setup panel |
| POST | `/setup/countdown` | `{"seconds":N,"message":"..."}` | Show countdown overlay |
| GET | `/setup/trigger` | — | Read trigger file |
| DELETE | `/setup/trigger` | — | Delete trigger file |
| POST | `/config-reset` | — | Reset Hydrogen config |
> To run steps: use `POST /setup/step/<id>` or relaunch Hydrogen to auto-run the cascade.
### Setup panel control
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/setup/panel/show` | — | Force the setup panel visible |
| POST | `/setup/panel/hide` | — | Hide the setup panel |
| POST | `/setup/panel/show-virgin-reset` | — | Show panel + expand the Virgin Reset section |
| POST | `/setup/panel/virgin/show` | — | Show the Virgin Reset section only |
| POST | `/setup/panel/virgin/hide` | — | Hide the Virgin Reset section |
| POST | `/setup/panel/set-virgin-options` | `{"options":{...}}` | Set the virgin-reset checkboxes |
| POST | `/setup/panel/run-virgin-reset` | — | ⭐ The **ONLY** allowed virgin-reset trigger — UI-visible by construction (shows panel + checkboxes + progress before deleting anything) |
| POST | `/setup/panel/wipe-keep-auth` | — | Synchronous wipe that KEEPS Adom + Claude tokens |
| POST | `/setup/screenshot-mode` | `{"enabled":B}` | Toggle per-step screenshot capture (default OFF) |
| GET | `/setup/screenshot-mode` | — | Whether per-step screenshot mode is on |
## Workspace Tabs
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/workspace/tabs` | — | List all workspace tabs |
| GET | `/workspace/tabs/find?name=X` | — | Find tab by name (404 if not found) |
| POST | `/workspace/tabs` | `{tab spec}` | Add a new tab |
| POST | `/workspace/tabs/activate` | `{tabId}` or `{name}` or `{panelId, tabIndex}` | Bring one tab to the front |
| POST | `/workspace/tabs/remove` | `{tabId}` or `{name}` or `{panelId, tabIndex}` | Close one tab (`/workspace/tabs/close` is the same) |
| POST | `/workspace/tabs/move` | `{tabId or name, targetPanelId}` | Move a tab to another pane |
| POST | `/workspace/swap` | `{panelA, panelB}` | Swap two panes |
| POST | `/workspace/split` | `{panelId, direction, position?, ratio?, panelType?, displayName?, initialState?}` | Split a pane; answers the new `panelId` |
| POST | `/workspace/resize` | `{splitId, ratio}` | Set a split's proportion (0.1 to 0.9) |
| POST | `/workspace/close-panel` | `{panelId}` | Close a pane and its tabs |
| GET | `/workspace/get` | (none) | The whole live layout tree: panes, splits (id and ratio), tabs |
The whole layout API is on the desktop control port (the same on Windows and Linux): drive it with
`curl` from the host or through Adom Bridge, no workspace needed. Each route is the twin of an
`adom-cli hydrogen workspace` verb (`get`, `active-tab`, `remove-tab`, `move-tab`, `swap`, `split`,
`resize`, `close-panel`) on the same live tree, and every answer's `_hints.adom_cli` names it.
**The VS Code pane holds the user's AI threads** (John 2026-11-15). A call that covers, hides,
replaces or removes it (closing its pane, removing or moving the VS Code tab, moving or activating
another tab in front of it, adding a tab to its pane by name) is allowed, but its answer carries
`_hints.vscode`: a strong warning and, in `undo`, the exact call that puts VS Code back. Read it,
and undo unless you had a very good reason. Hydrogen's own placement never does this: a new tab
with no pane named (the dock, `webview open-or-refresh`, `POST /workspace/tabs` without
`panelId`) opens in another pane, or, when VS Code's pane is the only one, in a new right-hand
split at half the width.
Example, from the host:
```bash
C=http://127.0.0.1:47084
curl -s $C/workspace/tabs # tabs with tabId, panelId, name
curl -s -X POST $C/workspace/split -d '{"panelId":"desktop-pane-left","direction":"horizontal","panelType":"adom/a1b2c3d4-0031-4000-a000-000000000031","displayName":"Notes","initialState":{"url":"about:blank"}}'
curl -s -X POST $C/workspace/tabs/move -d '{"name":"Wiki","targetPanelId":"<new pane id>"}'
curl -s -X POST $C/workspace/tabs/activate -d '{"name":"Wiki"}'
curl -s -X POST $C/workspace/tabs/remove -d '{"name":"Notes"}'
curl -s -X POST $C/workspace/close-panel -d '{"panelId":"<new pane id>"}'
```
## System
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/system/reboot-state` | | Always null on Linux: Hydrogen setup never needs a reboot here |
| POST | `/system/reboot` | | Not available on Linux: Hydrogen does not reboot this computer |
`/recording/native/*` answers that native recording is not available on Linux.
## App lifecycle & window
| Method | Path | Body | Description |
|---|---|---|---|
| POST | `/app/restart` | — | Restart the Hydrogen app (kills + respawns the binary) |
| POST | `/app/relaunch-frontend` | — | Relaunch the Hydrogen GUI (kill+respawn) while it is responsive |
| POST | `/window/foreground` | — | Bring the Hydrogen window to the foreground (unminimize + focus) |
The desktop's window manager may refuse to raise the window for `/window/foreground`.
## Diagnostics (`/test/*`)
Setup-cascade and state diagnostics. **Gated behind `HD_TEST_API_ENABLED=1`** (return 404 /
"test API disabled" otherwise). `GET /test/help` self-lists the whole cluster.
| Method | Path | Body | Description |
|---|---|---|---|
| GET | `/test/help` | — | Self-lists every `/test/*` endpoint |
| GET | `/test/window-tree` | | Not available on Linux |
| POST | `/test/click-uia` | | Not available on Linux |
| GET | `/test/setup-steps` | — | Raw setup-steps.json + derived summary (alias: `/test/install-steps`) |
| POST | `/test/reset-cascade` | — | Delete install-steps.json + emit setup-reset event |
| GET | `/test/probe-dialogs` | | Not available on Linux |
## Key Patterns
### container-exec
Runs as user `adom` inside the workspace. Use full paths (`/home/adom/`
not `~/`). Tilde doesn't expand through the exec chain.
```
POST /container-exec {"command":"ls /home/adom/project"}
```
### Re-run a setup step after completion
The trigger file poller STOPS when all steps are done. Re-run one step by id (or relaunch
Hydrogen to auto-run the cascade):
```
POST /setup/step/<id>
```
## Complete route index
> The index below lists the routes every platform's router carries. On Linux some of them answer
> that they are not available here; their `/_manifest` description says so.
<!-- BEGIN GENERATED ROUTE INDEX -->
Every route Hydrogen for Linux serves, 332 across 23 categories, grouped the way the
API Explorer groups them. Routes that do nothing on Linux are left out, as they are from
`/_manifest` and the API Explorer here. Generated from the same table `/_manifest` serves, so it
cannot drift from the code; `scripts/check-manifest-fresh.sh` fails the build if it does.
`/_manifest` remains the richer source at runtime: it carries each route's args, its
description, and a `safety` flag (`destructive` / `disruptive`) that this flat index does not.
**Read a route's safety from `/_manifest` before calling it, not from this list.**
**AI Accounts** (14)
- `POST /agents/apikey`
- `GET /agents/bar`
- `GET /agents/catalog`
- `POST /agents/install`
- `POST /agents/login`
- `POST /agents/login-input`
- `POST /agents/login-stop`
- `GET /agents/login-url`
- `POST /agents/logout`
- `POST /agents/present`
- `POST /agents/setup-done`
- `POST /agents/setup-reset`
- `GET /agents/setup-state`
- `GET /agents/status`
**AI Threads** (39)
- `GET /ai-threads`
- `POST /ai-threads/activate`
- `POST /ai-threads/answer`
- `POST /ai-threads/close`
- `GET /ai-threads/dom-debug`
- `POST /ai-threads/dom-event`
- `GET /ai-threads/dom-events`
- `POST /ai-threads/focus`
- `GET /ai-threads/history`
- `POST /ai-threads/hook-event`
- `POST /ai-threads/inject`
- `POST /ai-threads/inspect`
- `POST /ai-threads/install`
- `GET /ai-threads/install/log`
- `POST /ai-threads/issue-inject`
- `GET /ai-threads/issue-queue`
- `GET /ai-threads/names`
- `POST /ai-threads/new`
- `POST /ai-threads/new-tui`
- `POST /ai-threads/pick`
- `GET /ai-threads/prompts`
- `POST /ai-threads/rename`
- `POST /ai-threads/reorder`
- `POST /ai-threads/repo-link`
- `GET /ai-threads/repo-links`
- `POST /ai-threads/resume`
- `POST /ai-threads/run-prompt`
- `GET /ai-threads/run-prompt/status`
- `GET /ai-threads/settings`
- `POST /ai-threads/settings`
- `GET /ai-threads/tabs`
- `POST /ai-threads/tag`
- `GET /ai-threads/tags`
- `GET /ai-threads/tools`
- `POST /ai-threads/uninstall`
- `GET /ai-threads/wait`
- `POST /ai-threads/walk`
- `GET /ai-threads/walk-report`
- `GET /ai-threads/wiki-repos`
**Adom Bridge** (19)
- `GET /ab/direct-api`
- `GET /ab/discovery-file`
- `GET /ab/embedded`
- `GET /ab/health`
- `GET /ab/liveness-beacon`
- `GET /ab/permissions`
- `POST /ab/permissions/request`
- `POST /ab/permissions/revoke`
- `GET /ab/process`
- `GET /ab/relay`
- `GET /ab/settings`
- `POST /ab/settings`
- `POST /ab/show`
- `POST /ab/toast-ack`
- `POST /ab/verb`
- `GET /ab/workspace-direct`
- `POST /direct/command`
- `GET /direct/health`
- `GET /direct/status`
**Auth & User** (7)
- `GET /auth-token`
- `GET /auth/browser-status`
- `GET /auth/proxy`
- `POST /auth/proxy`
- `DELETE /user/avatar`
- `POST /user/avatar`
- `POST /user/refresh`
**Browser & Open** (11)
- `GET /browser-picker/last-open`
- `POST /browser-picker/opened`
- `DELETE /browser-picker/prefs`
- `GET /browser-picker/prefs`
- `PUT /browser-picker/prefs`
- `GET /browser-profiles`
- `POST /open-in-profile`
- `POST /open-url`
- `GET /webview-can-embed`
- `GET /webview-proxy`
- `GET /wiki-proxy`
**Claude** (46)
- `POST /claude-auth`
- `GET /claude/auth-check`
- `GET /claude/auth-page-state`
- `GET /claude/auth-status`
- `POST /claude/authorize-tab-enter`
- `POST /claude/clear-open-highlight`
- `POST /claude/cli-auth/code`
- `POST /claude/cli-auth/start`
- `GET /claude/contexts`
- `GET /claude/conversation-state`
- `GET /claude/conversations`
- `POST /claude/cross-eval`
- `GET /claude/detect-auth-failure`
- `POST /claude/detect-state`
- `POST /claude/ensure-open`
- `POST /claude/find-auth-button`
- `POST /claude/focus`
- `POST /claude/highlight-open-button`
- `POST /claude/inject`
- `POST /claude/inject-creds`
- `POST /claude/inject-message`
- `POST /claude/new-chat-and-send`
- `POST /claude/new-conversation`
- `POST /claude/open`
- `POST /claude/open-with-message`
- `POST /claude/remote-control`
- `POST /claude/sample-prompt`
- `GET /claude/sample-prompts`
- `POST /claude/sample-prompts/refresh`
- `POST /claude/send`
- `GET /claude/sessions`
- `POST /claude/start-auth`
- `GET /claude/status`
- `POST /claude/submit`
- `GET /claude/tabs`
- `POST /claude/tabs/activate`
- `POST /claude/tabs/close-all`
- `POST /claude/tabs/close-empty-groups`
- `POST /claude/tabs/close-untitled`
- `POST /claude/tabs/merge-groups`
- `POST /claude/trigger-auth`
- `POST /claude/type-and-submit`
- `POST /claude/wipe-creds`
- `POST /config-reset`
- `GET /oauth/callback`
- `POST /start-oauth-proxy`
**Container / Docker (legacy)** (15)
- `POST /container-delete`
- `POST /container-exec`
- `POST /container-pull-image`
- `POST /container-restart`
- `POST /container-start`
- `GET /container-stats`
- `GET /container-status`
- `POST /container-stop`
- `GET /container/disk`
- `GET /container/env`
- `GET /container/logs`
- `GET /container/ports`
- `POST /container/restart`
- `POST /image-delete`
- `POST /volume-delete`
**Dock** (6)
- `GET /dock/apps`
- `POST /dock/close`
- `POST /dock/launch`
- `POST /dock/refresh`
- `POST /dock/reset`
- `POST /dock/result`
**Editor State Machine (ESM)** (4)
- `POST /editor/audit-prompt`
- `POST /editor/bars`
- `POST /editor/normalize`
- `GET /editor/state`
**Eval & Automation** (17)
- `POST /ai-cursor/click`
- `POST /ai-cursor/hide`
- `POST /ai-cursor/move`
- `POST /cdp-eval`
- `POST /click`
- `GET /devtools`
- `POST /devtools`
- `POST /eval`
- `POST /eval-in`
- `POST /files/inject`
- `POST /iframe-eval`
- `POST /mouse-click`
- `POST /query`
- `POST /reload-vscode`
- `GET /targets`
- `POST /vscode/command`
- `POST /vscode/hide-activity-items`
**Health & Build** (17)
- `GET /_manifest`
- `POST /app/relaunch-frontend`
- `POST /app/restart`
- `GET /buildinfo`
- `GET /cdp-info`
- `GET /console`
- `GET /diagnostics`
- `GET /diagnostics/all`
- `GET /doctor`
- `POST /doctor`
- `GET /health`
- `GET /logs/tail`
- `GET /ports`
- `GET /ports/all`
- `POST /ports/check`
- `POST /ports/set`
- `POST /report/problem`
**Hydrogen Browser Window** (11)
- `GET /hbw/chrome`
- `POST /hbw/chrome-toggle`
- `POST /hbw/close`
- `POST /hbw/nav`
- `POST /hbw/open`
- `GET /hbw/speed`
- `POST /hbw/speed`
- `GET /hbw/state`
- `GET /hbw/tip`
- `GET /hbw/tip-state`
- `POST /hbw/tooltip`
**Other** (2)
- `POST /proxy/restart`
- `POST /telemetry/webview-gpu`
**Permissions** (3)
- `POST /permission/dismiss`
- `POST /permission/request`
- `POST /permission/resolve`
**Screenshots & Recording** (13)
- `POST /annotate`
- `GET /annotate/hotkey`
- `POST /annotate/hotkey`
- `GET /capture/availability`
- `GET /capture/viewport`
- `GET /recording/native/capabilities`
- `POST /recording/native/reset`
- `GET /recording/native/sources`
- `POST /recording/native/start`
- `GET /recording/native/status`
- `POST /recording/native/stop`
- `POST /screenshot`
- `POST /shot`
**Settings** (2)
- `GET /settings/external-changes`
- `POST /settings/rebroadcast`
**Setup Cascade** (25)
- `GET /setup-status`
- `POST /setup/countdown`
- `GET /setup/flags`
- `POST /setup/flags`
- `POST /setup/force-close`
- `POST /setup/panel/hide`
- `POST /setup/panel/run-virgin-reset`
- `POST /setup/panel/set-virgin-options`
- `POST /setup/panel/show`
- `POST /setup/panel/show-virgin-reset`
- `POST /setup/panel/virgin/hide`
- `POST /setup/panel/virgin/show`
- `POST /setup/panel/wipe-keep-auth`
- `POST /setup/run-all`
- `POST /setup/run-step`
- `GET /setup/screenshot-mode`
- `POST /setup/screenshot-mode`
- `GET /setup/state`
- `POST /setup/state`
- `POST /setup/step`
- `DELETE /setup/trigger`
- `GET /setup/trigger`
- `POST /setup/virgin-reset`
- `POST /virgin-reset`
- `GET /virgin-reset-progress`
**System** (6)
- `GET /adom-port-hints`
- `POST /adom-port-hints`
- `GET /gpu`
- `POST /gpu`
- `GET /system/nonce`
- `GET /system/reboot-state`
**Test & Dev** (10)
- `POST /debug/show-auth-caption`
- `POST /debug/zorder-probe`
- `POST /dev/emit-event`
- `POST /test/dump-state`
- `POST /test/focus`
- `GET /test/help`
- `GET /test/install-steps`
- `POST /test/reset-cascade`
- `POST /test/screenshot-hd-window`
- `GET /test/setup-steps`
**UI & Windows** (23)
- `POST /api-explorer/open`
- `POST /demo/run`
- `GET /dock-launch.html`
- `GET /favicon.ico`
- `GET /orbital-loader.html`
- `POST /panel-webview/fullscreen`
- `GET /panes/memory`
- `POST /panes/reload-errors`
- `POST /ui/_bus-pong`
- `POST /ui/_result`
- `POST /ui/_sync`
- `GET /ui/actions`
- `POST /ui/invoke`
- `POST /ui/toast`
- `POST /ui/toast-ack`
- `GET /webview/frames`
- `POST /webview/link-intercepted`
- `GET /webview/port-check`
- `GET /welcome.html`
- `GET /widget-launch.html`
- `POST /window/close`
- `POST /window/foreground`
- `POST /window/show`
**Wake & Repair** (5)
- `POST /wake/config`
- `POST /wake/preview`
- `POST /wake/preview/hide`
- `POST /wake/simulate`
- `GET /wake/status`
**Widgets** (8)
- `GET /widgets`
- `POST /widgets/card`
- `POST /widgets/close`
- `POST /widgets/menu`
- `POST /widgets/navigate`
- `POST /widgets/open`
- `POST /widgets/refresh`
- `GET /widgets/status`
**Workspace & Updates** (29)
- `POST /migration/approved`
- `POST /migration/dismissed`
- `POST /updater/check`
- `POST /updater/install`
- `POST /updater/show-banner`
- `GET /updater/status`
- `POST /workspace/apply-updates`
- `POST /workspace/check-updates`
- `POST /workspace/exec`
- `GET /workspace/health`
- `POST /workspace/migration/approve`
- `POST /workspace/migration/decline`
- `GET /workspace/stats`
- `GET /workspace/tabs`
- `POST /workspace/tabs`
- `GET /workspace/tabs/`
- `POST /workspace/tabs/`
- `GET /workspace/tabs/find`
- `POST /workspace/vscode-settings`
- `POST /workspaces/apply`
- `GET /workspaces/benches`
- `POST /workspaces/demo`
- `POST /workspaces/menu`
- `POST /workspaces/offer`
- `POST /workspaces/refresh`
- `POST /workspaces/reset`
- `POST /workspaces/save`
- `GET /workspaces/status`
- `POST /workspaces/unload`
**Workspace control** (~30 routes, a SEPARATE server on the proxy port, absent from `/_manifest`)
Reached at `/api/workspaces/editor/<owner>/<repo>/current/...`, which the handler strips
before matching. A bare `GET /tabs` on the proxy 404s; that is correct, not a fault.
- `/tabs`
- `/tabs/find`
- `/tabs/alert`
- `/active-tab`
- `/splits`
- `/swaps`
- `/moves`
- `/nav`
- `/reload`
- `/window-mode`
- `/caption`
- `/recording`
- `/screenshot`
- `/audio`
- `/sharing`
- `/notification`
- `/probe`
<!-- END GENERATED ROUTE INDEX -->