halkyon/docs/adr/0021-private-instance-and-assistant.md

# ADR 0021: A private instance: approved sign-ups and an assistant the operator grants

- **Status:** accepted 25 Oct 2026, to be built for v0.21.0 (D18). Decided by the
  developer: D1–D6 on 23 Oct; on 25 Oct what an assistant may see and do (D7–D12), what it
  keeps and does, where it lives, the proposal's points 4–8 and 10, how often it warns and
  when it is built (D13–D18), who signs up and who operates (D19–D22), waiting accounts
  (D23–D26), and what people are told and what never goes (D27–D30).
- **Builds on:** ADR 0016 (the register), ADR 0019 (private studysets), ADR 0020
  (SimpleLogin), ADR 0022 (the hand-off and the connector gone).
- **Changes:** the rule of 10 Oct 2026 that Halkyon calls no language model with an API
  key, for an instance whose operator opts in.

## Context

The developer may stop the public instance and run halkyon.li for themselves and their
close family instead. They don't know in advance which addresses their family will sign in
with, and with SimpleLogin (ADR 0020) the instance keeps no addresses anyway.

On 10 Oct the developer ruled out API keys for language models: on a public instance anyone
could drive up the bill, and each person should decide what a model sees. Assistants came
through people's own subscriptions instead: the connector (ADR 0006) and the hand-off to
Claude or Lumo, both gone since 23 Oct (ADR 0022). A family instance whose operator
approves every account takes away the first reason; the second holds if the app shows
what it sends.

People in one family may prefer different providers (the developer: "I might use myself
the Claude API while other might want to use the OpenAI API, then one other the Proton
Lumo API"). A plan for Claude's or ChatGPT's apps is no API access: the APIs are billed
apart, by their providers' consoles.

Two protocols reach nearly every provider: Anthropic's Messages API (Claude), and the
OpenAI-compatible chat completions (OpenAI, Mistral, Google Gemini's compatibility
endpoint, OpenRouter, local models through Ollama, llama.cpp or vLLM). Proton announced a
Lumo API for autumn or winter 2026 without publishing its format; community projects
(lumo-tamer, an unofficial tracker) show an OpenAI-compatible interface. Still none by
25 Oct, but for the unofficial tracker's "early access".

No remote provider keeps what it is asked confidential while its model answers: the model
reads plain text. Lumo too: its prompts are encrypted beyond TLS on their way to Proton's
servers, decrypted there to be answered and, Proton says, discarded; its zero-access
encryption covers the chats it stores, which an API call doesn't make. What keeps a
private studyset private there is a promise, not cryptography. Only a model on the
person's own machine does without one.

## Decisions (23 Oct 2026, the developer's)

- **D1 Sign-ups wait for the operator's approval** (over invitation links, which were
  recommended, and a sign-up window): anyone can sign up; nothing works until the operator
  approves them.
- **D2 The assistant runs on the instance's key, granted per person** (recommended, over
  each person's own key and both): the operator pays and switches it on for whom they
  choose.
- **D3 Individual limits and statistics** (the developer: "so I can see after the fact who
  potentially drove up the bill"): each person's use is limited and counted, and the
  operator sees it per person.
- **D4 Several providers, all on the operator's keys** (over personal keys alone, and over
  both, which was recommended): the operator sets up the assistants the instance offers
  and grants each person one or more.
- **D5 Personal keys stay on the person's devices** (recommended, over keeping them on the
  instance): the app calls the provider itself, and the instance sees neither key nor
  text.
- **D6 Personal keys only where the operator allows them** (over every instance, which was
  recommended): an instance setting, off unless switched on.

