Why BYOB?
- Zero Subscription Markups: You only pay the raw token usage fees directly to the AI providers (such as OpenAI or Anthropic). For typical note-taking and outlining, this costs pennies a month compared to a $20/month subscription. Each send includes the tree outline unless you shrink it — see Token usage with Joe.
- Model Choice: You choose exactly which model drives Joe—whether you want the speed of a lighter model or the reasoning of a frontier model.
- Privacy & Control: Your keys and chats are never routed through FlowJoe servers. Connections are established directly from your local desktop application to the AI API endpoint.
🔒 API Key Storage & Fallbacks
FlowJoe uses a multi-tier storage design for your keys to balance security and convenience:- OS Secure Storage (Default): Inside the desktop Electron wrapper, FlowJoe prioritizes storing keys in your operating system’s native secure credential manager (macOS Keychain, Windows Credential Manager, Linux Secret Service).
- Plaintext Safety: Keys are never written to project JSON files, shared synced directories, or git version control systems.
Viewing & Copying Your Key
For easy verification, you can inspect or copy your stored API key:- Open Settings → APIs → API Settings.
- By default, the key is hidden behind a password mask (
••••••••). - Click the Eye icon on the input field to reveal the plaintext key, allowing you to quickly verify or copy it to your clipboard.
Configuring Your AI Brain
To adjust your model config:- Open Settings → APIs → API Settings and paste your key.
- Click the model settings button inside the Joe panel — or the brain name in the status bar — to pick the brain behind Joe:
- OpenAI models (API key): Sol 6.1, Luna 6 (the default), Sol 6, and Astra 6, plus Luna, Terra, and Sol from the GPT-5.6 family.
- CLI brains (no API key): route Joe through an agent CLI you have already installed and signed into on your own machine — Fable 5.1, Opus 5.5, Opus 5, Sonnet 5.5, Sonnet 5, Haiku, Grok, Antigravity, or Antigravity (3.7). Desktop only.
- Temperature and response length are managed automatically per model — there is no manual temperature dial, and GPT-5.6 / GPT-6 models run at their fixed default temperature.
Where to get an OpenAI key
Create one at platform.openai.com/api-keys, then paste it into Settings → APIs → API Settings. Keys start withsk-. You pay OpenAI directly for what you use; FlowJoe never takes a cut and never sees the key.
What CLI brains need first
A CLI brain is not something FlowJoe installs for you. It appears in the picker only once the matching command-line tool is installed on your machine and you have signed into it in your own terminal:
If a brain is greyed out in the picker, that tool is either missing or not signed in. These brains bill through that tool’s own account rather than an API key you paste here — which is why they need no key at all.
A CLI brain honors the same flow permission level (Off / Read / Propose) as OpenAI — it cannot read or propose changes to your flow beyond what your current permission allows, and this is enforced independently of what the brain itself claims. If something goes wrong on a CLI brain’s turn, FlowJoe tells you what actually happened (for example, “your conversation is too large for this brain” or the brain’s own error text) instead of a generic “sign in again” message. On Windows, a CLI brain that can’t be driven safely from FlowJoe is shown greyed out with a note, rather than failing with a confusing error.
What happens with no key and no CLI brain
Joe’s chat, the AI writing actions, and image generation stay unavailable until at least one brain is set up, and the app will say so when you try to use them. Everything else works normally without any key — your tree, galleries, notes, documents, workspaces, and import/export are entirely local and never need an AI provider.Making Joe faster: the optional TypeSafe key
Before Joe answers, he first works out what he needs to look at — whether you are asking him to change something, whether he needs the shape of your flow, which part of the manual is relevant. That step normally takes about a second. Add a TypeSafe API key and that decision runs on a model built purely for fast structured judgments, taking roughly a fifth of a second instead — on every message, whichever brain you are using. The difference is largest on the CLI brains (Claude, Grok, Antigravity). Those used to start up a second copy of the command-line tool just to ask that one question, and wait up to fifteen seconds for it. That no longer happens.- It is entirely optional. Without a key, everything works exactly as it does today — including the flow map, which is then never trimmed (see below).
- If the key is missing, wrong, expired, or the service is unreachable, FlowJoe quietly falls back to the normal path. Nothing breaks — Joe is simply not faster, and the map is not trimmed.
- It is stored as securely as your OpenAI key, and it is a separate key: adding or removing one never affects the other.
- It is desktop only. The Test button explains when TypeSafe is unavailable rather than reporting a network error.
It also trims a big flow map
With a TypeSafe key, the same model does a second job: when you send Joe your whole flow, it picks out the parts relevant to what you just asked. This only applies when you have unticked both map options in the chat box — “Omit entire flow map” and “Limit map to my location”. That is the case where Joe sees your entire tree on every message, which on a large flow is most of what you are sending him. On a 274-node flow, one such question kept 41 nodes — the right branch and its parents — and left out the rest.- Nothing is hidden from Joe. The map tells him it has been trimmed, how many of your nodes it is showing, and that anything not listed still exists. He can pull the full tree whenever he needs it, and is told to do that before ever saying something of yours does not exist.
- Questions about the whole flow skip it. “How many nodes do I have?”, “what am I neglecting?”, “do I have anything about X?” — these cannot be answered from a subset, so they get everything.
- Any problem sends the whole map. A slow answer, a garbled one, an answer that only covers some of your nodes, or a flow you edited while it was thinking — all of them fall back to the full tree. It never quietly sends Joe less.
- Small flows are left alone (under 60 nodes), and so are flows you have already narrowed with “Limit map to my location” — that is your choice of branch, not something to second-guess.