@mmmbuto/nexuscrew 0.9.0 → 0.9.2

package/lib/server.js

@@ -532,6 +532,14 @@ function createServer(opts = {}) {
   }
 
   const app = express();
+  // CSP frame-ancestors (P0 sicurezza 2026-08-16, rimedio 4 del report): la
+  // pagina dell'app non deve poter essere incorporata in un iframe altrui —
+  // clickjacking sul control plane. Ortogonale alla porta pannello: quello
+  // difende CHI E' NEL FRAME, questo difende l'app dall'ESSERE il frame.
+  app.use((_req, res, next) => {
+    res.setHeader('Content-Security-Policy', "frame-ancestors 'none'");
+    next();
+  });
   reverseSlotListeners = createReverseSlotListeners({
     app, diagnostics, createServerImpl: cfg.reverseSlotCreateServerImpl,
     // `routeUpgrade` e' hoisted: qui si cattura solo il riferimento, la
@@ -541,7 +549,19 @@ function createServer(opts = {}) {
   const distDir = path.join(__dirname, '..', 'frontend', 'dist');
   // no-store on everything (HTML+assets+API): this is a local, token-adjacent tool.
   app.use((_req, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
-  app.use('/pair', publicPeeringRoutes({ cfg, nodesPath }));
+  // Il panelServer nasce piu' avanti nella stessa funzione: il pairing legge
+  // la sua porta VIVA tramite questo ref, risolto a ogni join (pattern dello
+  // stesso tipo dell'hoisting di routeUpgrade qui sopra).
+  const panelListenerRef = { server: null };
+  app.use('/pair', publicPeeringRoutes({
+    cfg, nodesPath,
+    panelPort: () => {
+      const srv = panelListenerRef.server;
+      if (!srv || !srv.listening) return null;
+      const addr = srv.address();
+      return addr && Number.isInteger(addr.port) && addr.port > 0 ? addr.port : null;
+    },
+  }));
   // VL micro-device nodes use a separate, scoped credential surface.  These
   // routes never accept the NexusCrew UI bearer and expose only pair, poll and
   // self-unpair.  Operator management remains behind /api + federation ACL.
@@ -608,6 +628,46 @@ function createServer(opts = {}) {
       cell: entry.cell, reason: entry.reason, state: entry.outcome,
     }),
   }));
+  // Porta pannello dedicata (P0 sicurezza 2026-08-16): un iframe
+  // same-origin senza sandbox legge il localStorage del padre — il JS di un
+  // pannello ostile puo' prendersi il token e agire come l'operatore. La
+  // porta fa parte dell'origin: spostando SOLO il consumo (ticket in query,
+  // cookie di visione) su una porta sua, il browser vede un'origin diversa e
+  // non c'e' piu' nulla da rubare. Nessuna API di controllo qui, nessun
+  // Bearer verificato: l'emissione del ticket resta sopra, dietro
+  // requireToken — e' l'unica operazione che richiede provare CHI chiede.
+  const panelApp = express();
+  panelApp.use('/panel', panelAuth.consumeMiddleware, createPanelProxy({
+    resolveCellPanel,
+    log: (entry) => diagnostics.record('panel-proxy', 'info', entry.outcome, {
+      cell: entry.cell, reason: entry.reason, state: entry.outcome,
+    }),
+  }));
+  // Qualunque altra cosa (niente /api, niente SPA): 404 secco. Questa porta
+  // non ha nient'altro da offrire, e non deve mai imparare a offrirlo per
+  // errore — un catch-all che rispondesse con l'app sarebbe esattamente il
+  // difetto che questa porta esiste per chiudere.
+  panelApp.use((_req, res) => res.status(404).json({ error: 'not found' }));
+  const panelServer = http.createServer(panelApp);
+  const panelServerV6 = http.createServer(panelApp);
+  panelListenerRef.server = panelServer;
+  function routePanelUpgrade(req, socket, head) {
+    let pathname;
+    try { pathname = new URL(req.url, 'http://127.0.0.1').pathname; }
+    catch (_) { try { socket.destroy(); } catch (_e) {} return; }
+    if (!pathname.startsWith('/panel/')) { try { socket.destroy(); } catch (_) {} return; }
+    handlePanelUpgrade({
+      req, socket, head, resolveCellPanel,
+      verifyToken: (t) => verify(tokenHolder.value, t),
+      authorize: panelAuth.authorizeUpgrade,
+      log: (entry) => diagnostics.record('panel-proxy', 'info', entry.outcome, {
+        cell: entry.cell, reason: entry.reason, state: entry.outcome,
+      }),
+    });
+  }
+  panelServer.on('upgrade', routePanelUpgrade);
+  panelServerV6.on('upgrade', routePanelUpgrade);
+  panelServer.on('close', () => { try { panelServerV6.close(); } catch (_) {} });
   // L'ingresso ai pannelli REMOTI ha la stessa malattia dell'iframe locale: la
   // via federata /api/route/<nodi>/_/panel/... sta per finire sotto requireToken
   // e una navigazione del browser non porta header. QUI il ticket non si può
@@ -734,11 +794,26 @@ function createServer(opts = {}) {
       res.json(await setSessionVisibility(cfg.tmuxBin, name, req.body?.technical === true));
     } catch (e) { res.status(e.status || 500).json({ error: String(e.message || e) }); }
   });
