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:
10 files changed
+213
-140
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user