From 42b2841945848b02d7a8880efd6cef8174276437 Mon Sep 17 00:00:00 2001 From: helix-nine <267227783+helix-nine@users.noreply.github.com> Date: Tue, 11 Aug 2026 10:59:50 -0600 Subject: [PATCH 1/3] bump upstream to 0.4.1, add the status page UI, fix CI branch triggers MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Community-registry audit ahead of listing. Upstream 0.4.1 renames the model catalog (private/kimi-k2-6 → private/kimi-k3, drops qwen3-vl-30b) and serves a status page at GET /, so the package was documenting a stale model list and hiding a whole surface. Export that page as a `ui` interface alongside the existing `api` on one host, and unmask the API interface — its URL carries no credentials, so masking hid the address for nothing. PPQ_DATA_DIR stays unset deliberately. With it set, upstream persists a browser-entered key to its own config.json while the StartOS-supplied PPQ_API_KEY still wins at every restart, silently reverting the user. StartOS owns the key via the action; the status page's form renders disabled. CI never ran: build.yml's PR target and tagAndRelease.yml's push trigger both named `master` on a repo whose only branch is `main`. Point them at `main` and reset all three workflows to the package template, dropping the guard job retired in start-technologies@ed0dca2. packageRepo now names the Start9-Community fork, which is where CI runs, where the org's registry variables live, and where releases are cut. Also: drop three .catch handlers on file-model reads, which swallowed a genuine read failure into "no key configured" — readOnce already returns null for a missing file; pass null rather than an empty Mounts for the unmounted subcontainer; inline two single-use interface consts; and rewrite README/instructions against the writing guides, fixing a YAML block that claimed a /data mount the package deliberately does not make. --- .github/workflows/build.yml | 4 +- .github/workflows/release.yml | 14 ---- .github/workflows/tagAndRelease.yml | 16 +---- README.md | 56 ++++++++++----- TODO.md | 13 ++-- UPDATING.md | 24 ++++--- instructions.md | 51 +++++++++---- ppq-private-mode-proxy | 2 +- startos/actions/configureApiKey.ts | 23 +++--- startos/i18n/dictionaries/default.ts | 22 +++--- startos/i18n/dictionaries/translations.ts | 88 ++++++++++++----------- startos/init/taskConfigureApiKey.ts | 7 +- startos/interfaces.ts | 29 +++++--- startos/main.ts | 10 ++- startos/manifest/i18n.ts | 9 ++- startos/manifest/index.ts | 2 +- startos/versions/current.ts | 2 +- 17 files changed, 204 insertions(+), 168 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6e1a7e4..b8a32f4 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -4,7 +4,7 @@ on: workflow_dispatch: pull_request: paths-ignore: ['*.md'] - branches: ['master'] + branches: ['main'] concurrency: group: ${{ github.workflow }}-${{ github.head_ref || github.ref }} @@ -14,6 +14,4 @@ jobs: build: if: github.event.pull_request.draft == false uses: Start9Labs/start-technologies/.github/workflows/build.yml@master - # with: - # FREE_DISK_SPACE: true # No DEV_KEY — a PR build doesn't publish, so it doesn't need the signing key. diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 9defaba..6dcef4a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -6,23 +6,9 @@ on: - 'v*.*' jobs: - guard: - runs-on: ubuntu-latest - outputs: - id: ${{ steps.read.outputs.id }} - steps: - - uses: actions/checkout@v4 - - id: read - run: | - id="$(awk -F"'" '/id:/ {print $2; exit}' startos/manifest/index.ts)" - echo "id=$id" >> "$GITHUB_OUTPUT" - release: - needs: guard - if: needs.guard.outputs.id != 'hello-world' uses: Start9Labs/start-technologies/.github/workflows/release.yml@master with: - # FREE_DISK_SPACE: true RELEASE_REGISTRY: ${{ vars.RELEASE_REGISTRY }} S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }} secrets: diff --git a/.github/workflows/tagAndRelease.yml b/.github/workflows/tagAndRelease.yml index 50858c3..c4031d3 100644 --- a/.github/workflows/tagAndRelease.yml +++ b/.github/workflows/tagAndRelease.yml @@ -2,7 +2,7 @@ name: Tag and Release on: push: - branches: ['master'] + branches: ['main'] paths-ignore: ['*.md'] concurrency: @@ -10,24 +10,10 @@ concurrency: cancel-in-progress: true jobs: - guard: - runs-on: ubuntu-latest - outputs: - id: ${{ steps.read.outputs.id }} - steps: - - uses: actions/checkout@v4 - - id: read - run: | - id="$(awk -F"'" '/id:/ {print $2; exit}' startos/manifest/index.ts)" - echo "id=$id" >> "$GITHUB_OUTPUT" - tag: - needs: guard - if: needs.guard.outputs.id != 'hello-world' uses: Start9Labs/start-technologies/.github/workflows/tagAndRelease.yml@master with: REFERENCE_REGISTRY: ${{ vars.REFERENCE_REGISTRY }} - # FREE_DISK_SPACE: true RELEASE_REGISTRY: ${{ vars.RELEASE_REGISTRY }} S3_S9PKS_BASE_URL: ${{ vars.S3_S9PKS_BASE_URL }} secrets: diff --git a/README.md b/README.md index e6d46b3..543807b 100644 --- a/README.md +++ b/README.md @@ -55,35 +55,46 @@ variables only. ## Installation and First-Run Flow On install, a critical task prompts for a PPQ.AI API key. The service cannot -start until the key is provided (upstream exits immediately without -`PPQ_API_KEY`). There is no other setup. +start until the key is provided (the task blocks startup, and upstream exits +immediately when neither `PPQ_API_KEY` nor `PPQ_DATA_DIR` is set). There is no +other setup. ## Configuration Management -All upstream configuration is via environment variables; StartOS manages them -from `config.json`: +Nothing is upstream-managed: the proxy has no config file of its own and takes +every setting from an environment variable, all of which StartOS supplies from +`config.json`. - `PPQ_API_KEY` — set from the **Configure PPQ API Key** action - `DEBUG` — set from the same action's Verbose Logging toggle - `HOST` — fixed to `0.0.0.0` (container binding) -- `PORT` — fixed to `8787` +- `PORT` — fixed to 8787 - `PPQ_API_BASE` — not set (upstream default `https://api.ppq.ai`) +- `PPQ_DATA_DIR` — deliberately not set (see Limitations) Changing settings restarts the daemon (values are read reactively). ## Network Access and Interfaces -One interface, `api` (port 8787, HTTP): the upstream OpenAI-compatible API, -shown as a copyable connection string. Endpoints: `GET /health`, -`GET /v1/models`, `POST /v1/chat/completions` (OpenAI format), -`POST /v1/messages` (Anthropic format). Availability on LAN/Tor is decided by -the user from the interface panel. +Two interfaces on one HTTP host, port 8787, both served by the proxy: + +- **Status Page** (`ui`) — upstream's server-rendered page at `/`: attestation + state (enclave host and code fingerprint), API-key status, the private model + list, and client setup snippets. +- **OpenAI-Compatible API** (`api`) — the same origin, shown as a copyable + connection string for AI clients. Endpoints: `GET /health`, + `GET /v1/models`, `POST /v1/chat/completions` (OpenAI format), + `POST /v1/messages` (Anthropic format). + +Availability on LAN/Tor is decided by the user from the interface panel. ## Actions (StartOS UI) -- **Configure PPQ API Key** (`configure-api-key`) — sets the PPQ.AI API key - (masked, never echoed back) and the Verbose Logging toggle. Available at any - service status. Also the target of the critical first-run task. +- **Configure PPQ API Key** (`configure-api-key`) — visible and enabled at any + service status. Inputs: the PPQ.AI API key (masked; left blank it keeps the + key already saved, and it is never echoed back into the form) and the Verbose + Logging toggle. No result output. Also the target of the critical first-run + task. ## Backups and Restore @@ -108,16 +119,22 @@ None. 1. This service is a client-side encryption proxy, not a self-hosted model server: inference runs remotely in PPQ.AI's attested TEE enclaves, and a funded [PPQ.AI](https://ppq.ai) API key is required (pay-per-query). -2. The upstream OpenClaw-plugin mode is not packaged; only the standalone +2. The API-key form on upstream's status page is inactive here. StartOS is the + single source of truth for the key, so `PPQ_DATA_DIR` is left unset: with + it set, upstream would persist a browser-entered key to its own + `config.json` while the StartOS-supplied `PPQ_API_KEY` still won at every + restart, silently reverting it. Use the **Configure PPQ API Key** action. +3. The upstream OpenClaw-plugin mode is not packaged; only the standalone proxy runs on StartOS. -3. The bind address and port are fixed (`0.0.0.0:8787` inside the container); - upstream's `HOST`/`PORT`/`PPQ_API_BASE` variables are not user-configurable. +4. The bind address and port are fixed inside the container; upstream's + `HOST`/`PORT`/`PPQ_API_BASE` variables are not user-configurable. ## What Is Unchanged from Upstream - All API endpoints, request/response formats, and streaming behavior - The encryption and attestation flow (EHBP transport via the `tinfoil` client) - Model catalog and per-request `Authorization: Bearer` key override +- The status page rendered at `/`, minus its API-key form ## Contributing @@ -131,9 +148,12 @@ See [AGENTS.md](AGENTS.md). package_id: ppq-private-mode architectures: [x86_64, aarch64] volumes: - main: /data + main: null # host-side config.json only; not mounted into the container ports: - api: 8787 + main: 8787 # one host serving both interfaces +interfaces: + - ui + - api dependencies: none startos_managed_env_vars: - PPQ_API_KEY diff --git a/TODO.md b/TODO.md index d287cc6..3ef3ade 100644 --- a/TODO.md +++ b/TODO.md @@ -1,9 +1,8 @@ # TODO — remaining work before release -- [x] Verified on StartOS 0.4.0 (aarch64, QEMU/HVF VM): sideload install, - critical first-run task, Configure PPQ API Key action, attestation-gated - health check, OpenAI chat completion through the exported TLS interface, - logs, stop/start persistence, uninstall, and backup/restore to a disk - target (service restores with its key, no re-prompt). -- [ ] Submit to the Community Registry (email submissions@start9.com with a - link to this repo). +- [ ] Run one live inference request with a funded PPQ.AI key. Everything up to + the enclave is verified (attestation, encrypted forward, error handling), + but no request has yet been billed end-to-end against a real key. +- [ ] Re-run backup and restore on a StartOS box: back up, uninstall, restore, + and confirm the service comes back with its key and raises no + configuration task. diff --git a/UPDATING.md b/UPDATING.md index 9425cd5..ac086d5 100644 --- a/UPDATING.md +++ b/UPDATING.md @@ -2,14 +2,15 @@ Upstream is [PayPerQ/ppq-private-mode-proxy](https://github.com/PayPerQ/ppq-private-mode-proxy), vendored as the `ppq-private-mode-proxy` git submodule and built from its own -`Dockerfile`. The package version tracks upstream's `package.json` version. +`Dockerfile`. The package version tracks upstream's `package.json` version, +which upstream tags as `v`. ## Determining the upstream version ```bash -git -C ppq-private-mode-proxy fetch origin -git -C ppq-private-mode-proxy log --oneline HEAD..origin/main # anything new? -jq -r .version ppq-private-mode-proxy/package.json # current pin +git -C ppq-private-mode-proxy fetch origin --tags +git -C ppq-private-mode-proxy describe --tags HEAD # current pin +git -C ppq-private-mode-proxy tag --sort=-v:refname | head # latest released ``` The packaged version lives in `startos/versions/current.ts` (`version: @@ -17,9 +18,14 @@ The packaged version lives in `startos/versions/current.ts` (`version: ## Applying the bump -1. Advance the submodule: `git -C ppq-private-mode-proxy checkout origin/main` -2. Update `version` in `startos/versions/current.ts` to the new upstream +1. Advance the submodule: `git -C ppq-private-mode-proxy checkout v` +2. Read the upstream diff (`git -C ppq-private-mode-proxy diff ..`) + for anything the package has to follow — new or renamed environment + variables, changed endpoints, a changed bind/attestation order (the health + check depends on the port being bound only after attestation), or a model + catalog change that the docs name. +3. Update `version` in `startos/versions/current.ts` to the new upstream `package.json` version with revision `:0` (bump only the revision for - packaging-only changes), and write release notes. -3. Rebuild and test: `make x86` (or `make arm`), install, verify attestation - completes and a `/v1/models` request succeeds. + packaging-only changes), and write release notes in every locale. +4. Rebuild and test: `make x86` (or `make arm`), install, verify attestation + completes, the Status Page loads, and a `/v1/models` request succeeds. diff --git a/instructions.md b/instructions.md index 36881a7..de33fa6 100644 --- a/instructions.md +++ b/instructions.md @@ -5,21 +5,38 @@ - [Upstream proxy documentation](https://github.com/PayPerQ/ppq-private-mode-proxy) — endpoints, client examples, and how the encryption works - [PPQ.AI API docs](https://ppq.ai/api-docs) — creating an API key and funding your account +## What you get on StartOS + +A local endpoint your AI clients talk to instead of talking to a model provider +directly. Everything sent through it is encrypted on your server and only +decrypted inside an attested hardware enclave, so neither PPQ.AI nor the model +host can read your queries. + +Two interfaces share one address: + +- **Status Page** — a web page showing whether enclave attestation succeeded, + which private models are available, and how to point a client at the proxy. +- **OpenAI-Compatible API** — the same address, ready to copy into a client. + +The only thing the service stores is your PPQ.AI API key and the logging +setting. + ## Getting set up -1. When the service is installed, you will be prompted to run **Configure PPQ - API Key**. Paste an API key from [ppq.ai](https://ppq.ai) (create one under - **Settings → API Keys** and fund the account — usage is billed per query to - this key). +1. You will be prompted to run **Configure PPQ API Key**. Paste an API key from + [ppq.ai](https://ppq.ai) — create one under **Settings → API Keys** and fund + the account, since usage is billed per query to this key. 2. The service starts and performs a cryptographic attestation of the remote enclave. The health check reports ready once attestation is verified — usually within a few seconds. -3. Copy the **OpenAI-Compatible API** address from the service's interface - panel. That is the URL you point your AI clients at. +3. Open the **Status Page** to confirm attestation succeeded, or copy the + **OpenAI-Compatible API** address to point a client at it. -## Using the proxy +## Using PPQ Private Mode -Point any OpenAI-compatible client at the interface address: +### Connecting a client + +Point any OpenAI-compatible client at the API address: ``` POST /v1/chat/completions @@ -34,16 +51,22 @@ export ANTHROPIC_BASE_URL="" export ANTHROPIC_MODEL="private/glm-5-2" ``` -`GET /v1/models` lists the available private models. Every -request is encrypted on your server before it leaves and is only decrypted -inside the attested enclave — neither PPQ.AI nor the model host can read your -queries. +`GET /v1/models` lists the available private models, and the +Status Page shows the same list. Requests are billed to your saved API key by default. To bill a different PPQ.AI key per request, pass it as an `Authorization: Bearer` header. -If you need to change the key or turn on verbose logging later, run -**Configure PPQ API Key** again from the service's Actions. +### Actions + +Run **Configure PPQ API Key** again whenever you want to replace the key or +turn verbose logging on or off. Leaving the key field blank keeps the key you +already saved. + +## Limitations + +The Status Page has its own "save API key" form upstream; it is inactive here, +because the key is managed by the **Configure PPQ API Key** action instead. Backups of this service include your saved API key, and restoring a backup restores it — keep that in mind when handling backup drives. diff --git a/ppq-private-mode-proxy b/ppq-private-mode-proxy index a6d0f81..3ba4ac9 160000 --- a/ppq-private-mode-proxy +++ b/ppq-private-mode-proxy @@ -1 +1 @@ -Subproject commit a6d0f8116bf58499e64dffa81136940f94db952d +Subproject commit 3ba4ac94316572cb124c6052004b1231c1a0e7c8 diff --git a/startos/actions/configureApiKey.ts b/startos/actions/configureApiKey.ts index 0ef1985..e285057 100644 --- a/startos/actions/configureApiKey.ts +++ b/startos/actions/configureApiKey.ts @@ -41,24 +41,19 @@ export const configureApiKey = sdk.Action.withInput( inputSpec, // Prefill: the API key is never echoed back into the form. - async ({ effects }) => { - const debug = await configJson - .read((c) => c.debug) - .once() - .catch(() => false) - return { debug: debug ?? false } - }, + async ({ effects }) => ({ + debug: (await configJson.read((c) => c.debug).once()) ?? false, + }), async ({ effects, input }) => { - const existingKey = await configJson - .read((c) => c.apiKey) - .once() - .catch(() => undefined) - - const apiKey = (input.apiKey ?? '').trim() || existingKey + const apiKey = + (input.apiKey ?? '').trim() || + (await configJson.read((c) => c.apiKey).once()) if (!apiKey) { throw new Error( - i18n('An API key is required. Create one at ppq.ai under Settings → API Keys.'), + i18n( + 'An API key is required. Create one at ppq.ai under Settings → API Keys.', + ), ) } diff --git a/startos/i18n/dictionaries/default.ts b/startos/i18n/dictionaries/default.ts index d8191be..c559ac3 100644 --- a/startos/i18n/dictionaries/default.ts +++ b/startos/i18n/dictionaries/default.ts @@ -7,18 +7,20 @@ const dict = { 'The proxy is ready — enclave attestation verified': 2, 'The proxy is not ready (enclave attestation pending)': 3, // interfaces.ts - 'OpenAI-Compatible API': 4, - 'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption': 5, + 'Status Page': 4, + 'Enclave attestation state, the available private models, and client setup snippets': 5, + 'OpenAI-Compatible API': 6, + 'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption': 7, // actions/configureApiKey.ts - 'PPQ.AI API Key': 6, - 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.': 7, - 'Verbose Logging': 8, - 'Log every request the proxy handles. Useful for troubleshooting.': 9, - 'Configure PPQ API Key': 10, - 'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 11, - 'An API key is required. Create one at ppq.ai under Settings → API Keys.': 12, + 'PPQ.AI API Key': 8, + 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.': 9, + 'Verbose Logging': 10, + 'Log every request the proxy handles. Useful for troubleshooting.': 11, + 'Configure PPQ API Key': 12, + 'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 13, + 'An API key is required. Create one at ppq.ai under Settings → API Keys.': 14, // init/taskConfigureApiKey.ts - 'Add your PPQ.AI API key to start the proxy': 13, + 'Add your PPQ.AI API key to start the proxy': 15, } as const /** diff --git a/startos/i18n/dictionaries/translations.ts b/startos/i18n/dictionaries/translations.ts index 39b6cbe..2fabe5c 100644 --- a/startos/i18n/dictionaries/translations.ts +++ b/startos/i18n/dictionaries/translations.ts @@ -6,63 +6,71 @@ export default { 1: 'Proxy cifrado', 2: 'El proxy está listo — atestación del enclave verificada', 3: 'El proxy no está listo (atestación del enclave pendiente)', - 4: 'API compatible con OpenAI', - 5: 'Apunta cualquier cliente SDK de OpenAI o Anthropic a esta URL para usar los modelos privados (TEE) de PPQ con cifrado de extremo a extremo', - 6: 'Clave API de PPQ.AI', - 7: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada.', - 8: 'Registro detallado', - 9: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.', - 10: 'Configurar clave API de PPQ', - 11: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.', - 12: 'Se requiere una clave API. Crea una en ppq.ai en Ajustes → Claves API.', - 13: 'Añade tu clave API de PPQ.AI para iniciar el proxy', + 4: 'Página de estado', + 5: 'Estado de la atestación del enclave, los modelos privados disponibles y fragmentos de configuración para clientes', + 6: 'API compatible con OpenAI', + 7: 'Apunta cualquier cliente SDK de OpenAI o Anthropic a esta URL para usar los modelos privados (TEE) de PPQ con cifrado de extremo a extremo', + 8: 'Clave API de PPQ.AI', + 9: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada.', + 10: 'Registro detallado', + 11: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.', + 12: 'Configurar clave API de PPQ', + 13: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.', + 14: 'Se requiere una clave API. Crea una en ppq.ai en Ajustes → Claves API.', + 15: 'Añade tu clave API de PPQ.AI para iniciar el proxy', }, de_DE: { 0: 'Starte PPQ Private Mode!', 1: 'Verschlüsselter Proxy', 2: 'Der Proxy ist bereit — Enklave-Attestierung verifiziert', 3: 'Der Proxy ist nicht bereit (Enklave-Attestierung ausstehend)', - 4: 'OpenAI-kompatible API', - 5: 'Verbinde jeden OpenAI- oder Anthropic-SDK-Client mit dieser URL, um die privaten (TEE) Modelle von PPQ mit Ende-zu-Ende-Verschlüsselung zu nutzen', - 6: 'PPQ.AI-API-Schlüssel', - 7: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten.', - 8: 'Ausführliche Protokollierung', - 9: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.', - 10: 'PPQ-API-Schlüssel konfigurieren', - 11: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.', - 12: 'Ein API-Schlüssel ist erforderlich. Erstelle einen auf ppq.ai unter Einstellungen → API-Schlüssel.', - 13: 'Füge deinen PPQ.AI-API-Schlüssel hinzu, um den Proxy zu starten', + 4: 'Statusseite', + 5: 'Status der Enklave-Attestierung, die verfügbaren privaten Modelle und Codeschnipsel zur Client-Einrichtung', + 6: 'OpenAI-kompatible API', + 7: 'Verbinde jeden OpenAI- oder Anthropic-SDK-Client mit dieser URL, um die privaten (TEE) Modelle von PPQ mit Ende-zu-Ende-Verschlüsselung zu nutzen', + 8: 'PPQ.AI-API-Schlüssel', + 9: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten.', + 10: 'Ausführliche Protokollierung', + 11: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.', + 12: 'PPQ-API-Schlüssel konfigurieren', + 13: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.', + 14: 'Ein API-Schlüssel ist erforderlich. Erstelle einen auf ppq.ai unter Einstellungen → API-Schlüssel.', + 15: 'Füge deinen PPQ.AI-API-Schlüssel hinzu, um den Proxy zu starten', }, pl_PL: { 0: 'Uruchamianie PPQ Private Mode!', 1: 'Szyfrowany proxy', 2: 'Proxy jest gotowy — atestacja enklawy zweryfikowana', 3: 'Proxy nie jest gotowy (atestacja enklawy w toku)', - 4: 'API zgodne z OpenAI', - 5: 'Skieruj dowolnego klienta SDK OpenAI lub Anthropic na ten URL, aby korzystać z prywatnych modeli (TEE) PPQ z szyfrowaniem end-to-end', - 6: 'Klucz API PPQ.AI', - 7: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz.', - 8: 'Szczegółowe logowanie', - 9: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.', - 10: 'Skonfiguruj klucz API PPQ', - 11: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.', - 12: 'Wymagany jest klucz API. Utwórz go na ppq.ai w Ustawienia → Klucze API.', - 13: 'Dodaj swój klucz API PPQ.AI, aby uruchomić proxy', + 4: 'Strona stanu', + 5: 'Stan atestacji enklawy, dostępne modele prywatne oraz fragmenty konfiguracji dla klientów', + 6: 'API zgodne z OpenAI', + 7: 'Skieruj dowolnego klienta SDK OpenAI lub Anthropic na ten URL, aby korzystać z prywatnych modeli (TEE) PPQ z szyfrowaniem end-to-end', + 8: 'Klucz API PPQ.AI', + 9: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz.', + 10: 'Szczegółowe logowanie', + 11: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.', + 12: 'Skonfiguruj klucz API PPQ', + 13: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.', + 14: 'Wymagany jest klucz API. Utwórz go na ppq.ai w Ustawienia → Klucze API.', + 15: 'Dodaj swój klucz API PPQ.AI, aby uruchomić proxy', }, fr_FR: { 0: 'Démarrage de PPQ Private Mode !', 1: 'Proxy chiffré', 2: "Le proxy est prêt — attestation de l'enclave vérifiée", 3: "Le proxy n'est pas prêt (attestation de l'enclave en attente)", - 4: 'API compatible OpenAI', - 5: "Pointez n'importe quel client SDK OpenAI ou Anthropic vers cette URL pour utiliser les modèles privés (TEE) de PPQ avec un chiffrement de bout en bout", - 6: 'Clé API PPQ.AI', - 7: 'Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée.', - 8: 'Journalisation détaillée', - 9: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.', - 10: 'Configurer la clé API PPQ', - 11: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.", - 12: 'Une clé API est requise. Créez-en une sur ppq.ai dans Paramètres → Clés API.', - 13: 'Ajoutez votre clé API PPQ.AI pour démarrer le proxy', + 4: "Page d'état", + 5: "État de l'attestation de l'enclave, les modèles privés disponibles et des extraits de configuration client", + 6: 'API compatible OpenAI', + 7: "Pointez n'importe quel client SDK OpenAI ou Anthropic vers cette URL pour utiliser les modèles privés (TEE) de PPQ avec un chiffrement de bout en bout", + 8: 'Clé API PPQ.AI', + 9: 'Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée.', + 10: 'Journalisation détaillée', + 11: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.', + 12: 'Configurer la clé API PPQ', + 13: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.", + 14: 'Une clé API est requise. Créez-en une sur ppq.ai dans Paramètres → Clés API.', + 15: 'Ajoutez votre clé API PPQ.AI pour démarrer le proxy', }, } satisfies Record diff --git a/startos/init/taskConfigureApiKey.ts b/startos/init/taskConfigureApiKey.ts index 766085a..a17492e 100644 --- a/startos/init/taskConfigureApiKey.ts +++ b/startos/init/taskConfigureApiKey.ts @@ -5,11 +5,8 @@ import { i18n } from '../i18n' // The proxy cannot start without a PPQ.AI API key, so a critical task blocks // startup until the user provides one. -export const taskConfigureApiKey = sdk.setupOnInit(async (effects, kind) => { - const apiKey = await configJson - .read((c) => c.apiKey) - .once() - .catch(() => undefined) +export const taskConfigureApiKey = sdk.setupOnInit(async (effects) => { + const apiKey = await configJson.read((c) => c.apiKey).once() if (!apiKey) { await sdk.action.createOwnTask(effects, configureApiKey, 'critical', { diff --git a/startos/interfaces.ts b/startos/interfaces.ts index 0da1f8c..783d5d7 100644 --- a/startos/interfaces.ts +++ b/startos/interfaces.ts @@ -2,30 +2,39 @@ import { sdk } from './sdk' import { apiPort } from './utils' import { i18n } from './i18n' -// Host id (the sdk.MultiHost.of group) — distinct from the interface id exported on it. -export const apiHostId = 'api-multi' -export const apiInterfaceId = 'api' - export const setInterfaces = sdk.setupInterfaces(async ({ effects }) => { - const apiMulti = sdk.MultiHost.of(effects, apiHostId) - const apiMultiOrigin = await apiMulti.bindPort(apiPort, { + const multi = sdk.MultiHost.of(effects, 'main') + const origin = await multi.bindPort(apiPort, { protocol: 'http', }) + const ui = sdk.createInterface(effects, { + name: i18n('Status Page'), + id: 'ui', + description: i18n( + 'Enclave attestation state, the available private models, and client setup snippets', + ), + type: 'ui', + masked: false, + schemeOverride: null, + username: null, + path: '', + query: {}, + }) const api = sdk.createInterface(effects, { name: i18n('OpenAI-Compatible API'), - id: apiInterfaceId, + id: 'api', description: i18n( 'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption', ), type: 'api', - masked: true, + masked: false, schemeOverride: null, username: null, path: '', query: {}, }) - const apiReceipt = await apiMultiOrigin.export([api]) + const receipt = await origin.export([ui, api]) - return [apiReceipt] + return [receipt] }) diff --git a/startos/main.ts b/startos/main.ts index 5ed427a..97271df 100644 --- a/startos/main.ts +++ b/startos/main.ts @@ -17,7 +17,7 @@ export const main = sdk.setupMain(async ({ effects }) => { subcontainer: sdk.SubContainer.of( effects, { imageId: 'proxy' }, - sdk.Mounts.of(), + null, 'proxy-sub', ), exec: { @@ -36,8 +36,12 @@ export const main = sdk.setupMain(async ({ effects }) => { display: i18n('Encrypted Proxy'), fn: () => sdk.healthCheck.checkPortListening(effects, apiPort, { - successMessage: i18n('The proxy is ready — enclave attestation verified'), - errorMessage: i18n('The proxy is not ready (enclave attestation pending)'), + successMessage: i18n( + 'The proxy is ready — enclave attestation verified', + ), + errorMessage: i18n( + 'The proxy is not ready (enclave attestation pending)', + ), }), }, requires: [], diff --git a/startos/manifest/i18n.ts b/startos/manifest/i18n.ts index b78a199..818617f 100644 --- a/startos/manifest/i18n.ts +++ b/startos/manifest/i18n.ts @@ -1,9 +1,12 @@ export const short = { en_US: 'End-to-end encrypted proxy for PPQ.AI private (TEE) AI models', - es_ES: 'Proxy cifrado de extremo a extremo para los modelos de IA privados (TEE) de PPQ.AI', - de_DE: 'Ende-zu-Ende-verschlüsselter Proxy für private (TEE) KI-Modelle von PPQ.AI', + es_ES: + 'Proxy cifrado de extremo a extremo para los modelos de IA privados (TEE) de PPQ.AI', + de_DE: + 'Ende-zu-Ende-verschlüsselter Proxy für private (TEE) KI-Modelle von PPQ.AI', pl_PL: 'Szyfrowany end-to-end proxy dla prywatnych modeli AI (TEE) PPQ.AI', - fr_FR: 'Proxy chiffré de bout en bout pour les modèles IA privés (TEE) de PPQ.AI', + fr_FR: + 'Proxy chiffré de bout en bout pour les modèles IA privés (TEE) de PPQ.AI', } export const long = { diff --git a/startos/manifest/index.ts b/startos/manifest/index.ts index 2ad2417..5d3d4f5 100644 --- a/startos/manifest/index.ts +++ b/startos/manifest/index.ts @@ -5,7 +5,7 @@ export const manifest = setupManifest({ id: 'ppq-private-mode', title: 'PPQ Private Mode', license: 'MIT', - packageRepo: 'https://github.com/PayPerQ/ppq-private-mode-startos', + packageRepo: 'https://github.com/Start9-Community/ppq-private-mode-startos', upstreamRepo: 'https://github.com/PayPerQ/ppq-private-mode-proxy', marketingUrl: 'https://ppq.ai', donationUrl: null, diff --git a/startos/versions/current.ts b/startos/versions/current.ts index e984012..ee0d6d9 100644 --- a/startos/versions/current.ts +++ b/startos/versions/current.ts @@ -2,7 +2,7 @@ import { IMPOSSIBLE, VersionInfo } from '@start9labs/start-sdk' export const current = VersionInfo.of({ // Tracks upstream ppq-private-mode-proxy (package.json version). - version: '0.3.2:0', + version: '0.4.1:0', releaseNotes: { en_US: 'Initial release for StartOS', es_ES: 'Lanzamiento inicial para StartOS', From 8397c7b1eb66814619d8c6aea2daf5ac92aebfc4 Mon Sep 17 00:00:00 2001 From: helix-nine <267227783+helix-nine@users.noreply.github.com> Date: Tue, 11 Aug 2026 12:52:59 -0600 Subject: [PATCH 2/3] adopt 0.4's persistent key store and browser setup form MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The earlier bump took 0.4.1 for its model catalog and status page but left PPQ_DATA_DIR unset, which disabled the key form the release exists to add. Enable it, and let the proxy own the key outright. PPQ_API_KEY is no longer passed. The volume's `proxy/` subpath mounts at /data as PPQ_DATA_DIR, so upstream's key store is the single source of truth: the Status Page and the Configure PPQ API Key action write the same config.json, and there is no StartOS-side copy to revert what the browser saved. A chown oneshot hands /data to the image's `node` user so the page can write there. Verbose Logging moves to store.json outside the mount, because upstream rewrites config.json wholesale when a key is saved and would drop it. main.ts watches config.json — upstream loads it once at startup, so the watch is what makes the action take effect: the write restarts the daemon, which reloads the file. A key saved on the page applies immediately and converges through the same restart. The task drops from critical to important. A critical task suspends every other control, so it would have left the user unable to start the service and reach the page's own form — and with PPQ_DATA_DIR set the proxy no longer exits keyless; it attests, serves the page, and answers 401 until a key exists. main.ts clears the task when a key appears, since saving on the page never touches the action that would clear it. The action's key field is now validated against upstream's own ^sk-[A-Za-z0-9]{16,64}$ shape and no longer refuses a blank submission, a key having become optional. --- README.md | 74 ++++++++++------ instructions.md | 40 +++++---- startos/actions/configureApiKey.ts | 28 +++--- startos/fileModels/config.json.ts | 10 +-- startos/fileModels/store.json.ts | 13 +++ startos/i18n/dictionaries/default.ts | 14 +-- startos/i18n/dictionaries/translations.ts | 56 ++++++------ startos/init/taskConfigureApiKey.ts | 12 ++- startos/main.ts | 102 ++++++++++++++-------- startos/utils.ts | 4 + 10 files changed, 213 insertions(+), 140 deletions(-) create mode 100644 startos/fileModels/store.json.ts diff --git a/README.md b/README.md index 543807b..e580eab 100644 --- a/README.md +++ b/README.md @@ -46,33 +46,52 @@ Architectures: `x86_64`, `aarch64`. ## Volume and Data Layout -One volume, `main`, holding only `config.json` (the StartOS-managed settings -file containing the API key and logging preference), read and written by the -SDK on the host side. The proxy itself is stateless and the volume is **not** -mounted into the container — configuration reaches the daemon via environment -variables only. +One volume, `main`, split so the container sees only what it owns: + +| Host path | Container path | Written by | +| ------------------- | ------------------- | ------------------------------------------------ | +| `proxy/config.json` | `/data/config.json` | the proxy (Status Page) **and** the SDK (action) | +| `store.json` | not mounted | the SDK only | + +`proxy/` is mounted at `/data` as the proxy's `PPQ_DATA_DIR`, and `config.json` +inside it is upstream's own file — the proxy rewrites it wholesale when a key is +saved from the Status Page, so nothing of ours may live there. The Verbose +Logging setting therefore lives in `store.json`, outside the mount. + +A `chown` oneshot hands `/data` to the image's unprivileged `node` user before +the daemon starts, so the Status Page can write to it. ## Installation and First-Run Flow -On install, a critical task prompts for a PPQ.AI API key. The service cannot -start until the key is provided (the task blocks startup, and upstream exits -immediately when neither `PPQ_API_KEY` nor `PPQ_DATA_DIR` is set). There is no -other setup. +On install, an **important** (non-blocking) task prompts for a PPQ.AI API key. +There are two ways to satisfy it, and neither is required before starting: + +1. Run the **Configure PPQ API Key** action. +2. Start the service and save the key on the **Status Page**. + +The proxy runs without a key — it completes attestation, serves the Status Page, +and answers `401` to inference requests until one is set. The task is +deliberately not critical: a critical task suspends every other control, which +would leave the user unable to start the service and reach the Status Page's own +key form. ## Configuration Management -Nothing is upstream-managed: the proxy has no config file of its own and takes -every setting from an environment variable, all of which StartOS supplies from -`config.json`. +The API key is the proxy's to own. StartOS does **not** pass `PPQ_API_KEY`; +instead it points `PPQ_DATA_DIR` at the mounted volume so upstream's key store +is the single source of truth, written by either the action or the Status Page +and read from the same file by both. -- `PPQ_API_KEY` — set from the **Configure PPQ API Key** action -- `DEBUG` — set from the same action's Verbose Logging toggle +- `PPQ_DATA_DIR` — `/data`, enabling persistence and the Status Page's key form +- `DEBUG` — set from the action's Verbose Logging toggle, via `store.json` - `HOST` — fixed to `0.0.0.0` (container binding) - `PORT` — fixed to 8787 - `PPQ_API_BASE` — not set (upstream default `https://api.ppq.ai`) -- `PPQ_DATA_DIR` — deliberately not set (see Limitations) -Changing settings restarts the daemon (values are read reactively). +The proxy loads `config.json` once at startup, so `main.ts` watches the file: +writing a key restarts the daemon, which reloads it. A key saved on the Status +Page takes effect immediately in the running proxy and then triggers that same +restart — brief, and it converges on the value just saved either way. ## Network Access and Interfaces @@ -91,10 +110,10 @@ Availability on LAN/Tor is decided by the user from the interface panel. ## Actions (StartOS UI) - **Configure PPQ API Key** (`configure-api-key`) — visible and enabled at any - service status. Inputs: the PPQ.AI API key (masked; left blank it keeps the - key already saved, and it is never echoed back into the form) and the Verbose - Logging toggle. No result output. Also the target of the critical first-run - task. + service status. Inputs: the PPQ.AI API key (masked, validated against + upstream's `^sk-[A-Za-z0-9]{16,64}$` shape; left blank it keeps the key + already saved and is never echoed back into the form) and the Verbose Logging + toggle. No result output. Also the target of the first-run task. ## Backups and Restore @@ -119,11 +138,10 @@ None. 1. This service is a client-side encryption proxy, not a self-hosted model server: inference runs remotely in PPQ.AI's attested TEE enclaves, and a funded [PPQ.AI](https://ppq.ai) API key is required (pay-per-query). -2. The API-key form on upstream's status page is inactive here. StartOS is the - single source of truth for the key, so `PPQ_DATA_DIR` is left unset: with - it set, upstream would persist a browser-entered key to its own - `config.json` while the StartOS-supplied `PPQ_API_KEY` still won at every - restart, silently reverting it. Use the **Configure PPQ API Key** action. +2. Saving a key on the Status Page restarts the daemon a few seconds later. + The proxy applies the key immediately; the restart is StartOS reacting to + the same file write, and is what makes the **Configure PPQ API Key** action + work at all (upstream reads `config.json` only at startup). 3. The upstream OpenClaw-plugin mode is not packaged; only the standalone proxy runs on StartOS. 4. The bind address and port are fixed inside the container; upstream's @@ -134,7 +152,7 @@ None. - All API endpoints, request/response formats, and streaming behavior - The encryption and attestation flow (EHBP transport via the `tinfoil` client) - Model catalog and per-request `Authorization: Bearer` key override -- The status page rendered at `/`, minus its API-key form +- The status page rendered at `/`, its API-key form included ## Contributing @@ -148,7 +166,7 @@ See [AGENTS.md](AGENTS.md). package_id: ppq-private-mode architectures: [x86_64, aarch64] volumes: - main: null # host-side config.json only; not mounted into the container + main: /data # subpath `proxy/` only; `store.json` stays host-side ports: main: 8787 # one host serving both interfaces interfaces: @@ -156,7 +174,7 @@ interfaces: - api dependencies: none startos_managed_env_vars: - - PPQ_API_KEY + - PPQ_DATA_DIR - HOST - PORT - DEBUG diff --git a/instructions.md b/instructions.md index de33fa6..a0d44f6 100644 --- a/instructions.md +++ b/instructions.md @@ -16,6 +16,7 @@ Two interfaces share one address: - **Status Page** — a web page showing whether enclave attestation succeeded, which private models are available, and how to point a client at the proxy. + It is also where you can save your API key. - **OpenAI-Compatible API** — the same address, ready to copy into a client. The only thing the service stores is your PPQ.AI API key and the logging @@ -23,14 +24,21 @@ setting. ## Getting set up -1. You will be prompted to run **Configure PPQ API Key**. Paste an API key from - [ppq.ai](https://ppq.ai) — create one under **Settings → API Keys** and fund - the account, since usage is billed per query to this key. -2. The service starts and performs a cryptographic attestation of the remote - enclave. The health check reports ready once attestation is verified — - usually within a few seconds. -3. Open the **Status Page** to confirm attestation succeeded, or copy the - **OpenAI-Compatible API** address to point a client at it. +You need a funded API key from [ppq.ai](https://ppq.ai) — create one under +**Settings → API Keys**, since usage is billed per query to that key. You can +save it before or after starting the service; the proxy runs either way and +simply refuses inference requests until it has one. + +1. Start the service. It performs a cryptographic attestation of the remote + enclave, which the health check reports as ready — usually within a few + seconds. +2. Open the **Status Page**, confirm attestation says _verified_, and paste your + key into the API key form. The proxy picks it up immediately, then restarts + once to persist it. +3. Copy the **OpenAI-Compatible API** address to point a client at it. + +If you would rather not start the service first, run the **Configure PPQ API +Key** action instead of step 2 — it does the same thing from the Actions tab. ## Using PPQ Private Mode @@ -51,22 +59,20 @@ export ANTHROPIC_BASE_URL="" export ANTHROPIC_MODEL="private/glm-5-2" ``` -`GET /v1/models` lists the available private models, and the -Status Page shows the same list. +`GET /v1/models` lists the available private models, and the Status +Page shows the same list. Requests are billed to your saved API key by default. To bill a different PPQ.AI key per request, pass it as an `Authorization: Bearer` header. -### Actions +### Replacing the key -Run **Configure PPQ API Key** again whenever you want to replace the key or -turn verbose logging on or off. Leaving the key field blank keeps the key you -already saved. +Either surface works, and both write the same place: **Replace key** on the +Status Page, or the **Configure PPQ API Key** action. The action is also where +you turn Verbose Logging on and off; leaving its key field blank keeps the key +you already saved. ## Limitations -The Status Page has its own "save API key" form upstream; it is inactive here, -because the key is managed by the **Configure PPQ API Key** action instead. - Backups of this service include your saved API key, and restoring a backup restores it — keep that in mind when handling backup drives. diff --git a/startos/actions/configureApiKey.ts b/startos/actions/configureApiKey.ts index e285057..bb24778 100644 --- a/startos/actions/configureApiKey.ts +++ b/startos/actions/configureApiKey.ts @@ -1,5 +1,6 @@ import { sdk } from '../sdk' import { configJson } from '../fileModels/config.json' +import { storeJson } from '../fileModels/store.json' import { i18n } from '../i18n' const { InputSpec, Value } = sdk @@ -8,12 +9,21 @@ const inputSpec = InputSpec.of({ apiKey: Value.text({ name: i18n('PPQ.AI API Key'), description: i18n( - 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.', + 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved, or to set one later from the Status Page.', ), required: false, default: null, masked: true, placeholder: 'sk-...', + // Upstream's own shape check, applied here too — the Status Page rejects a + // malformed key outright, but a key written straight to config.json would + // only surface as a 401 on the first request. + patterns: [ + { + regex: '^sk-[A-Za-z0-9]{16,64}$', + description: i18n('A PPQ.AI key starts with "sk-".'), + }, + ], }), debug: Value.toggle({ name: i18n('Verbose Logging'), @@ -42,21 +52,13 @@ export const configureApiKey = sdk.Action.withInput( // Prefill: the API key is never echoed back into the form. async ({ effects }) => ({ - debug: (await configJson.read((c) => c.debug).once()) ?? false, + debug: (await storeJson.read((s) => s.debug).once()) ?? false, }), async ({ effects, input }) => { - const apiKey = - (input.apiKey ?? '').trim() || - (await configJson.read((c) => c.apiKey).once()) - if (!apiKey) { - throw new Error( - i18n( - 'An API key is required. Create one at ppq.ai under Settings → API Keys.', - ), - ) - } + await storeJson.merge(effects, { debug: input.debug }) - await configJson.merge(effects, { apiKey, debug: input.debug }) + const apiKey = (input.apiKey ?? '').trim() + if (apiKey) await configJson.merge(effects, { apiKey }) }, ) diff --git a/startos/fileModels/config.json.ts b/startos/fileModels/config.json.ts index ecd8040..f74024d 100644 --- a/startos/fileModels/config.json.ts +++ b/startos/fileModels/config.json.ts @@ -1,15 +1,15 @@ import { FileHelper, z } from '@start9labs/start-sdk' import { sdk } from '../sdk' -// Package-owned settings file on the main volume. The upstream proxy is -// configured purely through environment variables; main.ts bridges these -// values into the daemon's env. +// Upstream's own persistent config, at /config.json. The proxy +// loads the key from here at startup and rewrites the whole file when one is +// saved from the status page, so this shape must stay exactly upstream's and +// nothing else may live in it — see fileModels/store.json.ts. const shape = z.object({ apiKey: z.string().optional().catch(undefined), - debug: z.boolean().catch(false), }) export const configJson = FileHelper.json( - { base: sdk.volumes.main, subpath: 'config.json' }, + { base: sdk.volumes.main, subpath: 'proxy/config.json' }, shape, ) diff --git a/startos/fileModels/store.json.ts b/startos/fileModels/store.json.ts new file mode 100644 index 0000000..eae28b0 --- /dev/null +++ b/startos/fileModels/store.json.ts @@ -0,0 +1,13 @@ +import { FileHelper, z } from '@start9labs/start-sdk' +import { sdk } from '../sdk' + +// Package-owned settings, kept outside the mounted PPQ_DATA_DIR subtree so the +// proxy neither sees them nor overwrites them. +const shape = z.object({ + debug: z.boolean().catch(false), +}) + +export const storeJson = FileHelper.json( + { base: sdk.volumes.main, subpath: 'store.json' }, + shape, +) diff --git a/startos/i18n/dictionaries/default.ts b/startos/i18n/dictionaries/default.ts index c559ac3..caf3bf0 100644 --- a/startos/i18n/dictionaries/default.ts +++ b/startos/i18n/dictionaries/default.ts @@ -13,14 +13,14 @@ const dict = { 'Point any OpenAI or Anthropic SDK client at this URL to use PPQ private (TEE) models with end-to-end encryption': 7, // actions/configureApiKey.ts 'PPQ.AI API Key': 8, - 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved.': 9, - 'Verbose Logging': 10, - 'Log every request the proxy handles. Useful for troubleshooting.': 11, - 'Configure PPQ API Key': 12, - 'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 13, - 'An API key is required. Create one at ppq.ai under Settings → API Keys.': 14, + 'Your API key from ppq.ai (Settings → API Keys). Leave blank to keep the key already saved, or to set one later from the Status Page.': 9, + 'A PPQ.AI key starts with "sk-".': 10, + 'Verbose Logging': 11, + 'Log every request the proxy handles. Useful for troubleshooting.': 12, + 'Configure PPQ API Key': 13, + 'Set the PPQ.AI API key the proxy uses to authenticate. Requests are billed to this key.': 14, // init/taskConfigureApiKey.ts - 'Add your PPQ.AI API key to start the proxy': 15, + 'Add your PPQ.AI API key here, or start the service and save one on the Status Page': 15, } as const /** diff --git a/startos/i18n/dictionaries/translations.ts b/startos/i18n/dictionaries/translations.ts index 2fabe5c..f1f8d66 100644 --- a/startos/i18n/dictionaries/translations.ts +++ b/startos/i18n/dictionaries/translations.ts @@ -11,13 +11,13 @@ export default { 6: 'API compatible con OpenAI', 7: 'Apunta cualquier cliente SDK de OpenAI o Anthropic a esta URL para usar los modelos privados (TEE) de PPQ con cifrado de extremo a extremo', 8: 'Clave API de PPQ.AI', - 9: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada.', - 10: 'Registro detallado', - 11: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.', - 12: 'Configurar clave API de PPQ', - 13: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.', - 14: 'Se requiere una clave API. Crea una en ppq.ai en Ajustes → Claves API.', - 15: 'Añade tu clave API de PPQ.AI para iniciar el proxy', + 9: 'Tu clave API de ppq.ai (Ajustes → Claves API). Déjalo en blanco para conservar la clave ya guardada, o para configurar una más tarde desde la Página de estado.', + 10: 'Una clave de PPQ.AI empieza por «sk-».', + 11: 'Registro detallado', + 12: 'Registra cada solicitud que maneja el proxy. Útil para diagnosticar problemas.', + 13: 'Configurar clave API de PPQ', + 14: 'Establece la clave API de PPQ.AI que el proxy usa para autenticarse. Las solicitudes se facturan a esta clave.', + 15: 'Añade aquí tu clave API de PPQ.AI, o inicia el servicio y guárdala en la Página de estado', }, de_DE: { 0: 'Starte PPQ Private Mode!', @@ -29,13 +29,13 @@ export default { 6: 'OpenAI-kompatible API', 7: 'Verbinde jeden OpenAI- oder Anthropic-SDK-Client mit dieser URL, um die privaten (TEE) Modelle von PPQ mit Ende-zu-Ende-Verschlüsselung zu nutzen', 8: 'PPQ.AI-API-Schlüssel', - 9: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten.', - 10: 'Ausführliche Protokollierung', - 11: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.', - 12: 'PPQ-API-Schlüssel konfigurieren', - 13: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.', - 14: 'Ein API-Schlüssel ist erforderlich. Erstelle einen auf ppq.ai unter Einstellungen → API-Schlüssel.', - 15: 'Füge deinen PPQ.AI-API-Schlüssel hinzu, um den Proxy zu starten', + 9: 'Dein API-Schlüssel von ppq.ai (Einstellungen → API-Schlüssel). Leer lassen, um den bereits gespeicherten Schlüssel zu behalten oder später auf der Statusseite einen festzulegen.', + 10: 'Ein PPQ.AI-Schlüssel beginnt mit „sk-“.', + 11: 'Ausführliche Protokollierung', + 12: 'Protokolliert jede Anfrage, die der Proxy verarbeitet. Nützlich zur Fehlersuche.', + 13: 'PPQ-API-Schlüssel konfigurieren', + 14: 'Lege den PPQ.AI-API-Schlüssel fest, mit dem sich der Proxy authentifiziert. Anfragen werden diesem Schlüssel in Rechnung gestellt.', + 15: 'Füge deinen PPQ.AI-API-Schlüssel hier hinzu, oder starte den Dienst und speichere ihn auf der Statusseite', }, pl_PL: { 0: 'Uruchamianie PPQ Private Mode!', @@ -47,13 +47,13 @@ export default { 6: 'API zgodne z OpenAI', 7: 'Skieruj dowolnego klienta SDK OpenAI lub Anthropic na ten URL, aby korzystać z prywatnych modeli (TEE) PPQ z szyfrowaniem end-to-end', 8: 'Klucz API PPQ.AI', - 9: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz.', - 10: 'Szczegółowe logowanie', - 11: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.', - 12: 'Skonfiguruj klucz API PPQ', - 13: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.', - 14: 'Wymagany jest klucz API. Utwórz go na ppq.ai w Ustawienia → Klucze API.', - 15: 'Dodaj swój klucz API PPQ.AI, aby uruchomić proxy', + 9: 'Twój klucz API z ppq.ai (Ustawienia → Klucze API). Pozostaw puste, aby zachować już zapisany klucz lub ustawić go później na Stronie stanu.', + 10: 'Klucz PPQ.AI zaczyna się od „sk-”.', + 11: 'Szczegółowe logowanie', + 12: 'Rejestruje każde żądanie obsługiwane przez proxy. Przydatne przy rozwiązywaniu problemów.', + 13: 'Skonfiguruj klucz API PPQ', + 14: 'Ustaw klucz API PPQ.AI, którym proxy się uwierzytelnia. Żądania są rozliczane na ten klucz.', + 15: 'Dodaj tutaj swój klucz API PPQ.AI albo uruchom usługę i zapisz go na Stronie stanu', }, fr_FR: { 0: 'Démarrage de PPQ Private Mode !', @@ -65,12 +65,12 @@ export default { 6: 'API compatible OpenAI', 7: "Pointez n'importe quel client SDK OpenAI ou Anthropic vers cette URL pour utiliser les modèles privés (TEE) de PPQ avec un chiffrement de bout en bout", 8: 'Clé API PPQ.AI', - 9: 'Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée.', - 10: 'Journalisation détaillée', - 11: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.', - 12: 'Configurer la clé API PPQ', - 13: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.", - 14: 'Une clé API est requise. Créez-en une sur ppq.ai dans Paramètres → Clés API.', - 15: 'Ajoutez votre clé API PPQ.AI pour démarrer le proxy', + 9: "Votre clé API de ppq.ai (Paramètres → Clés API). Laissez vide pour conserver la clé déjà enregistrée, ou pour en définir une plus tard depuis la Page d'état.", + 10: 'Une clé PPQ.AI commence par « sk- ».', + 11: 'Journalisation détaillée', + 12: 'Journalise chaque requête traitée par le proxy. Utile pour le dépannage.', + 13: 'Configurer la clé API PPQ', + 14: "Définissez la clé API PPQ.AI avec laquelle le proxy s'authentifie. Les requêtes sont facturées sur cette clé.", + 15: "Ajoutez ici votre clé API PPQ.AI, ou démarrez le service et enregistrez-la sur la Page d'état", }, } satisfies Record diff --git a/startos/init/taskConfigureApiKey.ts b/startos/init/taskConfigureApiKey.ts index a17492e..3c8e725 100644 --- a/startos/init/taskConfigureApiKey.ts +++ b/startos/init/taskConfigureApiKey.ts @@ -3,14 +3,18 @@ import { configJson } from '../fileModels/config.json' import { configureApiKey } from '../actions/configureApiKey' import { i18n } from '../i18n' -// The proxy cannot start without a PPQ.AI API key, so a critical task blocks -// startup until the user provides one. +// The proxy starts and serves its Status Page without a key, answering 401 to +// inference requests until one is set. So this prompt is important rather than +// critical: a critical task suspends every other control, which would leave the +// user unable to start the service and reach the Status Page's own key form. export const taskConfigureApiKey = sdk.setupOnInit(async (effects) => { const apiKey = await configJson.read((c) => c.apiKey).once() if (!apiKey) { - await sdk.action.createOwnTask(effects, configureApiKey, 'critical', { - reason: i18n('Add your PPQ.AI API key to start the proxy'), + await sdk.action.createOwnTask(effects, configureApiKey, 'important', { + reason: i18n( + 'Add your PPQ.AI API key here, or start the service and save one on the Status Page', + ), }) } }) diff --git a/startos/main.ts b/startos/main.ts index 97271df..10a1485 100644 --- a/startos/main.ts +++ b/startos/main.ts @@ -1,49 +1,75 @@ import { i18n } from './i18n' import { sdk } from './sdk' -import { apiPort } from './utils' +import { manifest } from './manifest' +import { apiPort, dataDir } from './utils' +import { configureApiKey } from './actions/configureApiKey' import { configJson } from './fileModels/config.json' +import { storeJson } from './fileModels/store.json' export const main = sdk.setupMain(async ({ effects }) => { console.info(i18n('Starting PPQ Private Mode!')) - // Read reactively so the daemon restarts when the user changes settings. + // The proxy reads config.json once at startup, so watching it is what makes a + // key saved by the Configure PPQ API Key action take effect: the write + // restarts the daemon, which reloads the file. PPQ_API_KEY is left unset so + // the proxy's own key store is the only thing that owns the key. const apiKey = await configJson.read((c) => c.apiKey).const(effects) - const debug = await configJson.read((c) => c.debug).const(effects) + const debug = await storeJson.read((s) => s.debug).const(effects) - return sdk.Daemons.of(effects).addDaemon('proxy', { - // The proxy is stateless and fully configured via env — the 'main' volume - // (config.json, read host-side by the SDK) is never mounted into the - // container. - subcontainer: sdk.SubContainer.of( - effects, - { imageId: 'proxy' }, - null, - 'proxy-sub', - ), - exec: { - command: ['node', '/app/dist/bin/server.js'], - env: { - PPQ_API_KEY: apiKey ?? '', - HOST: '0.0.0.0', - PORT: apiPort.toString(), - DEBUG: debug ? 'true' : 'false', + // Running the action clears its own task, but a key saved on the Status Page + // never touches the action — so clear it here, on the restart that same save + // triggers. Otherwise StartOS keeps asking for a key the user already set. + if (apiKey) { + await sdk.action.clearTask(effects, `${manifest.id}:${configureApiKey.id}`) + } + + const subcontainer = sdk.SubContainer.of( + effects, + { imageId: 'proxy' }, + sdk.Mounts.of().mountVolume({ + volumeId: 'main', + subpath: 'proxy', + mountpoint: dataDir, + readonly: false, + }), + 'proxy-sub', + ) + + return sdk.Daemons.of(effects) + .addOneshot('chown', { + subcontainer, + exec: { + command: ['chown', '-R', 'node:node', dataDir], + user: 'root', }, - }, - // The proxy only binds its port after remote attestation of the enclave - // succeeds, so a listening port means the encrypted channel is verified - // and ready. - ready: { - display: i18n('Encrypted Proxy'), - fn: () => - sdk.healthCheck.checkPortListening(effects, apiPort, { - successMessage: i18n( - 'The proxy is ready — enclave attestation verified', - ), - errorMessage: i18n( - 'The proxy is not ready (enclave attestation pending)', - ), - }), - }, - requires: [], - }) + requires: [], + }) + .addDaemon('proxy', { + subcontainer, + exec: { + command: ['node', '/app/dist/bin/server.js'], + env: { + PPQ_DATA_DIR: dataDir, + HOST: '0.0.0.0', + PORT: apiPort.toString(), + DEBUG: debug ? 'true' : 'false', + }, + }, + // The proxy only binds its port after remote attestation of the enclave + // succeeds, so a listening port means the encrypted channel is verified + // and ready. + ready: { + display: i18n('Encrypted Proxy'), + fn: () => + sdk.healthCheck.checkPortListening(effects, apiPort, { + successMessage: i18n( + 'The proxy is ready — enclave attestation verified', + ), + errorMessage: i18n( + 'The proxy is not ready (enclave attestation pending)', + ), + }), + }, + requires: ['chown'], + }) }) diff --git a/startos/utils.ts b/startos/utils.ts index 92220bd..d6ca153 100644 --- a/startos/utils.ts +++ b/startos/utils.ts @@ -2,3 +2,7 @@ // Port the proxy listens on inside the container (upstream default). export const apiPort = 8787 + +// Upstream's PPQ_DATA_DIR inside the container: where it persists the API key +// saved from the status page. +export const dataDir = '/data' From a77cba492c414399a79de69a8ac539f70b1e31d2 Mon Sep 17 00:00:00 2001 From: helix-nine <267227783+helix-nine@users.noreply.github.com> Date: Wed, 12 Aug 2026 10:05:32 -0600 Subject: [PATCH 3/3] document the unauthenticated endpoints, drop TODO.md for issues MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nothing on the proxy is authenticated, so whoever can reach the port can spend the user's PPQ.AI balance — true of every version, and not something either doc said. Enabling PPQ_DATA_DIR adds a second unauthenticated route, POST /setup/api-key, which replaces the stored key (upstream PayPerQ/ppq-private-mode-proxy#23). README states both and whose each is; instructions.md tells the user plainly to expose the interface only to people they trust, which is the part they can act on. TODO.md is deleted rather than emptied. Its live-inference item is closed — PayPerQ confirmed billed end-to-end against glm-5-2 and llama3-3-70b — and the other two are now issues #2 (backup/restore, unverified: it needs the server password, and the 0.4 file split gives it two new ways to fail) and #3 (bump when the auth patch lands, and retract the warnings it makes false). The scaffold's worklist has been worked; a file left behind to say so is not worth reading. --- README.md | 10 ++++++++++ TODO.md | 8 -------- instructions.md | 7 +++++++ 3 files changed, 17 insertions(+), 8 deletions(-) delete mode 100644 TODO.md diff --git a/README.md b/README.md index e580eab..4c68871 100644 --- a/README.md +++ b/README.md @@ -107,6 +107,16 @@ Two interfaces on one HTTP host, port 8787, both served by the proxy: Availability on LAN/Tor is decided by the user from the interface panel. +**No endpoint is authenticated.** Upstream ships no auth on any route, so +whoever can reach the port can spend the user's PPQ.AI balance via +`/v1/chat/completions`, and — because this package sets `PPQ_DATA_DIR` — can +also replace the stored key via `POST /setup/api-key` +([upstream #23](https://github.com/PayPerQ/ppq-private-mode-proxy/issues/23)). +The billing exposure predates that endpoint and is inherent to the proxy; the +key-replacement one is enabled by our `PPQ_DATA_DIR` choice, and closes when +upstream's patch lands and this package bumps to it. `instructions.md` warns +the user to expose the interface accordingly. + ## Actions (StartOS UI) - **Configure PPQ API Key** (`configure-api-key`) — visible and enabled at any diff --git a/TODO.md b/TODO.md deleted file mode 100644 index 3ef3ade..0000000 --- a/TODO.md +++ /dev/null @@ -1,8 +0,0 @@ -# TODO — remaining work before release - -- [ ] Run one live inference request with a funded PPQ.AI key. Everything up to - the enclave is verified (attestation, encrypted forward, error handling), - but no request has yet been billed end-to-end against a real key. -- [ ] Re-run backup and restore on a StartOS box: back up, uninstall, restore, - and confirm the service comes back with its key and raises no - configuration task. diff --git a/instructions.md b/instructions.md index a0d44f6..6afbf8c 100644 --- a/instructions.md +++ b/instructions.md @@ -74,5 +74,12 @@ you already saved. ## Limitations +**The proxy has no login of its own, so only expose it to people you trust.** +Anyone who can reach the address can send requests that are billed to your +PPQ.AI key, and can replace the stored key from the Status Page. On a LAN-only +address that means everyone on your network; if you enable a Tor or public +address, it means anyone with the address. Keeping it on the LAN, or on Tor with +the address kept private, is the safe default. + Backups of this service include your saved API key, and restoring a backup restores it — keep that in mind when handling backup drives.