From cca08b6451596595f8bfbd83345e40fe89dbd139 Mon Sep 17 00:00:00 2001 From: Marketen Date: Mon, 24 Aug 2026 11:50:10 +0200 Subject: [PATCH 01/10] Add a Private mode toggle that routes Nexus through the attested local proxy The wizard hardcoded the direct Nexus endpoint, which is the path where TLS terminates at Cloudflare and prompts are readable there. A checkbox on the Nexus configuration screen now switches model.base_url to the nexus-local-proxy package on the same DAppNode, which verifies the Gateway's AWS Nitro attestation against a pinned policy and encrypts bodies with EHBP past that point. It is a toggle in this package rather than a separate package: a fork would double maintenance and split users. The base URL is written in two places -- env.OPENAI_BASE_URL and model.base_url in the generated config.yaml -- and both now go through one nexusBaseUrl() helper so they cannot drift apart. config.yaml is the load-bearing one; the env vars get cleared by config migration on boot. Default is off. The proxy fails closed, so opting in should be a deliberate choice made after reading what it changes rather than something a user discovers when inference stops working. The toggle copy states that trade-off rather than presenting it as free -- a verification failure surfaces as connection errors with no silent fallback to the unprotected path -- and links to the proxy's verification page. No manifest dependency is declared. nexus-local-proxy has never been published to the DAppNode registry: resolving it by name returns NOREPO and it does not appear in a registry search, because only its IPFS artifacts exist and it has been installed by hash. A dependencies entry would therefore fail to resolve at install time and break installing Hermes at all. The toggle copy carries the requirement instead -- it names the package, says this one will not install it, and tells the user to leave the toggle off until they have. Two supporting fixes in patch-config.py: - The context_size lookup was gated on the literal string nexus-api.dappnode.com in base_url. With Private mode on that gate is false, so model.context_length would never be set and every model would silently use Hermes' 256K fallback -- wrong for all of them (Deepseek V4 Flash is 1048576, MiniMax M2.7 is 204800). It now recognises either Nexus route, and falls back to the public catalog when the configured endpoint has no /models, which is the case on nexus-local-proxy releases before 0.1.1. - That lookup has in fact never worked. Cloudflare fronts nexus-api.dappnode.com and 403s the default Python-urllib User-Agent, so the fetch always failed and every Nexus user has been running on the 256K fallback. Upstream Hermes already guards against the same WAF behaviour in providers/base.py. Sending a real User-Agent fixes it; verified live, returning 1048576 and 204800 for the two models above, both directly and through a running proxy. Verified: wizard JS syntax-checked, and buildEnv()/buildConfigYaml() exercised against a DOM stub to confirm both write sites flip together with the toggle while the API key and context_length still land in config.yaml. Co-Authored-By: Claude Opus 5 --- dappnode/dappnode-nexus/SKILL.md | 27 +++++++++++++++- dappnode/patch-config.py | 55 +++++++++++++++++++++++++------- dappnode_package.json | 5 +-- setup-wizard/index.html | 54 +++++++++++++++++++++++++++++-- 4 files changed, 125 insertions(+), 16 deletions(-) diff --git a/dappnode/dappnode-nexus/SKILL.md b/dappnode/dappnode-nexus/SKILL.md index a8b0e96..6868856 100644 --- a/dappnode/dappnode-nexus/SKILL.md +++ b/dappnode/dappnode-nexus/SKILL.md @@ -27,12 +27,34 @@ Nexus runs as a service within the DAppNode ecosystem. Users access it via: - **Web UI**: https://nexus.dappnode.com/ - **API endpoint**: `https://nexus-api.dappnode.com/v1` +There are two ways to reach the API, chosen by the "Private mode" toggle in the +setup wizard: + +| Route | `model.base_url` | Who can read the prompt in transit | +|---|---|---| +| Direct | `https://nexus-api.dappnode.com/v1` | TLS terminates at Cloudflare, so prompts are visible there | +| Private mode | `http://nexus-local-proxy.dappnode.private:3301/v1` | Nobody between the proxy and the enclave | + +Private mode routes through the **nexus-local-proxy** package on the same +DAppNode. That proxy verifies the Nexus Gateway's AWS Nitro Enclave attestation +against a pinned trust policy and encrypts request and response bodies with +EHBP, so an intermediary that terminates TLS cannot read them. + +It **fails closed**: if the Gateway cannot be verified the proxy refuses to +run, and Hermes gets connection errors rather than a silent downgrade to the +unprotected path. The verification page at +`http://nexus-local-proxy.dappnode.private:3301/verification` shows the current +verdict, the checks performed, and the raw attestation evidence for independent +re-checking. + ## Key URLs | Resource | URL | |----------|-----| | Nexus Web App | https://nexus.dappnode.com/ | | Nexus API | https://nexus-api.dappnode.com/v1 | +| Attested local proxy | http://nexus-local-proxy.dappnode.private:3301/v1 | +| Proxy verification page | http://nexus-local-proxy.dappnode.private:3301/verification | | DAppNode Main Site | https://dappnode.com/ | ## Privacy Guarantees @@ -40,6 +62,9 @@ Nexus runs as a service within the DAppNode ecosystem. Users access it via: - Inference runs on DAppNode infrastructure, not external cloud providers - Data does not leave the user's controlled environment - No logging or retention of prompts by default +- With Private mode on, prompt and completion bodies are additionally encrypted + to a measured enclave, so the TLS terminator in front of the Gateway cannot + read them ## Pitfalls @@ -47,7 +72,7 @@ Nexus runs as a service within the DAppNode ecosystem. Users access it via: When Nexus is configured as the Hermes provider (`nexus-api.dappnode.com`), Hermes may not auto-detect the model's true context length because: -1. `nexus-api.dappnode.com` is not in Hermes' `_URL_TO_PROVIDER` map → treated as an unknown custom endpoint +1. Neither `nexus-api.dappnode.com` nor the local proxy is in Hermes' `_URL_TO_PROVIDER` map → treated as an unknown custom endpoint 2. Hermes may skip provider-aware lookups (Anthropic API, models.dev, hardcoded defaults) 3. Falls back to `DEFAULT_FALLBACK_CONTEXT = 256_000` tokens if auto-detection fails diff --git a/dappnode/patch-config.py b/dappnode/patch-config.py index 2513610..4fcd93e 100644 --- a/dappnode/patch-config.py +++ b/dappnode/patch-config.py @@ -19,15 +19,31 @@ skip_dashboard_auth = os.environ.get("DAPPNODE_SKIP_DASHBOARD_AUTH") == "1" -def fetch_nexus_context_size(base_url, model_id): - """Return the context_size Nexus reports for model_id, or None. +# Nexus is reachable either directly or through the attested local proxy. Both +# expose the same OpenAI-compatible catalog, and the model ids are identical. +NEXUS_DIRECT_BASE_URL = "https://nexus-api.dappnode.com/v1" +NEXUS_BASE_URL_MARKERS = ("nexus-api.dappnode.com", "nexus-local-proxy.dappnode.private") - Queries the OpenAI-compatible ``{base_url}/models`` listing, which Nexus - serves publicly with a ``context_size`` field per model. - """ + +def is_nexus_base_url(base_url): + return any(marker in base_url for marker in NEXUS_BASE_URL_MARKERS) + + +# Cloudflare fronts nexus-api.dappnode.com and 403s the default +# ``Python-urllib/`` User-Agent, so this fetch silently failed and every +# Nexus user fell back to Hermes' 256K default. Upstream Hermes guards against +# the same WAF behaviour in providers/base.py. Send a real UA. +CATALOG_USER_AGENT = "hermes-agent-dappnode/1.0" + + +def _context_size_from(base_url, model_id): + """Return the context_size the catalog at base_url reports, or None.""" url = base_url.rstrip("/") + "/models" try: - req = urllib.request.Request(url, headers={"Accept": "application/json"}) + req = urllib.request.Request( + url, + headers={"Accept": "application/json", "User-Agent": CATALOG_USER_AGENT}, + ) with urllib.request.urlopen(req, timeout=10) as resp: data = json.load(resp) except Exception: @@ -39,6 +55,23 @@ def fetch_nexus_context_size(base_url, model_id): return None +def fetch_nexus_context_size(base_url, model_id): + """Return the context_size Nexus reports for model_id, or None. + + Tries the configured endpoint first, then the public Nexus catalog. The + fallback matters when Hermes points at the local proxy: proxy releases + before 0.1.1 serve only chat completions and 404 on ``/models``, and the + catalog is public either way, so there is nothing private to lose by + asking the direct endpoint for it. + """ + size = _context_size_from(base_url, model_id) + if size: + return size + if base_url.rstrip("/") == NEXUS_DIRECT_BASE_URL: + return None + return _context_size_from(NEXUS_DIRECT_BASE_URL, model_id) + + def read_dashboard_password(username): try: values = {} @@ -159,10 +192,10 @@ def configure_dashboard_auth(config): print(msg) # --- Nexus context length: source the real value from /v1/models --- -# nexus-api.dappnode.com is not in Hermes' URL-to-provider map, so the agent -# cannot auto-detect a model's context window and falls back to 256K. Rather -# than hardcode a single number (wrong for the smaller models -- e.g. Kimi is -# 262K, MiniMax M2.7 is 205K), query the endpoint Nexus already exposes: +# Neither Nexus endpoint is in Hermes' URL-to-provider map, so the agent cannot +# auto-detect a model's context window and falls back to 256K. Rather than +# hardcode a single number (wrong for the smaller models -- e.g. Kimi is 262K, +# MiniMax M2.7 is 205K), query the endpoint Nexus already exposes: # GET /v1/models returns `context_size` per model. Set model.context_length to # that authoritative value for the configured model. model_section = config.setdefault("model", {}) @@ -170,7 +203,7 @@ def configure_dashboard_auth(config): base_url = str(model_section.get("base_url", "")) model_id = model_section.get("default") or model_section.get("model") or "" -if provider == "custom" and "nexus-api.dappnode.com" in base_url and model_id: +if provider == "custom" and is_nexus_base_url(base_url) and model_id: ctx = fetch_nexus_context_size(base_url, model_id) if ctx and model_section.get("context_length") != ctx: model_section["context_length"] = ctx diff --git a/dappnode_package.json b/dappnode_package.json index 523a0c4..29ae5fd 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -62,7 +62,8 @@ "homepage": "https://hermes-agent.nousresearch.com", "setup": "http://hermes-agent.dappnode:8080", "terminal": "http://hermes-agent.dappnode:7681", - "ui": "http://hermes-agent.dappnode:8080/dashboard" + "ui": "http://hermes-agent.dappnode:8080/dashboard", + "verification": "http://nexus-local-proxy.dappnode.private:3301/verification" }, "name": "hermes-agent.dnp.dappnode.eth", "repository": { @@ -81,7 +82,7 @@ "upstreamArg": "UPSTREAM_VERSION", "upstreamRepo": "NousResearch/hermes-agent", "upstreamVersion": "v2026.7.20", - "version": "0.1.7", + "version": "0.1.8", "warnings": { "onRemove": "Removing this package will delete all your Hermes Agent configuration, conversation history, skills, memories, and cached data. Make sure to create a backup first." } diff --git a/setup-wizard/index.html b/setup-wizard/index.html index 0e97b77..2422a4a 100644 --- a/setup-wizard/index.html +++ b/setup-wizard/index.html @@ -894,6 +894,28 @@