On 25 Oct, what an assistant may see and do (the developer: "Only what is chosen, within a
studyset, within a tree of studysets, and a complete library (maybe even an option
including/excluding private studysets?)"):

- **D7 The person chooses the scope of each question:** the parts they tick (the field's
  chips, as for a web search), this studyset (the one open, with everything inside it, as
  studying it covers), its tree (from its top studyset down), or their library (decided
  over a scope for a studyset without its topics). Beyond the parts ticked, nothing is
  put into the request whole, as a library outgrows any model's context: the model looks
  things up through tools the app answers on the device, read-only and within the scope,
  each lookup shown in the conversation and counted in the person's limits.
- **D8 Private studysets stay out of a wider scope unless switched on** (recommended, over
  taking them in with the warning, and over never sending them): beside the scope,
  "Include private studysets", off for every question.
- **D9 A warning whenever a private studyset's content would go to a remote model**
  (recommended): it leaves end-to-end encryption; the warning names the provider and links
  its terms. The same for every remote provider, Lumo included (see *Context*), not
  graded by promises the app can't verify, and with no exception for an address on the
  local network, which may be a company's or a shared one; none for a model at a loopback
  address, on the device itself. Shown for parts ticked as for the switch of D8.
- **D10 Changes only as drafts** (recommended, over answers alone and over writes with
  Undo): the model proposes cards, notes or edits, which open in the composer or editor;
  nothing is saved until the person accepts it, so neither a wrong answer nor
  instructions hidden in a copied studyset (prompt injection) change the library.
- **D11 Progress never goes along** (over a chip for it, which was recommended): no
  reviews, ratings, statistics or study time, in any scope.
- **D12 Text first, images when ticked or asked for** (the developer: "Can't it generally
  be text, only images if necessary (e.g. graphs within a PDF)?"; then the recommended
  way): text by default, a PDF's as PDFium reads it; where a part in scope holds an image
  (a card's picture, a PDF page with figures), its image is a chip of its own, off; and
  the model may ask for one, which the person approves each time. Only for an assistant
  that reads images. The app can't tell by itself when an image is needed: a graph is
  often drawn as lines, not stored as a picture.
- **D13 Conversations are kept, sealed** (recommended, over this device only and over
  none): in a synced table sealed with the person's own key (ADR 0019, as their settings
  and tags), so they reach all their devices and the instance can't read them, as Proton
  can't read Lumo's stored chats; kept until the person deletes one.
- **D14 The first version does four things:** answers questions about what is open, in
  the field on Home, in the Library, on a studyset and in a session (D7's scopes); makes
  cards from text (a paragraph, a note, a PDF page) as drafts (D10); explains, in a
  session after Bad, why the answer is what it is, from the card's own parts; and checks a
  written answer or a sentence written in the studyset's language, saying what is wrong
  and why, as feedback, changing nothing.
- **D15 The module and a package of its own** (recommended, over Learn alone first):
  grants, limits, statistics and the forwarding are halkyon_base's, the register's, one
  per instance as accounts are, so a person's grant and limits hold in every service of
  the instance; the two adapters (5) are `halkyon_llm`, a pure Dart package, BSD-3-Clause
  as `halkyon_oidc` is, in the monorepo, its publishing to pub.dev asked first; the field,
  the scopes and their tools are Learn's.
- **D16 Points 4 to 8 and 10 of the proposal stand as written** (recommended, over going
  through them one by one); what comes up while building is put to the developer.
- **D17 The warning of D9 is asked once per studyset and assistant** (recommended, over
  once per session and every time), as explaining a miss and checking an answer go out
  once per card: the answer is kept in the person's sealed settings, the studyset's
  privacy dialog shows it with Take back, and the assistant's button in that studyset
  carries a mark while it holds.
- **D18 Built for v0.21.0** (over shipping the batch held for it first, which was
  recommended, and over later): the batch on `feat/remove-github` (GitHub's removal,
  build 24) waits for it.
- **D19 `SIGN_UP` takes three values** (recommended, over approval on or off alone and
  over invitation links now): `open`, `approval`, `closed` (point 1).
- **D20 The first operator by SQL** (recommended, over a one-time setup code, over a
  handle in `deploy/.env` and over the instance's first account): the operator signs up
  in the app, then, on the server, one statement written here makes that account an
  operator and approves it. No code hands out the role, so nothing is there for a
  stranger to guess; whoever runs an instance reaches its database anyway.
- **D21 Further operators are named in the app** (recommended, over SQL for each): an
  operator names another by handle and can take it back; the last operator can't be
  removed.
- **D22 An operator can suspend an approved account** (recommended, over deleting it too
  and over grants alone): its sessions end and it waits again, nothing syncing, its data
  kept, until an operator approves it anew. Deleting stays the person's own act, or the
  operator's SQL.
- **D23 A waiting account shows a wait screen only** (recommended, over using the app on
  the device until approved): it says the account waits for the operator, and offers to
  delete it; nothing syncs or uploads, so a refusal loses nothing.
- **D24 A matching code tells the operator who waits** (recommended, over an
  introduction line and over the handle alone): the wait screen shows a short code of
  four words, and the operator sees the same code beside the handle, asking the person
  (by phone, in person) what theirs says; a stranger who took a family member's handle
  can't know it.
- **D25 The limits stand as proposed** (recommended, over 7 days and over 30): deleted
  after 14 days unapproved, at most 10 waiting at once, sign-ups per network limited as
  today's, a badge in the operator's app as the only notice.
- **D26 Someone refused may sign up again and wait again** (recommended, over refusing
  their SimpleLogin identity for 30 days): nothing about them is kept; the cap and the
  network limits hold strangers back.
- **D27 Each instance says what its assistants do, in the app and on a page of its own**
  (over the app alone, which was recommended, and over the website's page alone, which
  describes learn.halkyon.eu): the consent sheet when a grant is first used, the same
  facts in Settings › Assistant at any time, and `/privacy` on the instance's web server,
  made from its settings in English and German as the profile pages are, readable before
  signing up (point 9).
- **D28 Others' posts go to a model only with their author's agreement** (the developer:
  "not to send the content from others without their explicit (direct or indirect)
  agreement to LLM providers"; recommended, over a licence for one's posts and over
  never): a switch in the account's settings, "Others may send my posts to their AI
  assistant", off unless switched on and shown on the profile; while it is on, their
  posts in discussions and feedback threads are chips like the others, off. The rule
  binds what Halkyon sends on a person's behalf: someone who copies text into a model by
  hand acts on their own, and the app doesn't try to stop it. No standard says this yet
  (25 Oct): the IETF's AI preferences are drafts naming training and search, not a
  model's answer; Creative Commons' signals are still being worked out. Should one come,
  the switch can be expressed in it.
- **D29 A copy's licence is its agreement** (recommended, over an author's switch per
  studyset): publishing takes a licence that allows passing on (ADR 0005), so a copy is
  the person's own to send.
- **D30 The provider learns an opaque ID per person** (recommended, over nothing): with the
  operator's key, each request carries an ID the instance derives from the account with a
  key of its own (OpenAI's `user`, Anthropic's `metadata.user_id`), never the handle, so
  the provider can act against one person's abuse without blocking the operator's key,
  and can't tell who it is.

## Proposal

1. **Who signs up, per instance:** `SIGN_UP`: `open` (as today), `approval`, or
   `closed`. On halkyon.li `approval`.
2. **The operator** is a role on the register. The first one by SQL (D20), the others
   named in the app (D21); an operator approves, refuses and suspends accounts (D22),
   grants assistants with their limits, and sees everyone's figures, never content.
3. **Waiting accounts** (D1): after signing up (SimpleLogin, handle, keys: ADR 0020), an
   account waits. Its sessions can only see that they wait, or delete the account;
   nothing syncs and nothing uploads (D23). The operator sees who waits in the app (the
   handle, when they signed up, which is all the instance knows, and the matching code of
   D24) and approves or refuses; a refusal deletes the account. Unapproved after 14 days, it is deleted. At most 10
   waiting at once, and sign-ups per network limited as today's, so strangers can't flood
   the list. The operator's app shows a badge; there is no mail, as the instance keeps no
   addresses.
4. **The assistants**, set by the operator (D4): one or more, each with an ID, the name
   people see ("Claude Sonnet"), its protocol (`anthropic`, or `openai` for every
   OpenAI-compatible service), its base URL (the provider's own unless set) and model in
   `deploy/.env` (`ASSISTANTS=claude,gpt`, then `ASSISTANT_CLAUDE_NAME`, `_PROTOCOL`,
   `_BASE_URL`, `_MODEL`), and its key in the passwords (`ASSISTANT_CLAUDE_KEY`). There
   rather than in the app: the keys stay out of the database and its hourly backups, where
   the operator keeps the instance's other secrets. None set: no assistant on the
   instance, as today. Adding Lumo once its API is out, or switching a model, is a change
   of these and a restart; no app changes.
5. **Two adapters of our own** behind one interface, over plain HTTP, no SDKs, in a pure
   Dart package of their own, which the server uses for the operator's assistants and the
   app for personal keys (10). Features use only what both protocols share: a system prompt and messages,
   streamed text, and tool calls where a feature needs them. Tested against recorded
   replies of each. Not chosen: LiteLLM as a sidecar (a Python proxy for about 100
   providers: one more container to run and update, for providers never used) and
   langchain_dart (a large framework for a small job).
6. **Grants** (D2, D4): nobody has an assistant until the operator grants it to them, one
   assistant at a time, each grant with its limits. The person agrees once to what goes where: the provider's name, that the
   instance sees the text on its way, and that the operator sees how much they used,
   never what.
7. **Asking:** the field offers the assistants granted beside the web search (the one last
   used first), the app shows what it will send, the person sends it to the instance
   (`assistant.ask`, the answer streamed), the instance checks the grant and what is left
   of the limit, forwards the request, and counts what the provider's reply reports
   (input and output tokens). Past the limit it refuses (`limitReached`), saying when it
   resets. A private studyset (ADR 0019) goes only as far as the person sends it,
   decrypted on the device for that request. The scope (D7) holds the conversation: the
   app runs the tools' loop, answering each lookup from the person's local data within
   it, so with the operator's assistant the lookups' answers pass through the instance as
   the question does. A draft (D10) arrives as a tool call the app opens in the editor.
   Whether an assistant reads images (D12) is its setting (`ASSISTANT_CLAUDE_IMAGES`; for
   a personal key, a switch beside it).
8. **Limits and statistics** (D3): per grant, per day and per month (a day's limit stops a
   runaway loop early). Counted per person, day and assistant: requests, input and output
   tokens, and the cost at the prices the operator enters per model (per million tokens;
   without prices, tokens only, and limits in tokens). Neither prompts nor answers are
   kept. The operator sees everyone's figures in the app, per person and month; each
   person sees their own.
9. **What people are told** (D27): the provider and model, what is sent, that the instance
   sees it in passing, that the operator sees each person's figures, that the instance
   keeps no content, and that conversations are kept sealed on the person's devices
   (D13).
10. **Personal keys** (D5, D6), where the operator switches them on (`ASSISTANT_OWN_KEYS`,
    off unless `on`; `instance.info()` says so, and the app offers them only then): a
    person adds a provider in Settings (protocol, base URL, model, their key), and may add
    several. The key goes into their settings, which are sealed with their personal key
    (ADR 0019), so it reaches their other devices and the instance can't read it. The app
    calls the provider directly with the same adapters (5); the instance sees neither key
    nor text and counts nothing, and the person's limits are their provider's. The
    instance can't stop a modified app from doing so, and needn't: nothing passes through
    it. Personal assistants are offered in the field beside those granted.
11. **Never sent, in any scope:** the password, the account's keys, the recovery phrase,
    codes, API keys, the Jellyfin token, other people's data (but posts whose author
    agreed, D28), and progress (D11). Nothing is asked without the person: no assistant
    runs in the background.

## Consequences

- The operator pays the provider, and sees who used how much, never what for.
- The instance sees what is asked on its way to the provider, and the lookups' answers;
  the provider's own terms then apply to it. A private studyset leaves end-to-end
  encryption wherever it goes to a remote model (D9).
- A provider that is down stops the assistants on it; the others granted, personal keys
  and the web search go on.
- Strangers can sign up and wait, but can't use anything, and their accounts lapse.
- Public instances keep the rule of 10 Oct: their operators leave the assistants unset,
  and may allow personal keys.