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.