Configuration Saved!

// ========================================================================= // Provider definitions // ========================================================================= + + // Nexus can be reached two ways. The direct endpoint terminates TLS at + // Cloudflare, so prompts are readable there. The local proxy verifies the + // Gateway's AWS Nitro attestation and encrypts bodies end-to-end past that + // point, at the cost of a hard dependency on nexus-local-proxy running. + const NEXUS_DIRECT_BASE_URL = "https://nexus-api.dappnode.com/v1"; + const NEXUS_PROXY_BASE_URL = "http://nexus-local-proxy.dappnode.private:3301/v1"; + const NEXUS_PROXY_VERIFICATION_URL = "http://nexus-local-proxy.dappnode.private:3301/verification"; + + // Whether the private-proxy toggle is on. Read through a helper so a + // screen that has not rendered the checkbox yet still gets the default. + // Off by default: the proxy fails closed, so opting in should be a + // deliberate choice made after reading what it changes. + function nexusUseProxy() { + const el = document.getElementById("nexus-attested"); + return el ? el.checked : false; + } + + function nexusBaseUrl() { + return nexusUseProxy() ? NEXUS_PROXY_BASE_URL : NEXUS_DIRECT_BASE_URL; + } + const PROVIDERS = [ { id: "nexus", name: "DAppNode Nexus", desc: "Private AI models — your prompts are never logged or stored", tag: "Recommended", free: false, envKey: "NEXUS_API_KEY", provider: "custom" }, { id: "openrouter", name: "OpenRouter", desc: "Access 200+ models with one key", tag: "Flexible", free: false, envKey: "OPENROUTER_API_KEY", provider: "openrouter" }, @@ -1065,7 +1087,35 @@

