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.
PPQ Private Mode on StartOS
Upstream docs: https://github.com/PayPerQ/ppq-private-mode-proxy
Everything not listed in this document should behave the same as the upstream PPQ Private Mode proxy. If a feature, setting, or behavior is not mentioned here, the upstream documentation is accurate and fully applicable.
End-to-end encrypted proxy for PPQ.AI private (TEE) AI models. Requests are encrypted on your server and only decrypted inside a hardware-secured enclave whose code fingerprint is cryptographically attested before any data is sent. Upstream: PayPerQ/ppq-private-mode-proxy.
Table of Contents
- Image and Container Runtime
- Volume and Data Layout
- Installation and First-Run Flow
- Configuration Management
- Network Access and Interfaces
- Actions (StartOS UI)
- Backups and Restore
- Health Checks
- Dependencies
- Limitations and Differences
- What Is Unchanged from Upstream
- Contributing
- Quick Reference for AI Consumers
Image and Container Runtime
The image is built from the upstream repository's own Dockerfile via the
ppq-private-mode-proxy git submodule (multi-stage node:22-alpine build,
runs as the unprivileged node user). No entrypoint modifications; the daemon
runs node /app/dist/bin/server.js directly.
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.
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.
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.
PPQ_API_KEY— set from the Configure PPQ API Key actionDEBUG— set from the same action's Verbose Logging toggleHOST— fixed to0.0.0.0(container binding)PORT— fixed to 8787PPQ_API_BASE— not set (upstream defaulthttps://api.ppq.ai)PPQ_DATA_DIR— deliberately not set (see Limitations)
Changing settings restarts the daemon (values are read reactively).
Network Access and Interfaces
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) — 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
The main volume (i.e. config.json) is backed up. Restore brings back the
saved API key and settings; no other state exists. Note that backups therefore
contain the saved PPQ.AI API key (StartOS backups are encrypted with the
user's backup password).
Health Checks
One daemon readiness check on port 8787. The upstream proxy only binds its port after remote attestation of the enclave succeeds, so "listening" implies the encrypted channel is verified. Until attestation completes the check reports the proxy as not ready.
Dependencies
None.
Limitations and Differences
- 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 API key is required (pay-per-query).
- 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_DIRis left unset: with it set, upstream would persist a browser-entered key to its ownconfig.jsonwhile the StartOS-suppliedPPQ_API_KEYstill won at every restart, silently reverting it. Use the Configure PPQ API Key action. - The upstream OpenClaw-plugin mode is not packaged; only the standalone proxy runs on StartOS.
- The bind address and port are fixed inside the container; upstream's
HOST/PORT/PPQ_API_BASEvariables 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
tinfoilclient) - Model catalog and per-request
Authorization: Bearerkey override - The status page rendered at
/, minus its API-key form
Contributing
See AGENTS.md.
Quick Reference for AI Consumers
package_id: ppq-private-mode
architectures: [x86_64, aarch64]
volumes:
main: null # host-side config.json only; not mounted into the container
ports:
main: 8787 # one host serving both interfaces
interfaces:
- ui
- api
dependencies: none
startos_managed_env_vars:
- PPQ_API_KEY
- HOST
- PORT
- DEBUG
actions:
- configure-api-key