Wraps the ppq-private-mode-proxy (git submodule, built from its own Dockerfile) as a StartOS 0.4.0 service: - Critical first-run task + masked action to set the PPQ.AI API key - OpenAI-/Anthropic-compatible API interface on port 8787 - Health check reflects enclave attestation (proxy binds only after attestation succeeds) - x86_64 + aarch64, config backed up via the main volume Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
4.8 KiB
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, mounted at /data. The proxy itself is stateless; the
volume holds only config.json (the StartOS-managed settings file containing
the API key and logging preference), written by the SDK on the host side.
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.
Configuration Management
All upstream configuration is via environment variables; StartOS manages them
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 to8787PPQ_API_BASE— not set (upstream defaulthttps://api.ppq.ai)
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.
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.
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.
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 upstream OpenClaw-plugin mode is not packaged; only the standalone proxy runs on StartOS.
- The bind address and port are fixed (
0.0.0.0:8787inside the container); upstream'sHOST/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
Contributing
See AGENTS.md.
Quick Reference for AI Consumers
package_id: ppq-private-mode
architectures: [x86_64, aarch64]
volumes:
main: /data
ports:
api: 8787
dependencies: none
startos_managed_env_vars:
- PPQ_API_KEY
- HOST
- PORT
- DEBUG
actions:
- configure-api-key