+  // Mappa nome-nodo -> porta pannello inoltrata sul NOSTRO loopback (coppia
+  // panel negoziata nel pairing). E' la fonte con cui il frontend mette il
+  // frame di una cella REMOTA su un'origin diversa: la lettura e' questa, non
+  // /api/nodes, perche' qui non c'e' nessun probe di health federato — la
+  // mappa costa quanto la lettura dello store. Un nodo assente dalla mappa e
+  // un peer accoppiato prima di questa negoziazione: via storica.
+  const nodePanelPorts = () => {
+    const st = nodesStore.loadStore(nodesPath);
+    const out = {};
+    if (st) for (const n of st.nodes) {
+      if (n.panelLocalPort !== undefined) out[n.name] = n.panelLocalPort;
+    }
+    return out;
+  };
   api.get('/config', (_req, res) => res.json({
     readonlyDefault: cfg.readonlyDefault, version: VERSION, uiVersion: uiBuildVersion(distDir),
-    bind: cfg.bind, port: cfg.port,
+    bind: cfg.bind, port: cfg.port, panelPort: cfg.panelPort,
     protectSharedTmuxServer: cfg.protectSharedTmuxServer !== false,
     instanceId: (nodesStore.loadStore(nodesPath) || {}).nodeId || null,
+    nodePanelPorts: nodePanelPorts(),
     presets: ['shell', 'claude', 'codex-vl', 'pi', ...Object.keys(cfg.sessionPresets || {})],
   }));
   api.use('/files', filesRoutes({
@@ -859,8 +934,9 @@ function createServer(opts = {}) {
     readonly: proxyReadonly,
   }));
   // Cella ospite Live (contratto rev6 §2): hostCell unico per nodo con CAS. Lo store
-  // vive accanto al token (stessa dir isolata nei test); le route sono local-only e
-  // il proxy nega /api/live-host via /node (federazione default-deny).
+  // vive accanto al token (stessa dir isolata nei test); il proxy nega /api/live-host
+  // via /node (local-only), ma la via /api/route la instrada (0.9.1) dietro un
+  // permesso per-peer negato di default (liveHostAccess, v. lib/proxy/federation.js).
   // Fetta 3: il ponte risolve il puntamento all'avvio di una Live (POST /bridge
   // nello stesso gruppo, stessa auth, stesso local-only). Isolabile da cfg
   // (rev5 MC0): spento non crea connessioni e la Live resta standard.
@@ -1023,6 +1099,10 @@ function createServer(opts = {}) {
     watcher.close(); previews.close(); eventsHub.closeAll(); updater.close();
     for (const timer of reverseWatchers.values()) clearInterval(timer);
     reverseWatchers.clear(); rotatableReverse.clear(); void reverseSlotListeners?.closeAll();
+    // Il pannello non sopravvive al control plane: senza requireToken sopra,
+    // non c'e' un secondo lifecycle da tenere in vita da soli. panelServerV6
+    // si chiude a cascata dal listener 'close' gia' registrato su panelServer.
+    try { panelServer.close(); } catch (_) {}
   });
   // noServer: gestiamo l'upgrade a mano per instradare /ws (locale) e /node/*
   // (proxy). Il WS locale resta identico; il proxy WS applica gli STESSI check
