From 408b0a5372dd25f7503b0a612c57574b38fb5d67 Mon Sep 17 00:00:00 2001 From: Marketen Date: Wed, 9 Sep 2026 14:04:34 +0200 Subject: [PATCH 1/3] Add getting-started and rewrite the docs for the person installing it The package had no getting-started page, so the Dappnode UI showed nothing after install and there was no route to the verification page from anywhere in the product. It also had no links section, so the UI could not surface the one screen that makes this package meaningful. The README explained the mechanism before it explained the point. It opened on AWS Nitro attestation and EHBP, which is the right level for a maintainer and the wrong one for someone deciding whether to install it. It now opens with what changes for the user and puts the rest behind a "Learn more" divider, where the depth is still there in full. Copy follows what the rest of the Nexus packages now use: TEE (trusted execution environment) rather than naming the vendor and hardware, "Dappnode" in prose, and the three ideas worth landing -- we cannot read your prompts, the proxy verifies it for you automatically, you can check the proof yourself. Both documents now state two real limitations, verified against the live TEE Gateway rather than assumed: - Auto Router (nexus/auto) returns 500 on the TEE Gateway while working on production, so it does not work through the proxy. - PII masking cannot apply. The enclave may only dial the measured egress routes in its signed manifest, and the Presidio analyzer is not one of them, so a key with masking enabled does not get masking here. Also drops the NEXUS_SDK_TOKEN build section: dappnode-nexus-sdk is public now, so the credential it describes no longer exists and the Dockerfile's unauthenticated path is the only one left. Co-Authored-By: Claude Opus 5 --- README.md | 233 ++++++++++++++++++++++-------------------- dappnode_package.json | 11 +- getting-started.md | 49 +++++++++ 3 files changed, 180 insertions(+), 113 deletions(-) create mode 100644 getting-started.md diff --git a/README.md b/README.md index 02e0a02..971972f 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,159 @@ -# Nexus Local Proxy for DAppNode +# Nexus Proxy -This DAppNode package runs one shared Nexus proxy for OpenAI-compatible -applications installed on the same DAppNode. The proxy verifies fresh AWS -Nitro attestation against measurements it takes from signed Gateway releases, -and encrypts chat request and response bodies with EHBP before they cross -Cloudflare. +Your prompts normally get decrypted on the way to Nexus. This Dappnode package +stops that: it encrypts them so only the **TEE** — the trusted execution +environment Nexus runs inside — can read them. Not us, not Dappnode, nobody in +between. -## Client configuration +It also checks that the TEE really is what it claims to be, automatically, on +every connection. If that check fails it stops rather than sending your prompts +unprotected. -Configure DAppNode applications with: +## Use it + +Point any OpenAI-compatible app on this Dappnode at: ```text Base URL: http://nexus-proxy.dappnode.private:3301/v1 -API key: the application's normal Nexus API key -API: OpenAI Chat Completions +API key: your normal Nexus API key ``` -The API key remains in the normal `Authorization: Bearer ...` header. The -proxy does not store it and does not automatically retry inference requests. +Same key, same models, same prices. Some Dappnode apps have a **private mode** +switch that does this for you — Hermes Agent is one. -Applications may declare the package dependency once. They then follow Gateway -releases automatically, without either the application or this package being -republished: +## Check it yourself -```json -{ - "dependencies": { - "nexus-proxy.dnp.dappnode.eth": "^0.1.0" - } -} +```text +http://nexus-proxy.dappnode.private:3301/verification ``` -`POST /v1/chat/completions` and `GET /v1/models` are OpenAI-compatible, so an -application that lists models against its configured base URL works without a -second endpoint. `GET /healthz` reports whether the local proxy is ready. +The page shows whether the check passed right now, what was checked, and lets +you download the raw proof so you can verify it with independent tooling. It +never shows your prompts. -The model catalog is the one route here that is **not** confidential. It is -public, unauthenticated, cacheable data with no prompt, completion or -credential in it, so the proxy passes it through over ordinary TLS rather than -over EHBP, and does not forward the caller's `Authorization` header. These -requests are not counted on the verification page, because nothing about them -crossed the attested channel. Add `--model-catalog=false` to the service -command to remove the route. +## Good to know -## Privacy verification page +- **Auto Router (`nexus/auto`) does not work through the proxy yet.** Pick a + specific model instead. +- **PII masking does not apply.** The masking service runs outside the TEE and + the TEE is not allowed to reach it, so a key with masking enabled will not + get masking here. +- **It fails closed.** If the TEE cannot be verified, requests stop rather than + quietly falling back to the unprotected path. +- **Keep port 3301 internal.** Do not publish it to the host or the internet. -The package serves a page showing whether the Gateway is currently verified and -what was checked: +--- -```text -http://nexus-proxy.dappnode.private:3301/verification -``` +# Learn more + +Everything below is detail. The four points above are the whole story for most +people. + +## What is and is not protected + +Protected: the contents of your prompts and the model's replies, from this +proxy to the verified Nexus Gateway inside the TEE. + +Not protected: + +- **The hop from your app to this proxy.** That is ordinary HTTP on the + Dappnode internal network. You are trusting the Dappnode host, this package, + and that network. +- **Metadata.** Request method, path, headers, body length, timing and your + bearer API key are all still visible to the network in front of Nexus. +- **What the model provider does afterwards.** This package makes no claim + about a downstream inference provider. + +## Endpoints + +| Route | Confidential | Notes | +|---|---|---| +| `POST /v1/chat/completions` | yes | Streaming supported | +| `GET /v1/models` | no | Public catalog, see below | +| `GET /healthz` | n/a | Readiness | +| `GET /verification` | n/a | The page above | -It reports the verdict in plain language, lists the checks the proxy performed -before it would encrypt anything, shows the enclave measurements and attested -key, and lists recent requests with the attested key each one was encrypted to. -From there the raw COSE_Sign1 attestation document and its signed manifest can -be downloaded and re-checked with an independent AWS Nitro verifier. - -The page shows no prompt or completion content. The ledger behind it records -only verification evidence and per request identifiers, timing and sizes. That -history is written to the `verification_state` volume at -`/var/lib/nexus-proxy/verification.json`, so it survives a restart and is -included in package backups. The on-disk format cannot express a prompt or a -completion. Because the page is served on the proxy port, anything on the -DAppNode internal network can read this metadata. Add `--verification-ui=false` -to the service command to remove the page and its API, or drop `--state-file` -from the service command to keep history in memory only. - -## Security boundary - -Callers trust the DAppNode host, this package, and the DAppNode internal -network. The caller-to-proxy hop is ordinary HTTP and is outside EHBP. From -this local proxy to the measured Nexus Gateway process inside AWS Nitro -Enclaves, prompt and completion bodies are encrypted and integrity-protected. - -EHBP does not hide the HTTP method, path, headers, body length, frame sizes, -timing, or bearer API key. This package does not extend the claim to a -downstream inference provider. Do not publish container port 3301 to the host -or Internet. - -## Trust policy - -This package no longer ships enclave measurements. The proxy derives them from -the most recent Gateway releases, each signed during the Gateway release -workflow with a Sigstore certificate issued to that workflow's GitHub identity. -Only a signature from that exact identity is accepted, so the download is not +The model catalog is the one route that is deliberately **not** confidential. +It is public, unauthenticated, cacheable data with no prompt, completion or +credential in it, so the proxy passes it through over ordinary TLS and does not +forward your `Authorization` header. Those requests are not counted on the +verification page, because nothing about them crossed the protected channel. +Add `--model-catalog=false` to remove the route. + +## What the verification page records + +No prompt or completion content, ever. The ledger holds verification evidence +plus per-request identifiers, timing and sizes. The on-disk format cannot +express a prompt or a reply. + +History is written to the `verification_state` volume at +`/var/lib/nexus-proxy/verification.json`, so it survives restarts and is +included in package backups. Because the page is served on the proxy port, +anything on the Dappnode internal network can read this metadata. Add +`--verification-ui=false` to remove the page and its API, or drop +`--state-file` to keep history in memory only. + +## How the proxy knows what to trust + +It does not ship a fixed list of measurements. It derives them from the most +recent Gateway releases, each signed during the Gateway release workflow with a +Sigstore certificate issued to that workflow's GitHub identity. Only a +signature from that exact identity is accepted, so the download itself is not trusted: GitHub is a CDN here, and a swapped or edited release is rejected rather than believed. -This is why the package no longer has to be republished for every Gateway -release, and why an installed proxy can no longer be left stranded on -measurements that predate the deployed enclave. +That is why this package no longer has to be republished for every Gateway +release, and why an installed proxy can no longer be stranded on measurements +that predate the deployed TEE. -What the proxy checks has not changed. The measurements are still compared -against the enclave's live attestation exactly as before, and the -body-encryption contract is compiled into the SDK: a signed release may say -which build to trust, never what protection that build owes the caller. +What gets checked has not changed. Measurements are still compared against the +TEE's live attestation, and the body-encryption contract is compiled into the +SDK: a signed release may say which build to trust, never what protection that +build owes you. -A newly deployed Gateway is picked up on first contact rather than on a timer. -A release the current policy has never heard of is precisely what a new -deployment looks like, so the proxy re-derives its policy and verifies again -within the same request. Nothing needs to be pushed to the node, which matters -because DAppNodes sit behind NAT. An hourly background refresh is a backstop on -top of that. - -It stays fail-closed. If neither the network nor the cache produces a verified -policy, the proxy refuses to start rather than falling back to something older. +A newly deployed Gateway is picked up **on first contact**, not on a timer. A +release the current policy has never heard of is exactly what a new deployment +looks like, so the proxy re-derives its policy and verifies again within the +same request. Nothing has to be pushed to the node, which matters because +Dappnodes sit behind NAT. An hourly background refresh is a backstop on top. +If neither the network nor the cache produces a verified policy, the proxy +refuses to start rather than falling back to something older. `--trust-policy-cache` keeps the signed material from the last successful fetch -on the `verification_state` volume, so a node that restarts without a network -rebuilds the same policy. Every signature is re-verified on load. - -This package pins: +on the `verification_state` volume, and every signature is re-verified on load, +so a tampered cache is rejected rather than believed. -- SDK commit, as `UPSTREAM_VERSION` in `docker-compose.yml` and - `dappnode_package.json`. -- Gateway origin `https://nexus-api-tee.dappnode.com`. -- The Gateway release-workflow signing identity, compiled into the SDK. +This package pins the SDK commit (`UPSTREAM_VERSION` in `docker-compose.yml` +and `dappnode_package.json`), the Gateway origin +`https://nexus-api-tee.dappnode.com`, and the Gateway release-workflow signing +identity, which is compiled into the SDK. ### Network requirement -The proxy needs outbound HTTPS to `api.github.com` and -`objects.githubusercontent.com` at startup, on meeting an unknown Gateway -release, and hourly. A node that cannot reach them starts only if its cache -already holds a verified policy. +Outbound HTTPS to `api.github.com` and `objects.githubusercontent.com` at +startup, on meeting an unknown Gateway release, and hourly. A node that cannot +reach them starts only if its cache already holds a verified policy. + +## Declaring the dependency + +Applications can declare the package once and then follow Gateway releases +automatically, without either the application or this package being +republished: + +```json +{ + "dependencies": { + "nexus-proxy.dnp.dappnode.eth": "^0.1.0" + } +} +``` ## Build ```sh -NEXUS_SDK_TOKEN="$(gh auth token)" docker compose build +docker compose build ``` The image builds the SDK from a full Git commit, verifies the checked-out revision matches, and runs as an unprivileged user in a minimal runtime image. - -`NEXUS_SDK_TOKEN` must hold a token with read access to the private -`dappnode-nexus-sdk` repository. `docker-compose.yml` passes it to the build as -a BuildKit secret, so it never reaches an image layer. In CI it comes from the -`NEXUS_SDK_TOKEN` repository secret; the default `GITHUB_TOKEN` cannot be used -because it is scoped to this repository only. - -Remove the secret, the `secrets:` blocks in `docker-compose.yml`, and this -section once the SDK repository is public: the Dockerfile already falls back to -an unauthenticated fetch when no secret is supplied. +`dappnode-nexus-sdk` is public, so no credentials are needed. diff --git a/dappnode_package.json b/dappnode_package.json index 69fa320..924c893 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -4,8 +4,8 @@ "upstreamVersion": "219977388b9f26435c2529fc1cd52ff7229e5397", "upstreamRepo": "dappnode/dappnode-nexus-sdk", "upstreamArg": "UPSTREAM_VERSION", - "shortDescription": "Attested private AI proxy for DAppNode applications", - "description": "A shared OpenAI-compatible Nexus proxy for applications on the same DAppNode. It verifies the measured Nexus Gateway inside AWS Nitro Enclaves and encrypts prompt and completion bodies with EHBP before they cross Cloudflare. A local verification page at /verification shows the attestation evidence behind that protection and lets you export it for independent checking. GET /v1/models passes the Gateway public model catalog through so ordinary OpenAI clients can list models against the proxy.", + "shortDescription": "Keep your Nexus prompts private, and verify it yourself", + "description": "Your prompts normally get decrypted on the way to Nexus. This package stops that: it encrypts them so only the TEE (trusted execution environment) that Nexus runs inside can read them — not us, not Dappnode, nobody in between.\n\nIt checks that the TEE really is what it claims to be, automatically, every time it connects. If the check fails it stops rather than sending your prompts unprotected.\n\nYou do not have to take our word for it. The verification page shows whether the check passed right now, what was checked, and lets you download the raw proof to verify independently. It never shows your prompts.\n\nPoint any OpenAI-compatible app on this Dappnode at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Same key, same models, same prices. Some apps, such as Hermes Agent, have a private mode switch that does this for you.\n\nNote: Auto Router (nexus/auto) and PII masking do not work through the proxy yet.", "type": "dncore", "backup": [ { @@ -45,6 +45,11 @@ }, "license": "MIT", "warnings": { - "onInstall": "This package protects inference bodies from the local Nexus proxy to the attested Nexus Gateway. The DAppNode host and internal package network remain trusted. Do not expose port 3301 publicly." + "onInstall": "Your prompts get encrypted so only the TEE running Nexus can read them. The proxy verifies that TEE automatically and stops rather than sending prompts unprotected if it cannot. Auto Router and PII masking do not work through the proxy yet. Keep port 3301 on the internal network." + }, + "links": { + "ui": "http://nexus-proxy.dappnode.private:3301/verification", + "homepage": "https://nexus.dappnode.com", + "docs": "https://github.com/dappnode/DNP_NEXUS_PROXY#readme" } } diff --git a/getting-started.md b/getting-started.md new file mode 100644 index 0000000..ada5710 --- /dev/null +++ b/getting-started.md @@ -0,0 +1,49 @@ +# Nexus Proxy + +Your prompts normally get decrypted on the way to Nexus. This package stops +that: it encrypts them so only the **TEE** — the trusted execution environment +Nexus runs inside — can read them. Not us, not Dappnode, nobody in between. + +It also checks that the TEE really is what it claims to be, automatically, +every time it connects. If that check fails it stops rather than sending your +prompts unprotected. + +## Check it yourself + +You don't have to take our word for it: + +**[Open the verification page](http://nexus-proxy.dappnode.private:3301/verification)** + +It shows whether the check passed right now, what was checked, and lets you +download the raw proof to verify independently. It never shows your prompts. + +## Use it + +Point any OpenAI-compatible app on this Dappnode at: + +```text +Base URL: http://nexus-proxy.dappnode.private:3301/v1 +API key: your normal Nexus API key +``` + +Nothing else changes — same key, same models, same prices. + +Some Dappnode apps have a **private mode** switch that does this for you. +Hermes Agent is one. + +## Good to know + +- **Auto Router (`nexus/auto`) does not work through the proxy yet.** Pick a + specific model instead. +- **PII masking does not apply.** The masking service sits outside the TEE and + the TEE is not allowed to reach it, so a key with PII masking on will not get + masking here. +- **It fails closed.** If it cannot verify the TEE, requests stop working + rather than quietly falling back to the unprotected path. That is deliberate. +- **Keep port 3301 internal.** Do not publish it to the internet. + +## Learn more + +The [README](https://github.com/dappnode/DNP_NEXUS_PROXY) covers exactly what +is and is not protected, how the trust policy follows signed Gateway releases, +and how to re-check the proof with independent tooling. From c9ef11ae95705d0d5ed4fe3b5026a69fcf0c2488 Mon Sep 17 00:00:00 2001 From: Marketen Date: Wed, 9 Sep 2026 14:20:09 +0200 Subject: [PATCH 2/3] Say what private mode gives you, not what you lose without it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs opened by describing the problem — prompts get decrypted on the way to Nexus — and positioned the package as the fix. That frames the default as a flaw and reads as a warning about a state the reader did not choose. Lead with what this gives you instead: Encrypts your Nexus prompts so only the TEE — the trusted execution environment Nexus runs inside — can read them. No mention of what happens without it, anywhere. Also drops "yet" from the Auto Router and PII masking note. Neither has a committed fix, so "yet" promises something nobody has agreed to ship. And shorter throughout: README 159 -> 110 lines, getting-started 49 -> 34. Co-Authored-By: Claude Opus 5 --- README.md | 175 +++++++++++++++--------------------------- dappnode_package.json | 4 +- getting-started.md | 41 ++++------ 3 files changed, 78 insertions(+), 142 deletions(-) diff --git a/README.md b/README.md index 971972f..a839314 100644 --- a/README.md +++ b/README.md @@ -1,18 +1,11 @@ # Nexus Proxy -Your prompts normally get decrypted on the way to Nexus. This Dappnode package -stops that: it encrypts them so only the **TEE** — the trusted execution +Encrypts your Nexus prompts so only the **TEE** — the trusted execution environment Nexus runs inside — can read them. Not us, not Dappnode, nobody in -between. - -It also checks that the TEE really is what it claims to be, automatically, on -every connection. If that check fails it stops rather than sending your prompts -unprotected. +between. It verifies the TEE automatically on every connection. ## Use it -Point any OpenAI-compatible app on this Dappnode at: - ```text Base URL: http://nexus-proxy.dappnode.private:3301/v1 API key: your normal Nexus API key @@ -27,125 +20,83 @@ switch that does this for you — Hermes Agent is one. http://nexus-proxy.dappnode.private:3301/verification ``` -The page shows whether the check passed right now, what was checked, and lets -you download the raw proof so you can verify it with independent tooling. It -never shows your prompts. +What was checked, right now, plus the raw proof to verify with independent +tooling. It never shows your prompts. ## Good to know -- **Auto Router (`nexus/auto`) does not work through the proxy yet.** Pick a - specific model instead. -- **PII masking does not apply.** The masking service runs outside the TEE and - the TEE is not allowed to reach it, so a key with masking enabled will not - get masking here. -- **It fails closed.** If the TEE cannot be verified, requests stop rather than - quietly falling back to the unprotected path. -- **Keep port 3301 internal.** Do not publish it to the host or the internet. +- Auto Router (`nexus/auto`) and PII masking do not work through the proxy. + Pick a specific model. +- If the TEE cannot be verified, requests stop. That is deliberate. +- Keep port 3301 on the internal network. --- -# Learn more - -Everything below is detail. The four points above are the whole story for most -people. - -## What is and is not protected +# Reference -Protected: the contents of your prompts and the model's replies, from this -proxy to the verified Nexus Gateway inside the TEE. +## Scope -Not protected: +Encrypted: prompt and reply bodies, from this proxy to the verified Gateway +inside the TEE. -- **The hop from your app to this proxy.** That is ordinary HTTP on the - Dappnode internal network. You are trusting the Dappnode host, this package, - and that network. -- **Metadata.** Request method, path, headers, body length, timing and your - bearer API key are all still visible to the network in front of Nexus. -- **What the model provider does afterwards.** This package makes no claim - about a downstream inference provider. +Outside that: the hop from your app to this proxy (ordinary HTTP on the +Dappnode internal network), request metadata — method, path, headers, sizes, +timing and your bearer key — and whatever the model provider does downstream. ## Endpoints -| Route | Confidential | Notes | +| Route | Encrypted | Notes | |---|---|---| | `POST /v1/chat/completions` | yes | Streaming supported | -| `GET /v1/models` | no | Public catalog, see below | +| `GET /v1/models` | no | Public catalog | | `GET /healthz` | n/a | Readiness | | `GET /verification` | n/a | The page above | -The model catalog is the one route that is deliberately **not** confidential. -It is public, unauthenticated, cacheable data with no prompt, completion or -credential in it, so the proxy passes it through over ordinary TLS and does not -forward your `Authorization` header. Those requests are not counted on the -verification page, because nothing about them crossed the protected channel. -Add `--model-catalog=false` to remove the route. - -## What the verification page records - -No prompt or completion content, ever. The ledger holds verification evidence -plus per-request identifiers, timing and sizes. The on-disk format cannot -express a prompt or a reply. - -History is written to the `verification_state` volume at -`/var/lib/nexus-proxy/verification.json`, so it survives restarts and is -included in package backups. Because the page is served on the proxy port, -anything on the Dappnode internal network can read this metadata. Add -`--verification-ui=false` to remove the page and its API, or drop -`--state-file` to keep history in memory only. - -## How the proxy knows what to trust - -It does not ship a fixed list of measurements. It derives them from the most -recent Gateway releases, each signed during the Gateway release workflow with a -Sigstore certificate issued to that workflow's GitHub identity. Only a -signature from that exact identity is accepted, so the download itself is not -trusted: GitHub is a CDN here, and a swapped or edited release is rejected -rather than believed. - -That is why this package no longer has to be republished for every Gateway -release, and why an installed proxy can no longer be stranded on measurements -that predate the deployed TEE. - -What gets checked has not changed. Measurements are still compared against the -TEE's live attestation, and the body-encryption contract is compiled into the -SDK: a signed release may say which build to trust, never what protection that -build owes you. - -A newly deployed Gateway is picked up **on first contact**, not on a timer. A -release the current policy has never heard of is exactly what a new deployment -looks like, so the proxy re-derives its policy and verifies again within the -same request. Nothing has to be pushed to the node, which matters because -Dappnodes sit behind NAT. An hourly background refresh is a backstop on top. - -If neither the network nor the cache produces a verified policy, the proxy -refuses to start rather than falling back to something older. -`--trust-policy-cache` keeps the signed material from the last successful fetch -on the `verification_state` volume, and every signature is re-verified on load, -so a tampered cache is rejected rather than believed. - -This package pins the SDK commit (`UPSTREAM_VERSION` in `docker-compose.yml` -and `dappnode_package.json`), the Gateway origin -`https://nexus-api-tee.dappnode.com`, and the Gateway release-workflow signing -identity, which is compiled into the SDK. - -### Network requirement - -Outbound HTTPS to `api.github.com` and `objects.githubusercontent.com` at -startup, on meeting an unknown Gateway release, and hourly. A node that cannot -reach them starts only if its cache already holds a verified policy. - -## Declaring the dependency - -Applications can declare the package once and then follow Gateway releases -automatically, without either the application or this package being -republished: +The catalog is public, unauthenticated data with no prompt or credential in it, +so it goes over ordinary TLS and the `Authorization` header is not forwarded. +Those requests are not counted on the verification page. `--model-catalog=false` +removes the route. + +## Verification history + +No prompt or reply content, ever — only verification evidence and per-request +identifiers, timing and sizes. The on-disk format cannot express a prompt. + +Stored on the `verification_state` volume at +`/var/lib/nexus-proxy/verification.json`, so it survives restarts and is in +package backups. Anything on the Dappnode internal network can read it. +`--verification-ui=false` removes the page and its API; dropping `--state-file` +keeps history in memory only. + +## Trust policy + +Measurements are derived from the most recent Gateway releases, each signed +during the Gateway release workflow with a Sigstore certificate issued to that +workflow's GitHub identity. Only that exact identity is accepted, so the +download is not trusted — GitHub is a CDN here, and a swapped release is +rejected. + +A new Gateway is picked up **on first contact**, not on a timer: a release the +policy has never seen is what a new deployment looks like, so the proxy +re-derives and verifies within the same request. Nothing needs pushing to the +node, which matters behind NAT. An hourly refresh is a backstop. + +Fail-closed: if neither the network nor the cache produces a verified policy, +the proxy refuses to start. `--trust-policy-cache` keeps the signed material on +the `verification_state` volume and every signature is re-verified on load. + +Pinned here: the SDK commit (`UPSTREAM_VERSION`), the Gateway origin +`https://nexus-api-tee.dappnode.com`, and the release-workflow signing identity +(compiled into the SDK). + +Needs outbound HTTPS to `api.github.com` and `objects.githubusercontent.com` at +startup, on meeting an unknown release, and hourly. Without them it starts only +if the cache already holds a verified policy. + +## Dependency ```json -{ - "dependencies": { - "nexus-proxy.dnp.dappnode.eth": "^0.1.0" - } -} +{ "dependencies": { "nexus-proxy.dnp.dappnode.eth": "^0.1.0" } } ``` ## Build @@ -154,6 +105,6 @@ republished: docker compose build ``` -The image builds the SDK from a full Git commit, verifies the checked-out -revision matches, and runs as an unprivileged user in a minimal runtime image. -`dappnode-nexus-sdk` is public, so no credentials are needed. +Builds the SDK from a pinned commit, verifies the checked-out revision, and +runs unprivileged in a minimal image. `dappnode-nexus-sdk` is public, so no +credentials are needed. diff --git a/dappnode_package.json b/dappnode_package.json index 924c893..118f9b3 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -5,7 +5,7 @@ "upstreamRepo": "dappnode/dappnode-nexus-sdk", "upstreamArg": "UPSTREAM_VERSION", "shortDescription": "Keep your Nexus prompts private, and verify it yourself", - "description": "Your prompts normally get decrypted on the way to Nexus. This package stops that: it encrypts them so only the TEE (trusted execution environment) that Nexus runs inside can read them — not us, not Dappnode, nobody in between.\n\nIt checks that the TEE really is what it claims to be, automatically, every time it connects. If the check fails it stops rather than sending your prompts unprotected.\n\nYou do not have to take our word for it. The verification page shows whether the check passed right now, what was checked, and lets you download the raw proof to verify independently. It never shows your prompts.\n\nPoint any OpenAI-compatible app on this Dappnode at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Same key, same models, same prices. Some apps, such as Hermes Agent, have a private mode switch that does this for you.\n\nNote: Auto Router (nexus/auto) and PII masking do not work through the proxy yet.", + "description": "Encrypts your Nexus prompts so only the TEE (trusted execution environment) that Nexus runs inside can read them — not us, not Dappnode, nobody in between. It verifies the TEE automatically on every connection.\n\nYou do not have to take our word for it: the verification page shows what was checked, right now, and lets you download the raw proof to verify independently. It never shows your prompts.\n\nPoint any OpenAI-compatible app on this Dappnode at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Same key, same models, same prices. Some apps, such as Hermes Agent, have a private mode switch that does this for you.\n\nAuto Router (nexus/auto) and PII masking do not work through the proxy.", "type": "dncore", "backup": [ { @@ -45,7 +45,7 @@ }, "license": "MIT", "warnings": { - "onInstall": "Your prompts get encrypted so only the TEE running Nexus can read them. The proxy verifies that TEE automatically and stops rather than sending prompts unprotected if it cannot. Auto Router and PII masking do not work through the proxy yet. Keep port 3301 on the internal network." + "onInstall": "Point your apps at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Auto Router and PII masking do not work through the proxy. If the TEE cannot be verified, requests stop. Keep port 3301 on the internal network." }, "links": { "ui": "http://nexus-proxy.dappnode.private:3301/verification", diff --git a/getting-started.md b/getting-started.md index ada5710..32162ab 100644 --- a/getting-started.md +++ b/getting-started.md @@ -1,21 +1,16 @@ # Nexus Proxy -Your prompts normally get decrypted on the way to Nexus. This package stops -that: it encrypts them so only the **TEE** — the trusted execution environment -Nexus runs inside — can read them. Not us, not Dappnode, nobody in between. +Encrypts your Nexus prompts so only the **TEE** — the trusted execution +environment Nexus runs inside — can read them. Not us, not Dappnode, nobody in +between. -It also checks that the TEE really is what it claims to be, automatically, -every time it connects. If that check fails it stops rather than sending your -prompts unprotected. +It verifies the TEE automatically on every connection. ## Check it yourself -You don't have to take our word for it: - **[Open the verification page](http://nexus-proxy.dappnode.private:3301/verification)** - -It shows whether the check passed right now, what was checked, and lets you -download the raw proof to verify independently. It never shows your prompts. +— what was checked, right now, plus the raw proof to verify independently. It +never shows your prompts. ## Use it @@ -26,24 +21,14 @@ Base URL: http://nexus-proxy.dappnode.private:3301/v1 API key: your normal Nexus API key ``` -Nothing else changes — same key, same models, same prices. - -Some Dappnode apps have a **private mode** switch that does this for you. -Hermes Agent is one. +Same key, same models, same prices. Some apps have a **private mode** switch +that does this for you — Hermes Agent is one. ## Good to know -- **Auto Router (`nexus/auto`) does not work through the proxy yet.** Pick a - specific model instead. -- **PII masking does not apply.** The masking service sits outside the TEE and - the TEE is not allowed to reach it, so a key with PII masking on will not get - masking here. -- **It fails closed.** If it cannot verify the TEE, requests stop working - rather than quietly falling back to the unprotected path. That is deliberate. -- **Keep port 3301 internal.** Do not publish it to the internet. - -## Learn more +- Auto Router (`nexus/auto`) and PII masking do not work through the proxy. + Pick a specific model. +- If the TEE cannot be verified, requests stop. That is deliberate. +- Keep port 3301 on the internal network. -The [README](https://github.com/dappnode/DNP_NEXUS_PROXY) covers exactly what -is and is not protected, how the trust policy follows signed Gateway releases, -and how to re-check the proof with independent tooling. +[Full documentation](https://github.com/dappnode/DNP_NEXUS_PROXY#readme) From ecdee44c76fe82b85bee3924820a755cda5de775 Mon Sep 17 00:00:00 2001 From: Marketen Date: Wed, 9 Sep 2026 14:26:29 +0200 Subject: [PATCH 3/3] Recommend private/ models for the whole path The proxy protects the prompt as far as the Gateway. A model whose id starts with private/ is reached over an attested, encrypted transport that fails closed, so with the proxy in front the prompt is protected end to end. That is the combination worth telling people about. Says private/ rather than naming the provider: the provider may change, the id prefix is the stable thing. Co-Authored-By: Claude Opus 5 --- README.md | 12 ++++++++++-- dappnode_package.json | 2 +- getting-started.md | 6 ++++++ 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a839314..3580a2f 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ API key: your normal Nexus API key Same key, same models, same prices. Some Dappnode apps have a **private mode** switch that does this for you — Hermes Agent is one. +For the whole path, pick a model whose id starts with **`private/`**. Those run +inside a TEE too, so your prompt stays encrypted from this proxy to Nexus and +from Nexus to the model. + ## Check it yourself ```text @@ -39,9 +43,13 @@ tooling. It never shows your prompts. Encrypted: prompt and reply bodies, from this proxy to the verified Gateway inside the TEE. +With a **`private/`** model, that continues past Nexus: the Gateway reaches +those models over an attested, encrypted transport that fails closed, so the +prompt is protected end to end. + Outside that: the hop from your app to this proxy (ordinary HTTP on the -Dappnode internal network), request metadata — method, path, headers, sizes, -timing and your bearer key — and whatever the model provider does downstream. +Dappnode internal network) and request metadata — method, path, headers, sizes, +timing and your bearer key. ## Endpoints diff --git a/dappnode_package.json b/dappnode_package.json index 118f9b3..14bb879 100644 --- a/dappnode_package.json +++ b/dappnode_package.json @@ -5,7 +5,7 @@ "upstreamRepo": "dappnode/dappnode-nexus-sdk", "upstreamArg": "UPSTREAM_VERSION", "shortDescription": "Keep your Nexus prompts private, and verify it yourself", - "description": "Encrypts your Nexus prompts so only the TEE (trusted execution environment) that Nexus runs inside can read them — not us, not Dappnode, nobody in between. It verifies the TEE automatically on every connection.\n\nYou do not have to take our word for it: the verification page shows what was checked, right now, and lets you download the raw proof to verify independently. It never shows your prompts.\n\nPoint any OpenAI-compatible app on this Dappnode at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Same key, same models, same prices. Some apps, such as Hermes Agent, have a private mode switch that does this for you.\n\nAuto Router (nexus/auto) and PII masking do not work through the proxy.", + "description": "Encrypts your Nexus prompts so only the TEE (trusted execution environment) that Nexus runs inside can read them — not us, not Dappnode, nobody in between. It verifies the TEE automatically on every connection.\n\nYou do not have to take our word for it: the verification page shows what was checked, right now, and lets you download the raw proof to verify independently. It never shows your prompts.\n\nPoint any OpenAI-compatible app on this Dappnode at http://nexus-proxy.dappnode.private:3301/v1 with your normal Nexus API key. Same key, same models, same prices. Some apps, such as Hermes Agent, have a private mode switch that does this for you.\n\nFor the whole path, pick a model whose id starts with private/ — those run inside a TEE too, so your prompt stays encrypted from the proxy to Nexus and from Nexus to the model.\n\nAuto Router (nexus/auto) and PII masking do not work through the proxy.", "type": "dncore", "backup": [ { diff --git a/getting-started.md b/getting-started.md index 32162ab..111128e 100644 --- a/getting-started.md +++ b/getting-started.md @@ -24,6 +24,12 @@ API key: your normal Nexus API key Same key, same models, same prices. Some apps have a **private mode** switch that does this for you — Hermes Agent is one. +## Get the most out of it + +Pick a model whose id starts with **`private/`**. Those run inside a TEE too, +so your prompt stays encrypted the whole way — from this proxy to Nexus, and +from Nexus to the model. + ## Good to know - Auto Router (`nexus/auto`) and PII masking do not work through the proxy.