Keysat
974c3eb07d
Five providers behind one streaming abstraction:
- claude (Anthropic)
- openai (api.openai.com)
- openai-compatible (any base URL — OpenRouter / LiteLLM /
vLLM / Together / your own gateway)
- gemini (Google)
- ollama (self-hosted; no key; LAN URL like
http://ollama.embassy:11434)
The "self-hosted Ollama on Start9" angle is the killer use case —
configure Settings → AI integration with the LAN URL of your Ollama
service and no API keys ever leave your network.
Architecture
- lib/ai/types.ts LLMProvider streaming interface
- lib/ai/sse.ts shared SSE + NDJSON line iterators
- lib/ai/providers/*.ts 5 implementations + factory
- lib/ai/programSchema.ts Zod schema + JSON-schema-for-prompt +
parseAIProgram with markdown-fence
stripping and balanced-brace JSON
extraction
- lib/ai/apply.ts materializes parsed AIProgram into
Program tree (validates exerciseIds,
rejects unresolved nulls, atomic
transaction, sets aiGenerated=true)
Schema
- UserPreferences gets aiProvider/aiModel/aiBaseUrl/aiApiKey
(plaintext — same threat model as the rest of /data). Dead
enableClaudeAI/claudeApiKey columns from v1.0.0:1-7 stay as
no-op fields.
- AIPromptTemplate (userId nullable; userId=NULL = built-in)
- AIGeneration (raw response + parsed program + status +
appliedProgramId + token counts)
- All compat-ALTER'd in docker_entrypoint.sh on first boot.
API
- POST /api/ai/generate SSE streaming: emits
generation/text/usage/complete
events; persists AIGeneration
row up front so failures show
in history too
- POST /api/ai/apply takes user-edited AIProgram,
creates Program, marks
generation as applied
- GET /api/ai/templates built-ins + this user's own
- POST /api/ai/templates create user-owned template
- PATCH /api/ai/templates/[id] edit; built-ins admin-only
- DELETE /api/ai/templates/[id] delete; built-ins admin-only
- GET /api/ai/generations list (paginated)
- GET /api/ai/generations/[id] full row
- DELETE /api/ai/generations/[id] delete one (Program survives)
- GET /api/ai/config returns aiKeyConfigured flag,
never plaintext key
- POST /api/ai/config update provider config
- DELETE /api/admin/ai/generations admin-only "clear all" with
optional userId / olderThanDays
UI
- Settings → AI integration provider/model/URL/key form;
plaintext key warning visible
- /main/ai hub page with cards
- /main/ai/generate template picker + textarea +
live SSE stream + cancel +
ProgramPreview with inline
unknown-exercise resolver +
apply button + redirect to
the new Program
- /main/ai/templates list + create + edit + delete;
per-row "show prompt" expand;
built-in delete warns about
reconcile re-creation
- /main/ai/history list + delete; status badges;
link to applied Program
- Nav: "AI" entry between Programs and Exercises (Sparkles icon)
Built-in templates
- prisma/aiTemplates.seed.json: 5 starter templates (hypertrophy /
strength / endurance / recovery / custom)
- prisma/ensurePromptTemplates.cjs: per-boot reconcile,
INSERT-or-UPDATE keyed on (userId IS NULL AND name=...);
user-created templates never touched
Tests
- tests/ai-programSchema.test.ts: extractJson + parseAIProgram
edge cases (markdown fences, balanced braces, malformed JSON,
Zod shape rejection, unresolved-exerciseId tolerance)
- tests/ai-apply.test.ts: materializes valid AIProgram, rejects
cross-user exerciseIds, rejects unresolved exercises, honors
isActive flag
- tests/routes-ai-templates.test.ts: built-in vs user permissions,
cross-user template isolation, /api/ai/config plaintext-key safety,
provider enum validation
- 123 tests across 14 files, all passing.
No data migration. Existing /data is augmented with the new columns
+ tables only.
Proof of Work on StartOS 0.4 (migration package)
This directory packages Proof of Work (proof-of-work) for StartOS 0.4
beta. It is the cutover package that carries your 0.3.5 data across to a new
x86_64 StartOS 0.4 host.
Upstream app lives at
../../proof-of-work/in this repo. Legacy 0.3.5 package lives at../0.3.5/(kept intact; do not modify). Codex's WIP 0.4 scaffold lives at../0.4/(kept intact; superseded by this folder).
Goals
- Keep the package id
proof-of-workso StartOS recognizes it as the same service. - Keep the persistent data volume
mainmounted at/data. - Keep the SQLite database at
/data/app.db. - Preserve every existing workout, set, exercise, and preference.
- Ship x86_64 only for 0.4 beta (sideload target).
How data preservation works
seed/data/app.dbholds a one-time snapshot of/datafrom the live 0.3.5 host (currently 1 user, 348 workouts, 164 exercises, 5720 set logs).- The
Dockerfilebakes that snapshot into the image at/app/seed/data/. - On first boot only —
/data/app.dbmissing AND/data/.seededabsent —docker_entrypoint.shcopies the seed into/data/and writes a.seededmarker. - On every subsequent boot,
/data/is the sole source of truth; the seed in the image is ignored.
See seed/README.md for the snapshot provenance and row counts.
Image runtime
| Property | Value |
|---|---|
| Base image | node:20-alpine (multi-stage build) |
| App runtime | Next.js standalone + Prisma + SQLite |
| Entrypoint | /usr/local/bin/docker_entrypoint.sh (dumb-init wrapped) |
| Internal port | 3000 |
| Architectures | x86_64 (beta) |
Build and sideload
cd start9/0.4
npm ci
make clean
make x86 # outputs proof-of-work_x86_64.s9pk
Sideload via StartOS web UI or make install (requires ~/.startos/config.yaml).
Step-by-step instructions are in DEPLOY_040.md.
What is unchanged from 0.3.5
- Package id:
proof-of-work - Volume id:
main - Mount path:
/data - DB path:
/data/app.db - Health endpoint:
/api/health - Compat
ALTER TABLEblock (idempotent; no-op on a current DB)
What is new in 0.4
- TypeScript SDK manifest under
startos/ - ExVer version (
0.1.0:18) replaces the 0.3.5 4-part0.1.0.17 - Seed-on-first-boot with a
.seededmarker and stderr logging alertUpdatewarning users not to Uninstall to troubleshoot- Self-contained Dockerfile — no references to
../0.3.5/or../0.4/
Follow-up releases (planned, do not ship yet)
- v0.1.0:19 — remove the
COPY seed/data \u2026line and the seed block from the entrypoint once the cutover is confirmed. Leavesseed/on disk unreferenced. - v0.1.0:19 or v0.1.0:20 — add a StartOS Package Action
change-admin-credentialsthat updates the User row in/data/app.db(bcryptjs, salt rounds 10) so you can rename/rotate the admin from the StartOS UI.