@@ -1143,11 +1223,14 @@ function createServer(opts = {}) {
     fleetP.then((fleet) => (typeof fleet.close === 'function' ? fleet.close() : null)).catch(() => {});
   });
 
-  return { app, server, wss, cfg, token: tokenHolder.value, tokenStore, watcher, fleetP, updater, diagnostics };
+  return {
+    app, server, wss, cfg, token: tokenHolder.value, tokenStore, watcher, fleetP, updater, diagnostics,
+    panelApp, panelServer, panelServerV6,
+  };
 }
 
 function start(opts = {}) {
-  const { server, cfg } = createServer({ ...opts, cellLeaseEnabled: true });
+  const { server, cfg, panelServer, panelServerV6 } = createServer({ ...opts, cellLeaseEnabled: true });
   const log = opts.log || console.log;
   const requestedPort = cfg.port;
   const nodesPath = opts.nodesPath || nodesStore.defaultNodesPath(cfg.home || os.homedir());
@@ -1156,12 +1239,51 @@ function start(opts = {}) {
     if (typeof opts.onListenError === 'function') return opts.onListenError(error);
     throw error;
   };
+  // Porta pannello (P0 sicurezza 2026-08-16): scelta libera con lo STESSO
+  // meccanismo di fallback della principale, ma piu' leggero — nessun peer
+  // dipende ancora da un valore stabile persistito (a differenza di cfg.port,
+  // che i tunnel pairati referenziano), quindi niente scrittura su
+  // config.json: il frontend la scopre da /api/config a ogni avvio. Un
+  // fallimento qui non deve MAI abbattere il control plane: e' un log, non
+  // un throw — il pannello resta un'estensione, non un requisito di avvio.
+  const startPanelV6 = () => {
+    panelServerV6.once('error', (error) => {
+      log(`panel: IPv6 loopback listener not available (${(error && error.code) || error}); IPv4 still serves the panel.`);
+    });
+    panelServerV6.listen(cfg.panelPort, '::1');
+  };
+  const startPanelServer = () => {
+    const requestedPanelPort = cfg.panelPort;
+    const tryPanelFallback = (candidate, remaining) => {
+      panelServer.once('error', (error) => {
+        if (error && error.code === 'EADDRINUSE' && remaining > 1) {
+          tryPanelFallback(candidate >= 65535 ? 41821 : candidate + 1, remaining - 1);
+          return;
+        }
+        log(`panel: preferred port ${requestedPanelPort} busy and no fallback available (${(error && error.code) || error}); panel disabled this run.`);
+      });
+      panelServer.listen(candidate, cfg.bind, () => {
+        cfg.panelPort = panelServer.address().port;
+        log(`panel port ${requestedPanelPort} busy; selected ${cfg.panelPort}`);
+        startPanelV6();
+      });
+    };
+    panelServer.once('error', (error) => {
+      if (error && error.code === 'EADDRINUSE') { tryPanelFallback(requestedPanelPort >= 65535 ? 41821 : requestedPanelPort + 1, 200); return; }
+      log(`panel: failed to start (${(error && error.code) || error}); panel disabled this run.`);
+    });
+    panelServer.listen(requestedPanelPort, cfg.bind, () => {
+      cfg.panelPort = panelServer.address().port;
+      startPanelV6();
+    });
+  };
   const onListening = () => {
     cfg.port = server.address().port;
     // Il token NON si stampa allo startup: finirebbe nei log del servizio
     // (journalctl/logfile). L'apertura autenticata passa da `nexuscrew show`.
     log(`nexuscrew on http://${cfg.bind}:${cfg.port}  (open with \`nexuscrew show\`)`);
     log('localhost-only — reach it via a user-controlled SSH or VPN channel.');
+    startPanelServer();
   };
   const persistFallback = () => {
     const selected = server.address().port;

package/lib/settings/pairing-coordinator.js

@@ -87,6 +87,7 @@ function createPairHandler(deps) {
 
     let provisionalPort = null;
     let portReservation = null;
+    let panelPortReservation = null;
     let rollbackCredential = null;
     let created = false;
     let rolledBack = false;
@@ -98,6 +99,10 @@ function createPairHandler(deps) {
         try { await portReservation.release(); } catch (_) { /* best-effort */ }
         portReservation = null;
       }
+      if (panelPortReservation) {
+        try { await panelPortReservation.release(); } catch (_) { /* best-effort */ }
+        panelPortReservation = null;
+      }
       if (rollbackCredential && provisionalPort) {
         try {
           await pairFetch(`http://127.0.0.1:${provisionalPort}/pair/cancel`, {
@@ -296,6 +301,26 @@ function createPairHandler(deps) {
       // --- tunnel-final: connessione privata, solo -L -------------------------
       // reversePort resta negoziata per un futuro Share opt-in, ma il builder
       // non emette -R finche' shared non diventa true.
+      //
+      // Porta pannello del peer (P0 stessa-origin, meta' remota): se il peer
+      // l'ha annunciata nel join, si riserva una controparte locale e la
+      // coppia entra nel record — il supervisor finale inoltrera' entrambe.
+      // Nessuna porta disponibile NON fa fallire il pairing: il pannello e
+      // un'estensione, il legame viene prima. Stesso patto di publicKey: un
+      // peer piu' vecchio non annuncia e si accoppia esattamente come prima.
+      const peerPanelPort = nodesStore.isPort(joined.panelPort) ? joined.panelPort : null;
+      let panelLocalPort = null;
+      if (peerPanelPort) {
+        try {
+          panelPortReservation = await nodesCmds.reserveLocalPort(
+            nodesStore.loadStoreStrict(nodesPath),
+            { createServerImpl: seams.createPanelPortServer || seams.createPortServer },
+          );
+          panelLocalPort = panelPortReservation.port;
+        } catch (_) {
+          panelPortReservation = null; panelLocalPort = null; // fail-open dichiarato: via storica
+        }
+      }
       st = nodesStore.loadStoreStrict(nodesPath);
       if (joinedPool && st.schemaVersion < nodesStore.SCHEMA_VERSION) {
         // This device is a client of the hub-owned pool.  It persists the
@@ -313,8 +338,15 @@ function createPairHandler(deps) {
           : {}),
         ...(joinedPool ? { reversePool: joinedPool } : {}),
         ...(joinedRoles ? { roles: joinedRoles, rolesKnown: true } : {}),
+        ...(panelLocalPort ? { panelLocalPort, panelRemotePort: peerPanelPort } : {}),
       });
       nodesStore.atomicWriteStore(nodesPath, st);
+      // La riserva della porta pannello ha protetto la scelta fino alla
+      // scrittura: come la porta di controllo, si rilascia prima dello spawn.
+      if (panelPortReservation) {
+        try { await panelPortReservation.release(); } catch (_) { /* best-effort */ }
+        panelPortReservation = null;
+      }
       nodesTunnel.stopTunnel({ home, name: b.name });
       const finalStart = nodesTunnel.startForward({
         home, node: nodesStore.getNode(st, b.name), localAppPort: runtimePort(),

package/lib/settings/public-peering-routes.js

@@ -28,6 +28,12 @@ function publicPeeringRoutes(deps = {}) {
   const invitesPath = cfg.invitesPath || peering.defaultInvitesPath(home);
   const pendingPath = cfg.pendingPairingsPath || peering.defaultPendingPath(home);
   const reversePoolLedgerPath = deps.reversePoolLedgerPath || cfg.reversePoolLedgerPath || reversePool.defaultLedgerPath(home);
+  // Porta pannello di QUESTA installazione, letta al momento del join: non
+  // cfg.panelPort (che resta al valore richiesto anche quando il listener non
+  // e' mai partito), ma la porta su cui il panelServer ascolta ADESSO. Null
+  // quando il pannello e' spento per questo run: meglio il silenzio che far
+  // inoltrare al client una porta che nessuno ascolta.
+  const panelPortLive = typeof deps.panelPort === 'function' ? deps.panelPort : () => null;
   // La pubblica di questa installazione, per il passo 1 del modello di
   // autorita'. Si legge PIGRAMENTE e non all'avvio del router: un errore sul
   // file di chiave non deve impedire di montare le route di pairing — il passo
@@ -170,13 +176,19 @@ function publicPeeringRoutes(deps = {}) {
         return res.status(410).json({ error: 'invito scaduto o gia usato' });
       }
       const mia = localPublicKey();
+      const pannello = panelPortLive();
       res.json({ paired: true, instanceId: poolStore.nodeId, reversePort,
         reversePool: { base: assignedPool.base, slots: assignedPool.slots.map((slot) => slot.port) },
         credential, roles: readRoles(configPath),
         // Lo scambio e' simmetrico e avviene QUI, dentro l'atto che consuma
         // l'invito monouso: e' il solo momento in cui l'operatore ha deciso,
         // su entrambe le macchine, che questi due nodi si conoscono.
-        ...(mia ? { publicKey: mia } : {}) });
+        ...(mia ? { publicKey: mia } : {}),
+        // Stesso patto della pubblica: la porta pannello si annuncia nel
+        // join, e un peer piu' vecchio che non la capisce si accoppia come
+        // sempre. Il campo assente non e' un errore, e' una versione (o un
+        // pannello spento per questo run).
+        ...(pannello ? { panelPort: pannello } : {}) });
     } catch (e) {
       if (credential) try { peering.consumePending({ pendingPath, credential, now }); } catch (_) {}
       res.status(e.status || 500).json({ error: String(e.message || e), ...(e.code ? { code: e.code } : {}) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/aidesktop/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: aidesktop
+description: Use when a user wants to give a cell a web panel via panelUrl, asks why a panel URL or panel request was rejected, wants to build the AI Desktop container recipe for an isolated browser and desktop, or needs to connect a Playwright MCP client to that desktop's Chromium through its CDP relay.
+---
+
+# AI Desktop
+
+A desktop you can watch and a browser you can drive are two faces of the same
+container: watching it is the **panel**, driving it is the **CDP relay** a
+Playwright MCP client attaches to. This skill covers both together, plus the
+recipe that builds the container itself.
+
+## The panel
+
+`panelUrl` is a **property of the cell** (or its engine, as a default for
+every cell using it) — a sibling of `engine` and `cwd`, not a command and not
+something the cell runs. The app's cell/engine editor has a `panelUrl` field
+for this; do not write the URL into the command field, which makes the cell
+try to execute it as a program and fails to start, while no panel button
+appears either, since `panelUrl` was never actually set.
+
+The value must be an `http:`/`https:` URL pointing at **loopback** —
+`127.0.0.1`, `[::1]`, or `localhost`. Anything else is rejected when the
+definition is read, and the cell keeps working, just without a panel button.
+**A container's own address is not loopback** — publish its port to
+`127.0.0.1` on the host that runs the node, and point `panelUrl` there. This
+is not a nitpick: the forwarder resolves *which cell*, never *where to
+connect*, so allowing a non-loopback destination would turn it into a way to
+reach any address the node can reach. See
+[The cell panel](../../docs/CELL_PANEL.md) for the full explanation and the
+worked example.
+
+### Origin separation (0.9.1)
+
+The panel used to be served from the same origin as the control plane, which
+meant a compromised or hostile page mounted in the panel iframe could, in
+principle, read the operator's token straight out of the app's own
+`localStorage`. As of 0.9.1, the panel is served from a **second loopback
+port** — the browser's Same-Origin Policy treats a different port as a
+different origin, so a document in that frame has nothing of the control
+plane's to read or write. The app also sends
+`Content-Security-Policy: frame-ancestors` on its own page, which is a
+separate, orthogonal protection: it stops the app itself from being embedded
+as someone else's iframe.
+
+This covers **remote** cells too, not just local ones. Two paired nodes
+negotiate a second port pair the same way they already negotiate the control
+plane's own tunnel: when the hub side has a panel server running, it
+announces its panel port at join time, the joining side reserves a local port
+for it, and the supervisor forwards both destinations over the same SSH
+connection — one `-L` for control, one for the panel, never sharing a port.
+`GET /api/config` exposes the result as `nodePanelPorts` (node name → the
+locally forwarded port), and the app resolves the right one per cell from its
+route before ever opening the frame.
+
+A node with no port pair on record — paired **before** this existed, or
+paired since but with the local port reservation having failed at the time
+(pairing still succeeds; the port pair is treated as an extension, never a
+reason to fail the bond) — is not treated as an error either way: its cells
+fall back to the old federated path (same origin as the control plane)
+exactly as before, and a cell never borrows another node's port to paper over
+the gap — the absence stays visible as the old behavior, not a silent, wrong
+origin. The pair is only established at pairing time, not by reconnecting an
+existing tunnel; re-pair the node to pick one up.
+
+None of this changes how a request actually gets into the frame: an
+authenticated call asks for a one-use ticket bound to one cell, the frame's
+first request spends it and receives a viewing cookie scoped to that cell's
+panel path, and the app's own token never reaches the frame. See
+[How the browser gets in](../../docs/CELL_PANEL.md#how-the-browser-gets-in)
+for the full mechanism — it is unchanged by the port move, only relocated.
+
+### Panels on another node
+
+Opening a panel that lives on a paired node needs that node's permission,
+**granted there, never by the requester**:
+
+```bash
+nexuscrew nodes panel <node> on
+```
+
+Denied by default. Without it, the rejection names itself —
+`panel-not-granted` — instead of leaving a blank rectangle to debug.
+
+## The Docker recipe
+
+**This repository ships the recipe, not an image.** The base,
+`lscr.io/linuxserver/webtop`, is GPL-3.0; a `FROM` line pointing at its public
+source is a recipe, not a distributed derivative, and the only thing this
+project actually owns is the two added lines below and their reasons. It also
+means no registry to host, nothing to keep patched on your behalf, and a
+recipe you can read before you run it.
+
+Build it yourself from [`docker/`](docker/):
+
+```bash
+cd <skill-dir>/docker
+cp docker-compose.example.yml docker-compose.yml
+# create ./.gui_password yourself — see the comments in the compose file
+docker compose up -d --build
+```
+
+First start creates an **empty** browser profile: no logins, no history,
+nothing carried over. The example compose ships no branding and no
+pre-populated `/config` — you get a bare webtop desktop plus the two
+additions below.
+
+### The two additions, and why each exists
+
+- **`socat`** — modern Chrome ignores `--remote-debugging-address` and binds
+  its DevTools/CDP port to `127.0.0.1` *inside* the container, so a Docker
+  port mapping alone never reaches it. `socat` relays
+  `0.0.0.0:9223 -> 127.0.0.1:9222` inside the container's own network
+  namespace; the published host port still only opens on `127.0.0.1`, so the
+  loopback-only rule is unchanged — nothing new is exposed, only bridged.
+- **the init script** also clears `Singleton{Lock,Cookie,Socket}` files an
+  unclean shutdown leaves behind, which otherwise stop Chromium from starting
+  again with no visible error.
+
+Notably absent: anything that tries to sandbox the browser. That is the next
+section, and it is the part worth reading before you adapt this recipe.
+
+### Where the boundary is
+
+**The browser in this container runs with `--no-sandbox`, and this recipe
+keeps it that way.** That is a trade, made deliberately, and you should
+understand it before deciding whether it fits your situation.
+
+The base image launches Chromium through `/usr/local/bin/wrapped-chromium`,
+which hardcodes the flag:
+
+```
+${BIN} --password-store=basic --no-sandbox --test-type "$@"
+```
+
+Installing Chromium's setuid helper does not change this, and overriding the
+wrapper to drop the flag does not produce a sandbox either. Measured inside a
+running container, launching the browser without it aborts:
+
+```
+The setuid sandbox is not running as root. Common causes:
+  * A parent process set prctl(PR_SET_NO_NEW_PRIVS, ...)
+Failed to move to new namespace: PID namespaces supported,
+Network namespace supported, but failed: errno = Operation not permitted
+```
+
+Both routes are closed, and for opposite reasons. The **setuid** sandbox needs
+its helper to elevate, which `no-new-privileges` exists to prevent. The
+**namespace** sandbox needs unprivileged user namespaces, which the container
+denies. Opening either one means handing the container `CAP_SYS_ADMIN` or
+`seccomp=unconfined`.
+
+That is the trade: **you would weaken the boundary that is actually holding in
+order to build one inside it.** For a desktop reachable only over loopback,
+the container is the stronger of the two — so the recipe keeps the container
+hard and accepts the browser soft. `no-new-privileges` stays on.
+
+**What this costs you, stated plainly:** a renderer exploit lands in the
+container. Everything the browser can reach is in the blast radius — its
+profile, its logged-in sessions, and anything you mount. Mount as little as
+possible, keep the published ports on loopback, and do not treat this desktop
+as isolation between *sites*: it is isolation between the desktop and the
+host.
+
+**If your situation differs** — an untrusted desktop, or a host where the
+container boundary matters less than the browser one — the inverse trade is
+legitimate: grant `seccomp=unconfined`, override the wrapper, and verify you
+actually got a sandbox rather than assuming it. Check the running process, not
+the launch log:
+
+- open `chrome://sandbox` inside the desktop and read what it reports, or
+- confirm the zygote no longer carries `--no-sandbox` (`ps -eo args | grep zygote`).
+
+Until one of those confirms it, assume the browser is unsandboxed — which,
+with this recipe as shipped, it is.
+### Commanding the browser
+
+The relay's published port, `127.0.0.1:9222` on the host, is the CDP
+endpoint a Playwright MCP client attaches to — for example:
+
+```bash
+playwright-mcp --cdp-endpoint http://127.0.0.1:9222
+```
+
+Register that command as its own MCP server in the AI client's configuration;
+NexusCrew does not bundle browser automation itself, it only gives the
+container a loopback CDP port to attach one to. It is the same Chromium the
+panel shows over the desktop, so it carries the same logins — treat driving
+it with the same care as watching it.
+
+## Dependencies
+
+**Bundled:** the `docker/` recipe (`Dockerfile`, `docker-compose.example.yml`,
+`custom-cont-init.d/10-cdp-relay.sh`) ships with this skill.
+
+**External (you must provide):**
+
+| Need | Install | Probe / failure mode |
+|---|---|---|
+| Docker with Compose v2 | your platform's Docker install | `docker compose version` fails → nothing in `docker/` builds or runs |
+| A Playwright-capable MCP client, to drive the browser | install separately, point it at the CDP port | if no such client is registered, no `browser_*`-style tools exist in that session — the desktop and its panel still work without it |

package/skills/aidesktop/docker/Dockerfile

@@ -0,0 +1,21 @@
+# AI Desktop = a webtop base plus the one thing the base is missing: a way to
+# reach Chrome DevTools Protocol from outside the container.
+#
+# WHAT THIS IMAGE DELIBERATELY DOES NOT DO
+# It does not try to give the browser its own sandbox. That is a decision, not
+# an omission, and it was made after measuring — see ../SKILL.md, "Where the
+# boundary is". In short: inside this container the browser's own sandbox
+# cannot start (setuid helper blocked by no-new-privileges, unprivileged user
+# namespaces denied), and the changes that would let it start are exactly the
+# ones that weaken the container — the boundary that actually holds here.
+FROM lscr.io/linuxserver/webtop:debian-xfce
+
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends socat \
+ && rm -rf /var/lib/apt/lists/*
+
+# socat: modern Chrome IGNORES --remote-debugging-address and binds CDP to
+# 127.0.0.1 inside the container, so a Docker port mapping alone never
+# reaches it. The relay 0.0.0.0:9223 -> 127.0.0.1:9222 is the only bridge,
+# and it still only leaves the container through a port you publish to the
+# host's own loopback (see docker-compose.example.yml).

package/skills/aidesktop/docker/custom-cont-init.d/10-cdp-relay.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# Runs at every container start, as root, BEFORE the desktop session starts.
+#
+# 1) Orphaned profile locks: if the container dies while Chromium is still
+#    running, Singleton{Lock,Cookie,Socket} files are left behind pointing at
+#    a dead pid, and Chromium then REFUSES to start on the next boot.
+#    Observed symptom: autostart present, zero processes, no visible error.
+#    It is safe to remove them here: the desktop session has not started yet,
+#    so no browser can possibly be alive.
+rm -f /config/browser-profile/Singleton* 2>/dev/null || true
+
+# 2) CDP relay: modern Chrome ignores --remote-debugging-address and binds
+#    DevTools to 127.0.0.1 inside the container, unreachable through a Docker
+#    port mapping. socat bridges it. What leaves the container through this
+#    port still only reaches the host's own loopback — see the port mapping
+#    in docker-compose.example.yml.
+pkill -f "TCP-LISTEN:9223" 2>/dev/null || true
+nohup socat TCP-LISTEN:9223,fork,reuseaddr TCP:127.0.0.1:9222 >/dev/null 2>&1 &
+
+echo "[cdp-relay] stale profile locks cleared; socat 9223 -> 9222 started"

package/skills/aidesktop/docker/docker-compose.example.yml

@@ -0,0 +1,75 @@
+# Example compose for the AI Desktop recipe. Copy this next to the Dockerfile
+# and custom-cont-init.d/, adjust the marked values, then:
+#
+#   docker compose up -d --build
+#
+# First start creates an EMPTY browser profile under ./config — no logins,
+# no history, nothing carried over from anywhere else. Expect a self-signed
+# certificate warning on the HTTPS port on first connect: normal for a
+# loopback-only service, and safe to trust locally.
+services:
+  ai-desktop:
+    build: .
+    image: ai-desktop:local
+    container_name: ai-desktop
+    restart: unless-stopped
+
+    environment:
+      - PUID=1000
+      - PGID=1000
+      - TZ=Etc/UTC                    # set your own timezone
+      - TITLE=AI Desktop
+      # GUI login: without a password, anyone who reaches the port gets a
+      # terminal with passwordless sudo INSIDE the container. Create your own
+      # ./.gui_password file (mode 600, one line, no trailing newline needed)
+      # before the first start — do not put the password in this file.
+      - CUSTOM_USER=admin              # set your own login name
+      - FILE__PASSWORD=/run/gui_password
+
+    volumes:
+      - ./config:/config
+      - ./.gui_password:/run/gui_password:ro
+      - ./custom-cont-init.d:/custom-cont-init.d:ro
+
+    # Loopback only, like everything else in NexusCrew: reach this from
+    # elsewhere through an SSH tunnel or VPN you control, never by publishing
+    # these ports beyond 127.0.0.1.
+    # 6900 = http, 6901 = https. The https port is the one worth using day to
+    # day — full desktop features (clipboard, audio/video codecs) need it.
+    ports:
+      - "127.0.0.1:6900:3000"
+      - "127.0.0.1:6901:3001"
+      # CDP of the Chromium running on the desktop: the channel a Playwright
+      # MCP client attaches to (see SKILL.md). Same browser you see and use
+      # over the desktop, so same logins.
+      - "127.0.0.1:9222:9223"
+
+    # Chromium crashes on tab open without adequate /dev/shm.
+    shm_size: "1gb"
+    mem_limit: 4g               # tune to your machine
+    mem_reservation: 1g
+    cpus: 2.0
+
+    # KEEP THIS. The container is the boundary that holds here, and this line
+    # is part of it. The browser inside runs with --no-sandbox — that is not
+    # an accident, it is the trade this image makes: giving Chromium its own
+    # sandbox would require handing the container CAP_SYS_ADMIN or
+    # seccomp=unconfined, weakening the one boundary that is actually doing
+    # the work in order to add one inside it.
+    #
+    # Measured, not assumed: with this line set, launching the browser without
+    # --no-sandbox aborts — the setuid helper cannot elevate (PR_SET_NO_NEW_PRIVS)
+    # and the namespace sandbox is denied ("failed to move to new namespace:
+    # Operation not permitted"). See ../SKILL.md, "Where the boundary is".
+    #
+    # The consequence is real and you should plan for it: a renderer exploit
+    # lands in this container. Treat what the browser can reach — its profile,
+    # its sessions, anything you mount — as being inside the blast radius.
+    security_opt:
+      - no-new-privileges:true
+
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"