Configure DAppNode Nexus

Models are fetched live from Nexus. Browse all at nexus.dappnode.com/models.
Loading models from Nexus...
+
+ +
Sends prompts through the attested local proxy instead of straight to Nexus. Requires the nexus-local-proxy package installed and running on this DAppNode.
+ + +
`; + document.getElementById("nexus-attested").addEventListener("change", (e) => { + document.getElementById("nexus-attested-notice").style.display = e.target.checked ? "block" : "none"; + }); fetchNexusModels(); return; } @@ -1361,7 +1411,7 @@

Configure ${p.name}

if (p.id === "nexus") { const apiKey = (document.getElementById("api-key").value || "").trim(); if (apiKey) env.NEXUS_API_KEY = apiKey; - env.OPENAI_BASE_URL = "https://nexus-api.dappnode.com/v1"; + env.OPENAI_BASE_URL = nexusBaseUrl(); env.OPENAI_API_KEY = apiKey; env.LLM_MODEL = getModelValue() || "deepseek/deepseek-v4-pro"; } else if (p.id === "ollama") { @@ -1413,7 +1463,7 @@

Configure ${p.name}

const model = getModelValue() || "deepseek/deepseek-v4-pro"; lines.push(` default: "${model}"`); lines.push(` provider: "custom"`); - lines.push(` base_url: "https://nexus-api.dappnode.com/v1"`); + lines.push(` base_url: "${nexusBaseUrl()}"`); // Hermes reads the key for a custom endpoint from model.api_key in // config.yaml (the documented source of truth). The NEXUS_API_KEY / // OPENAI_API_KEY env vars are not a reliable path: NEXUS_API_KEY is From 5467e0268aa9d9b45dfe2fdff64aa7a56c738e4e Mon Sep 17 00:00:00 2001 From: Marketen Date: Tue, 25 Aug 2026 21:16:46 +0200 Subject: [PATCH 02/10] Depend on nexus-local-proxy now that it is a core package The dependency came out earlier because nexus-local-proxy.dnp.dappnode.eth had no registry entry -- resolving it by name returned NOREPO, so declaring it would have broken installing Hermes at all. It is now shipped as a core package via DNP_CORE, so it is guaranteed present and the dependency resolves. That makes the toggle copy accurate again: it no longer tells the user to go install the proxy themselves, only what routing through it changes and that it fails closed. Requires nexus-local-proxy 0.2.0 and the DNP_CORE release that carries it. Co-Authored-By: Claude Opus 5 --- dappnode_package.json | 3 +++ setup-wizard/index.html | 6 ++---- 2 files changed, 5 insertions(+), 4 deletions(-) diff --git a/dappnode_package.json b/dappnode_package.json index 29ae5fd..4196bab 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -18,6 +18,9 @@ "Developer tools", "Communications" ], + "dependencies": { + "nexus-local-proxy.dnp.dappnode.eth": "^0.2.0" + }, "description": "Hermes Agent is a self-improving AI agent built by Nous Research. It features a built-in learning loop — creating skills from experience, improving them during use, and building a deepening model of who you are across sessions.\n\n- **Web Gateway**: Full-featured web interface for interacting with AI\n- **Multi-LLM Support**: OpenRouter, OpenAI, Anthropic, Google Gemini, Ollama, Groq, and more\n- **Messaging Gateway**: Telegram, Discord, Slack, WhatsApp, Signal — all from a single process\n- **Skills System**: Agent-curated procedural memory that self-improves\n- **Persistent Memory**: Cross-session recall with user modeling\n- **Cron Scheduling**: Automated tasks with delivery to any platform\n- **Subagent Delegation**: Spawn isolated subagents for parallel workstreams\n\nRun your own AI agent with full control over your data and API keys.", "exposable": [ { diff --git a/setup-wizard/index.html b/setup-wizard/index.html index 2422a4a..5365c44 100644 --- a/setup-wizard/index.html +++ b/setup-wizard/index.html @@ -1089,7 +1089,7 @@

Configure DAppNode Nexus

-
Sends prompts through the attested local proxy instead of straight to Nexus. Requires the nexus-local-proxy package installed and running on this DAppNode.
+
Sends prompts through the attested local proxy instead of straight to Nexus.
-
Sends prompts through the attested local proxy instead of straight to Nexus.
+
Sends prompts through the attested local proxy instead of straight to Nexus. Requires the nexus-local-proxy package installed and running on this DAppNode.
+ + +

Quick Links

@@ -824,6 +877,144 @@

Configuration Saved!

} if (name === "dashboard") { refreshDashboard(); + + // ========================================================================= + // Nexus privacy mode (runtime switch) + // ========================================================================= + // Direct and private are the same account, the same key and the same model + // ids -- only model.base_url differs. So this is a switch, not a + // reconfiguration: nothing is re-entered and the provider never changes. + + let _nexusModeBusy = false; + + function nexusModeMessage(text, kind) { + const el = document.getElementById("nexus-mode-msg"); + if (!el) return; + if (!text) { el.hidden = true; el.textContent = ""; return; } + el.hidden = false; + el.className = "nexus-mode-msg" + (kind ? " " + kind : ""); + el.innerHTML = text; + } + + function renderNexusMode(state) { + const card = document.getElementById("nexus-mode-card"); + const toggle = document.getElementById("nexus-mode-toggle"); + const sub = document.getElementById("nexus-mode-sub"); + const detail = document.getElementById("nexus-mode-detail"); + if (!card || !toggle) return; + + // Not pointed at Nexus at all -- the switch would be meaningless. + if (!state || !state.is_nexus) { card.hidden = true; return; } + card.hidden = false; + + const isPrivate = state.mode === "private"; + toggle.checked = isPrivate; + toggle.disabled = _nexusModeBusy; + + const proxy = state.proxy || {}; + sub.textContent = isPrivate + ? "On — prompts are encrypted to the attested enclave" + : "Off — prompts are readable where TLS terminates"; + + if (isPrivate) { + let evidence = ""; + if (proxy.reachable && proxy.status) { + evidence = ` Proxy status: ${escapeHtml(String(proxy.status))}.`; + if (proxy.sourceRevision) { + evidence += ` Verified Gateway build ${escapeHtml(String(proxy.sourceRevision).slice(0, 12))}.`; + } + } + detail.innerHTML = + "Prompts and completions go through nexus-local-proxy on this DAppNode, " + + "which checks the Gateway is the expected code running inside an AWS Nitro Enclave and " + + "encrypts bodies so the TLS terminator in front of Nexus cannot read them." + + evidence + + ` See the verification evidence.`; + } else { + detail.innerHTML = + "Prompts travel to Nexus over ordinary HTTPS, which is decrypted at Cloudflare before it " + + "reaches the Gateway. Turn this on to route them through the attested proxy on this " + + "DAppNode instead. Your API key and model do not change."; + } + + if (!proxy.reachable) { + toggle.disabled = true; + nexusModeMessage( + "nexus-local-proxy is not reachable. Install and start the " + + "nexus-local-proxy package on this DAppNode to use private mode." + + (isPrivate + ? " Private mode is currently selected, so Hermes will report connection errors until " + + "the proxy is running — the proxy fails closed and never falls back to the " + + "unprotected path." + : ""), + isPrivate ? "err" : null + ); + } else if (!_nexusModeBusy) { + nexusModeMessage(null); + } + } + + function escapeHtml(value) { + return String(value).replace(/[&<>"']/g, (c) => ( + { "&": "&", "<": "<", ">": ">", '"': """, "'": "'" }[c] + )); + } + + async function refreshNexusMode() { + try { + const resp = await fetch("/api/nexus/mode"); + renderNexusMode(await resp.json()); + } catch { + const card = document.getElementById("nexus-mode-card"); + if (card) card.hidden = true; + } + } + + async function setNexusMode(enabled) { + const toggle = document.getElementById("nexus-mode-toggle"); + _nexusModeBusy = true; + if (toggle) toggle.disabled = true; + const target = enabled ? "private" : "direct"; + nexusModeMessage("Switching to " + (enabled ? "private" : "direct") + " mode…"); + try { + const resp = await fetch("/api/nexus/mode", { + method: "POST", + headers: { "Content-Type": "application/json" }, + body: JSON.stringify({ mode: target }) + }); + const data = await resp.json(); + if (!resp.ok) { + // Put the switch back where it was: the change did not happen. + if (toggle) toggle.checked = !enabled; + nexusModeMessage(escapeHtml(data.error || "Could not switch mode"), "err"); + return; + } + // Hermes reads config.yaml at startup, so the switch only takes effect + // after a restart. Do it for the user rather than leaving the agent in + // a state that disagrees with what the toggle shows. + nexusModeMessage("Saved. Restarting Hermes to apply…", "ok"); + await fetch("/api/restart", { method: "POST" }); + nexusModeMessage( + "Restarting Hermes — this takes about 5–10 seconds. " + + (enabled + ? "Prompts will be encrypted to the attested enclave once it is back." + : "Prompts will go directly to Nexus once it is back."), + "ok" + ); + setTimeout(() => { refreshNexusMode(); refreshDashboard(); }, 12000); + } catch (err) { + if (toggle) toggle.checked = !enabled; + nexusModeMessage(escapeHtml(err.message || "Could not switch mode"), "err"); + } finally { + _nexusModeBusy = false; + if (toggle) toggle.disabled = false; + } + } + + document.getElementById("nexus-mode-toggle") + .addEventListener("change", (e) => setNexusMode(e.target.checked)); + + refreshNexusMode(); } else { // Stop polling when leaving dashboard if (_dashboardPollTimer) { clearInterval(_dashboardPollTimer); _dashboardPollTimer = null; } @@ -1116,6 +1307,16 @@

Configure DAppNode Nexus

document.getElementById("nexus-attested").addEventListener("change", (e) => { document.getElementById("nexus-attested-notice").style.display = e.target.checked ? "block" : "none"; }); + // Seed the checkbox from the mode actually in force. Without this, + // re-running the wizard with private mode on would silently write the + // direct endpoint back, downgrading the user without telling them. + fetch("/api/nexus/mode").then(r => r.json()).then((state) => { + if (!state || state.mode !== "private") return; + const box = document.getElementById("nexus-attested"); + if (!box) return; + box.checked = true; + document.getElementById("nexus-attested-notice").style.display = "block"; + }).catch(() => {}); fetchNexusModels(); return; } diff --git a/setup-wizard/server.cjs b/setup-wizard/server.cjs index ea60d4a..f90d67d 100644 --- a/setup-wizard/server.cjs +++ b/setup-wizard/server.cjs @@ -396,6 +396,72 @@ async function fetchNexusModels() { } } +// --- Nexus endpoint mode ----------------------------------------------- +// Direct vs private (attested local proxy) is only a model.base_url value in +// config.yaml. nexus_mode.py owns that knowledge and edits the file with a +// real YAML parser, so the wizard never has to pattern-match config text. + +// Overridable so the wizard can be exercised outside the image, where +// neither the venv nor /opt/dappnode exists. +const NEXUS_MODE_SCRIPT = process.env.NEXUS_MODE_SCRIPT || "/opt/dappnode/nexus_mode.py"; +const NEXUS_MODE_PYTHON = process.env.NEXUS_MODE_PYTHON || "/opt/hermes/.venv/bin/python3"; +const NEXUS_PROXY_HEALTH_URL = "http://nexus-local-proxy.dappnode.private:3301/healthz"; +const NEXUS_PROXY_VERIFICATION_API = "http://nexus-local-proxy.dappnode.private:3301/v1/verification"; + +/** + * Run nexus_mode.py and parse its JSON. Runs as the hermes user for the same + * reason getHermesStatus does: a root-owned config.yaml would leave the + * gateway unable to write it. + */ +function runNexusMode(args) { + return new Promise((resolve) => { + const python = NEXUS_MODE_PYTHON; + const [cmd, argv] = + process.getuid && process.getuid() === 0 + ? ["s6-setuidgid", ["hermes", python, NEXUS_MODE_SCRIPT, ...args]] + : [python, [NEXUS_MODE_SCRIPT, ...args]]; + execFile(cmd, argv, { timeout: 15000, env: { ...process.env, HERMES_HOME } }, (err, stdout) => { + let parsed = null; + try { parsed = JSON.parse(String(stdout || "").trim()); } catch { parsed = null; } + if (!parsed) { + resolve({ error: "could not read the Nexus endpoint from config.yaml" }); + return; + } + resolve(parsed); + }); + }); +} + +/** + * Is the attested proxy actually up? Private mode fails closed, so the UI + * must be able to say "this will break Hermes" before the user flips it + * rather than after. + */ +async function probeNexusProxy() { + try { + const resp = await fetch(NEXUS_PROXY_HEALTH_URL, { signal: AbortSignal.timeout(4000) }); + if (!resp.ok) return { reachable: false, reason: `proxy returned HTTP ${resp.status}` }; + } catch { + return { reachable: false, reason: "nexus-local-proxy is not reachable on this DAppNode" }; + } + // Reachable. Fold in the verification verdict when the proxy offers one, so + // the switch can show what is actually being attested rather than just that + // a port is open. + try { + const resp = await fetch(NEXUS_PROXY_VERIFICATION_API, { signal: AbortSignal.timeout(4000) }); + if (resp.ok) { + const snapshot = await resp.json(); + return { + reachable: true, + status: snapshot.status || null, + sourceRevision: (snapshot.current && snapshot.current.source_revision) || null, + verifiedTotal: snapshot.verified_total ?? null, + }; + } + } catch { /* verification detail is a bonus, not a requirement */ } + return { reachable: true }; +} + /** * Run `hermes status` and return the output. */ @@ -614,6 +680,51 @@ const server = http.createServer(async (req, res) => { return; } + // Current Nexus endpoint mode + whether the attested proxy is usable + if (req.method === "GET" && url.pathname === "/api/nexus/mode") { + const state = await runNexusMode(["get"]); + const proxy = await probeNexusProxy(); + json(res, 200, { ...state, proxy }); + return; + } + + // Flip between direct Nexus and the attested local proxy. + // + // This only rewrites model.base_url. The API key, provider and model are + // untouched, so switching never asks the user to re-enter anything. Hermes + // reads config.yaml at startup, so the caller restarts to apply it. + if (req.method === "POST" && url.pathname === "/api/nexus/mode") { + try { + const body = await readBody(req); + const incoming = JSON.parse(body || "{}"); + const mode = incoming.mode === "private" ? "private" : incoming.mode === "direct" ? "direct" : null; + if (!mode) { + json(res, 400, { error: "mode must be 'direct' or 'private'" }); + return; + } + // Refuse to switch into a mode that cannot work. The proxy fails closed, + // so enabling private mode while it is down would take Hermes offline + // with a connection error rather than a useful message. `force` exists + // for the case where the user is knowingly setting it up ahead of time. + if (mode === "private" && !incoming.force) { + const proxy = await probeNexusProxy(); + if (!proxy.reachable) { + json(res, 409, { error: proxy.reason, proxy }); + return; + } + } + const state = await runNexusMode(["set", mode]); + if (state.error) { + json(res, 400, state); + return; + } + json(res, 200, { ...state, restartRequired: true }); + } catch (err) { + json(res, 400, { error: err.message }); + } + return; + } + // Probe Ollama if (req.method === "GET" && url.pathname === "/api/ollama/probe") { const result = await probeOllama(); From 94acf52bc35dcbecac43c533f86f0fe69eeeeebd Mon Sep 17 00:00:00 2001 From: Marketen Date: Wed, 9 Sep 2026 12:32:14 +0200 Subject: [PATCH 05/10] Decide Nexus mode on an exact hostname, not a substring CodeQL flagged the substring match, and it is worse here than the generic rule suggests. `NEXUS_PROXY_HOST in base_url` is true for http://nexus-local-proxy.dappnode.private.evil.com:3301/v1 so that endpoint would be reported as private mode and the dashboard would tell the user their prompts were encrypted to an attested enclave while they went somewhere else entirely. A privacy indicator that can be spoofed into claiming a guarantee it cannot back is worse than no indicator. Parse the URL and compare the hostname exactly. A base_url written without a scheme still resolves, so nothing that used to be recognised stops being recognised; the comparison is exact either way. Verified against the spoofing cases the substring version accepted: the marker appearing as a subdomain prefix, in a path, in a query string and in a fragment are all now correctly not_nexus, while both real endpoints, a trailing slash and a schemeless host still classify correctly. Co-Authored-By: Claude Opus 5 --- dappnode/nexus_mode.py | 37 +++++++++++++++++++++++++++---------- 1 file changed, 27 insertions(+), 10 deletions(-) diff --git a/dappnode/nexus_mode.py b/dappnode/nexus_mode.py index de1e0d0..da27326 100644 --- a/dappnode/nexus_mode.py +++ b/dappnode/nexus_mode.py @@ -28,19 +28,16 @@ import os import sys from pathlib import Path +from urllib.parse import urlsplit import yaml -NEXUS_DIRECT_BASE_URL = "https://nexus-api.dappnode.com/v1" +NEXUS_DIRECT_HOST = "nexus-api.dappnode.com" NEXUS_PROXY_HOST = "nexus-local-proxy.dappnode.private" +NEXUS_DIRECT_BASE_URL = f"https://{NEXUS_DIRECT_HOST}/v1" NEXUS_PROXY_BASE_URL = f"http://{NEXUS_PROXY_HOST}:3301/v1" NEXUS_PROXY_VERIFICATION_URL = f"http://{NEXUS_PROXY_HOST}:3301/verification" -# Any base_url carrying one of these is a Nexus endpoint. Kept as a tuple of -# substrings rather than exact URLs so a trailing slash or an explicit port -# does not make an endpoint unrecognisable. -NEXUS_BASE_URL_MARKERS = ("nexus-api.dappnode.com", NEXUS_PROXY_HOST) - MODE_DIRECT = "direct" MODE_PRIVATE = "private" # The configured endpoint is not Nexus at all (Ollama, OpenRouter, ...), so @@ -57,18 +54,38 @@ def config_path() -> Path: return Path(os.environ.get("HERMES_HOME", "/opt/data")) / "config.yaml" -def is_nexus_base_url(base_url: str) -> bool: - return any(marker in base_url for marker in NEXUS_BASE_URL_MARKERS) +def endpoint_host(base_url: str) -> str: + """Return the lowercased hostname of base_url, or "" if there isn't one. + + Modes are decided on an exact hostname, never on a substring. Substring + matching would classify https://nexus-api.dappnode.com.example.net/v1 as + Nexus, and worse, would let a host merely *containing* the proxy name be + reported as private mode -- so the dashboard would promise the prompt was + encrypted to an attested enclave while it went somewhere else entirely. + """ + try: + # A base_url written without a scheme still has a host worth reading; + # the "//" prefix makes urlsplit treat it as an authority rather than + # a path. The comparison below stays exact either way. + candidate = base_url if "//" in base_url else "//" + base_url.lstrip("/") + return (urlsplit(candidate).hostname or "").lower() + except ValueError: + return "" def detect_mode(base_url: str) -> str: - if NEXUS_PROXY_HOST in base_url: + host = endpoint_host(base_url) + if host == NEXUS_PROXY_HOST: return MODE_PRIVATE - if "nexus-api.dappnode.com" in base_url: + if host == NEXUS_DIRECT_HOST: return MODE_DIRECT return MODE_NOT_NEXUS +def is_nexus_base_url(base_url: str) -> bool: + return detect_mode(base_url) != MODE_NOT_NEXUS + + def load_config(path: Path) -> dict: try: with open(path) as handle: From d42cb4ea3904b56846a66ad0dd08c04bd8d209d5 Mon Sep 17 00:00:00 2001 From: Marketen Date: Wed, 9 Sep 2026 13:41:49 +0200 Subject: [PATCH 06/10] Follow the proxy package rename to nexus-proxy The proxy package moved to dappnode/DNP_NEXUS_PROXY and took the core naming convention with it, so its internal DNS name changed: nexus-local-proxy.dappnode.private -> nexus-proxy.dappnode.private Hermes hardcodes that host in the switch, the reachability probe, the manifest link and the skill docs, so all of them move with it. A config written before the rename still names the old host, which no longer resolves, so private mode would fail forever with no indication of why. Two things handle that: the old host is still recognised as private mode, since the user did choose private and the report should stay honest, and the boot patch repoints it to the new host before anything else reads base_url. The rename does not weaken the hostname check: matching stays exact, so nexus-proxy.dappnode.private.evil.com is still not_nexus. Co-Authored-By: Claude Opus 5 --- dappnode/dappnode-nexus/SKILL.md | 12 +++++------ dappnode/nexus_mode.py | 36 ++++++++++++++++++++++++++++---- dappnode/patch-config.py | 9 ++++++++ dappnode_package.json | 2 +- setup-wizard/index.html | 18 ++++++++-------- setup-wizard/server.cjs | 6 +++--- 6 files changed, 60 insertions(+), 23 deletions(-) diff --git a/dappnode/dappnode-nexus/SKILL.md b/dappnode/dappnode-nexus/SKILL.md index 1c6e788..0f1131d 100644 --- a/dappnode/dappnode-nexus/SKILL.md +++ b/dappnode/dappnode-nexus/SKILL.md @@ -34,9 +34,9 @@ during setup: | Route | `model.base_url` | Who can read the prompt in transit | |---|---|---| | Direct | `https://nexus-api.dappnode.com/v1` | TLS terminates at Cloudflare, so prompts are visible there | -| Private mode | `http://nexus-local-proxy.dappnode.private:3301/v1` | Nobody between the proxy and the enclave | +| Private mode | `http://nexus-proxy.dappnode.private:3301/v1` | Nobody between the proxy and the enclave | -Private mode routes through the **nexus-local-proxy** package on the same +Private mode routes through the **nexus-proxy** package on the same DAppNode. That proxy verifies the Nexus Gateway's AWS Nitro Enclave attestation against a pinned trust policy and encrypts request and response bodies with EHBP, so an intermediary that terminates TLS cannot read them. @@ -44,7 +44,7 @@ EHBP, so an intermediary that terminates TLS cannot read them. It **fails closed**: if the Gateway cannot be verified the proxy refuses to run, and Hermes gets connection errors rather than a silent downgrade to the unprotected path. The verification page at -`http://nexus-local-proxy.dappnode.private:3301/verification` shows the current +`http://nexus-proxy.dappnode.private:3301/verification` shows the current verdict, the checks performed, and the raw attestation evidence for independent re-checking. @@ -54,7 +54,7 @@ turning privacy on or off never requires re-entering a key or reconfiguring the provider. Hermes reads `config.yaml` at startup, so the package restarts itself to apply the change; the switch does that automatically. -The switch refuses to turn private mode on while `nexus-local-proxy` is +The switch refuses to turn private mode on while `nexus-proxy` is unreachable, because the proxy fails closed and Hermes would simply stop working. Install and start that package first. @@ -64,8 +64,8 @@ working. Install and start that package first. |----------|-----| | Nexus Web App | https://nexus.dappnode.com/ | | Nexus API | https://nexus-api.dappnode.com/v1 | -| Attested local proxy | http://nexus-local-proxy.dappnode.private:3301/v1 | -| Proxy verification page | http://nexus-local-proxy.dappnode.private:3301/verification | +| Attested local proxy | http://nexus-proxy.dappnode.private:3301/v1 | +| Proxy verification page | http://nexus-proxy.dappnode.private:3301/verification | | DAppNode Main Site | https://dappnode.com/ | ## Privacy Guarantees diff --git a/dappnode/nexus_mode.py b/dappnode/nexus_mode.py index da27326..59d5e98 100644 --- a/dappnode/nexus_mode.py +++ b/dappnode/nexus_mode.py @@ -7,8 +7,8 @@ direct https://nexus-api.dappnode.com/v1 TLS terminates at Cloudflare, so prompts are readable there. - private http://nexus-local-proxy.dappnode.private:3301/v1 - The nexus-local-proxy package on this DAppNode verifies the + private http://nexus-proxy.dappnode.private:3301/v1 + The nexus-proxy package on this DAppNode verifies the Gateway's AWS Nitro attestation and encrypts request and response bodies with EHBP, so the TLS terminator cannot read them. @@ -33,7 +33,13 @@ import yaml NEXUS_DIRECT_HOST = "nexus-api.dappnode.com" -NEXUS_PROXY_HOST = "nexus-local-proxy.dappnode.private" +NEXUS_PROXY_HOST = "nexus-proxy.dappnode.private" + +# The proxy package was called nexus-local-proxy before it took the core +# DNP_NEXUS_PROXY naming. A config written back then still names the old host, +# which no longer resolves. Recognising it keeps the reported mode honest -- +# the user did choose private -- and boot-time migration repoints it. +LEGACY_PROXY_HOSTS = ("nexus-local-proxy.dappnode.private",) NEXUS_DIRECT_BASE_URL = f"https://{NEXUS_DIRECT_HOST}/v1" NEXUS_PROXY_BASE_URL = f"http://{NEXUS_PROXY_HOST}:3301/v1" NEXUS_PROXY_VERIFICATION_URL = f"http://{NEXUS_PROXY_HOST}:3301/verification" @@ -75,13 +81,35 @@ def endpoint_host(base_url: str) -> str: def detect_mode(base_url: str) -> str: host = endpoint_host(base_url) - if host == NEXUS_PROXY_HOST: + if host == NEXUS_PROXY_HOST or host in LEGACY_PROXY_HOSTS: return MODE_PRIVATE if host == NEXUS_DIRECT_HOST: return MODE_DIRECT return MODE_NOT_NEXUS +def migrate_legacy_host(path: Path | None = None) -> bool: + """Repoint a config still naming the pre-rename proxy host. + + Returns True when it rewrote something. Safe to run on every boot: it only + touches a base_url whose host is a known legacy name. + """ + path = path or config_path() + config = load_config(path) + model = config.get("model") + if not isinstance(model, dict): + return False + if endpoint_host(str(model.get("base_url") or "")) not in LEGACY_PROXY_HOSTS: + return False + model["base_url"] = NEXUS_PROXY_BASE_URL + config["model"] = model + temporary = path.with_suffix(path.suffix + ".tmp") + with open(temporary, "w") as handle: + yaml.dump(config, handle, default_flow_style=False, sort_keys=False) + os.replace(temporary, path) + return True + + def is_nexus_base_url(base_url: str) -> bool: return detect_mode(base_url) != MODE_NOT_NEXUS diff --git a/dappnode/patch-config.py b/dappnode/patch-config.py index a6e725b..6b31dd8 100644 --- a/dappnode/patch-config.py +++ b/dappnode/patch-config.py @@ -26,6 +26,7 @@ from nexus_mode import ( # noqa: E402 NEXUS_DIRECT_BASE_URL, is_nexus_base_url, + migrate_legacy_host, ) @@ -191,6 +192,14 @@ def configure_dashboard_auth(config): msg += "; dashboard credentials saved to /opt/data/dashboard-login.txt" print(msg) +# --- Nexus proxy rename: repoint configs written before DNP_NEXUS_PROXY --- +# The old nexus-local-proxy.dappnode.private host no longer resolves, so a +# config still naming it would leave private mode permanently failing. Rewrite +# it before the context-length lookup below reads base_url. +if migrate_legacy_host(config_path): + config = yaml.safe_load(open(config_path)) or {} + print("Nexus: repointed the proxy host to nexus-proxy.dappnode.private") + # --- Nexus context length: source the real value from /v1/models --- # Neither Nexus endpoint is in Hermes' URL-to-provider map, so the agent cannot # auto-detect a model's context window and falls back to 256K. Rather than diff --git a/dappnode_package.json b/dappnode_package.json index fc4e4fb..ecb44d2 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -63,7 +63,7 @@ "setup": "http://hermes-agent.dappnode:8080", "terminal": "http://hermes-agent.dappnode:7681", "ui": "http://hermes-agent.dappnode:8080/dashboard", - "verification": "http://nexus-local-proxy.dappnode.private:3301/verification" + "verification": "http://nexus-proxy.dappnode.private:3301/verification" }, "name": "hermes-agent.dnp.dappnode.eth", "repository": { diff --git a/setup-wizard/index.html b/setup-wizard/index.html index dba3e28..d779985 100644 --- a/setup-wizard/index.html +++ b/setup-wizard/index.html @@ -925,7 +925,7 @@

