adopt 0.4's persistent key store and browser setup form

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.
This commit is contained in:
helix-nine committed 2026-08-12 09:58:35 -06:00
1 parent 42b2841945
commit 8397c7b1eb
10 files changed
+213 -140

No files matched your search

+46 -28
View File
@@ -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