The Headless Deskman

@@ -0,0 +1,74 @@+# headview++**A browser desktop for a headless Adom container.**++`headview` gives a headless container a real GUI you can open in any browser. It+starts a virtual X display in the container, scrapes it with VNC, bridges that to+WebSocket with noVNC, and maps a `*.adom.cloud` port so **Cloudflare serves the+page — the container hosts it itself.** No SSH tunnel, no local VNC viewer, no X+server on your machine. Open the URL on a laptop, a phone, or as a Hydrogen+webview tab.++![KiCad running in a headless container, viewed in a browser via headview](docs/screenshot-desktop.png)++## Why not `ssh -Y`?++X11 forwarding does **not** work through the `adom.cloud` SSH gateway: the gateway+relays your connection into the container, so the X11 channel never reaches the+container's `sshd` (`DISPLAY` comes back empty even with `X11Forwarding yes` and+`xauth` installed). `headview` sidesteps that entirely by serving over+HTTP/WebSocket, which the gateway and Cloudflare pass fine.++## Install++```bash+adom-wiki pkg install barrett-land/headview+```++## Quick start++```bash+# inside the target container:+headview up                     # start the desktop, map a port, print the URL+headview up --app "kicad"       # ...with KiCad already open on it+headview url                    # print the URL again+headview status                 # what's running + URL + password+headview down                   # stop everything and remove the port mapping+```++`headview up` prints a URL like `https://desktop-<id>.adom.cloud/vnc.html` and a+generated VNC password. Open it anywhere. To launch more apps onto the desktop:++```bash+DISPLAY=:99 pcbnew &+DISPLAY=:99 xterm &+```++Open it as a Hydrogen tab (from a Hydrogen workspace terminal): `headview open`.++## The stack++```+Xvfb (:99)  →  fluxbox  →  x11vnc (localhost:5900)  →  noVNC/websockify (:6080)  →  port-mapping  →  https://desktop-<id>.adom.cloud+```++## Notes & limits++- **Software rendering only.** Xvfb has no GPU, so 2D GUIs are great but+  OpenGL/3D views (KiCad 3D viewer, Blender viewport) won't render well.+- **Security.** The VNC server binds `localhost`; the public face is the noVNC+  HTTPS URL, protected by the generated VNC password (`headview password`).+- Run `headview` **inside** the target container — it auto-detects the container+  slug via `adom-cli` and maps its own port.++## Commands++| Command | What it does |+|---|---|+| `headview up` | start desktop, map port, print URL (`--display`, `--geometry`, `--vnc-port`, `--web-port`, `--prefix`, `--app`, `--no-password`) |+| `headview down` | stop everything, remove the mapping (`--keep-mapping` to keep it) |+| `headview status` | show running processes, URL, password |+| `headview url` | print the desktop URL |+| `headview password` | print the VNC password |+| `headview open` | open as a Hydrogen webview tab (needs a Hydrogen terminal) |+| `headview install` | (re)install the skill from the wiki |

@@ -0,0 +1,65 @@+{+  "slug": "headview",+  "title": "Headview",+  "type": "app",+  "version": "0.1.0",+  "bundled": true,+  "description": "A browser desktop for a headless Adom container. Runs Xvfb+fluxbox+x11vnc+noVNC inside the container and maps a *.adom.cloud port so any browser (or a Hydrogen webview tab) shows the container's GUI — no SSH tunnel, no local viewer. The container hosts the page itself.",+  "tags": [+    "cli",+    "desktop",+    "vnc",+    "novnc",+    "xvfb",+    "container",+    "gui",+    "remote-desktop"+  ],+  "dependencies": {},+  "discovery_triggers": [+    "headless desktop",+    "container desktop",+    "view a GUI from my container",+    "see kicad in a browser",+    "run a GUI app in the container",+    "novnc desktop",+    "remote desktop for a container",+    "x11 forwarding doesn't work",+    "browser desktop for headless container"+  ],+  "discovery_pitch": "When a headless container needs a real GUI you can open in a browser (X11 forwarding is blocked by the adom.cloud gateway), reach for headview.",+  "sample_prompts": [+    {+      "label": "See a GUI",+      "prompt": "I want to see a GUI app running in my headless container from my laptop"+    },+    {+      "label": "Container desktop",+      "prompt": "give my headless container a desktop I can open in a browser"+    },+    {+      "label": "KiCad in browser",+      "prompt": "open KiCad running in my container in a browser tab"+    }+  ],+  "metadata": {+    "activate": {+      "kind": "skill",+      "skill": "headview",+      "requires": [],+      "verbPrefixes": []+    }+  },+  "scripts": {+    "install": "./install.sh",+    "uninstall": "./uninstall.sh"+  },+  "hero": {+    "type": "image",+    "path": "docs/hero.png"+  },+  "author": {+    "name": "barrett-land",+    "email": "[email protected]"+  }+}\ No newline at end of file