Configuration Saved!

} } detail.innerHTML = - "Prompts and completions go through nexus-local-proxy on this DAppNode, " + "Prompts and completions go through nexus-proxy on this DAppNode, " + "which checks the Gateway is the expected code running inside an AWS Nitro Enclave and " + "encrypts bodies so the TLS terminator in front of Nexus cannot read them." + evidence @@ -940,8 +940,8 @@

Configuration Saved!

if (!proxy.reachable) { toggle.disabled = true; nexusModeMessage( - "nexus-local-proxy is not reachable. Install and start the " - + "nexus-local-proxy package on this DAppNode to use private mode." + "nexus-proxy is not reachable. Install and start the " + + "nexus-proxy package on this DAppNode to use private mode." + (isPrivate ? " Private mode is currently selected, so Hermes will report connection errors until " + "the proxy is running — the proxy fails closed and never falls back to the " @@ -1089,10 +1089,10 @@

Configuration Saved!

// Nexus can be reached two ways. The direct endpoint terminates TLS at // Cloudflare, so prompts are readable there. The local proxy verifies the // Gateway's AWS Nitro attestation and encrypts bodies end-to-end past that - // point, at the cost of a hard dependency on nexus-local-proxy running. + // point, at the cost of a hard dependency on nexus-proxy running. const NEXUS_DIRECT_BASE_URL = "https://nexus-api.dappnode.com/v1"; - const NEXUS_PROXY_BASE_URL = "http://nexus-local-proxy.dappnode.private:3301/v1"; - const NEXUS_PROXY_VERIFICATION_URL = "http://nexus-local-proxy.dappnode.private:3301/verification"; + const NEXUS_PROXY_BASE_URL = "http://nexus-proxy.dappnode.private:3301/v1"; + const NEXUS_PROXY_VERIFICATION_URL = "http://nexus-proxy.dappnode.private:3301/verification"; // Whether the private-proxy toggle is on. Read through a helper so a // screen that has not rendered the checkbox yet still gets the default. @@ -1280,7 +1280,7 @@

Configure DAppNode Nexus

-
Sends prompts through the attested local proxy instead of straight to Nexus. Requires the nexus-local-proxy package installed and running on this DAppNode.
+
Sends prompts through the attested local proxy instead of straight to Nexus. Requires the nexus-proxy package installed and running on this DAppNode.