AI configuration
Who runs the models for your organization — your own provider keys, or ours. The two modes, what self hosted asks for, what managed costs, and who is allowed to change it.
Openbook does not hold your AI provider keys. Which models your organization can call, and whose account pays for them, is configured once in the Bookbag account service — the same place that holds your sign-in, your organizations and your files. Openbook asks it a question every time something needs a model, and gets back an answer; no key ever reaches Openbook, and none ever reaches your browser.
That is why the same configuration answers in Madebook and in Bookbag too. One organization, one arrangement, three products.
The page
Pick your organization in the sidebar and open AI self hosted. It sits between Storage and Analytics, at /organizations/<id>/ai.
Who runs the models for {your organization}, and which ones. The chat assistant, the build agent and everything else here pick from what is configured below. Keys are held by Bookbag and never reach this page.
The sidebar item is called AI self hosted whichever mode you are in. It does not rename itself to "AI managed" when you hand the models back to us — so do not read the label as a statement about the current setting. The switch at the top of the page is the statement.
The one decision
At the top of the page is a pair of cards under Who runs the models, and the page is blunt about what they are:
This is not a preference — it decides whose key every model call is paid with. Neither mode falls back to the other.
| Mode | What it means |
|---|---|
| Self hosted | Your own provider keys and your own models, including your own OpenAI-compatible server. The provider bills you directly. |
| Managed by us | We run the models and pay for them. Nothing to configure, and no key of yours involved. |
Neither mode falls back to the other, and that is deliberate. An organization that switched to its own key and then removed it gets a plain error naming the fix, not somebody else's bill. Equally, a managed organization never quietly reaches for a customer's key.
Switching is one click and takes effect on the next call. A toast confirms it: We run the models now, or You run the models now.
Managed by us is greyed out when there is nothing to be managed by: "Nothing is on offer yet — the platform has no model configured." That means whoever operates this installation has not configured a platform key or a model catalog at the account service. Until they do, self hosted is the only working choice.
Which to pick
- Self hosted if you already have a provider account, if your procurement or compliance people need the contract to be with the model vendor rather than with us, or if you want a model we do not offer — including one running on your own hardware.
- Managed by us if you would rather not hold a key at all. Nothing to paste, nothing to rotate, nothing to be invoiced for by a third party.
Self hosted
Four cards appear, in the order you need them.
Provider keys
Checked against the provider before they are stored, then encrypted. A key the provider rejects is never kept. Only the last four characters are ever shown, and adding a key for a provider replaces the one it already has.
Choose a Provider, give it an optional Label (Production key), paste the API key, and press Add key. On success: Key verified and saved.
Six providers take a key here:
| Provider | Where the key comes from | The key looks like |
|---|---|---|
| OpenAI | platform.openai.com → API keys | sk-… |
| Anthropic | console.anthropic.com → API keys | sk-ant-… |
| DeepSeek | platform.deepseek.com → API keys | sk-… |
| xAI (Grok) | console.x.ai | xai-… |
| Google (Gemini) | aistudio.google.com → Get API key | AIza… |
| Azure OpenAI | the Azure portal, on your OpenAI resource | 32 hex characters |
Azure OpenAI also asks for an Endpoint, because an Azure deployment has no fixed host — the field appears when you pick it. The other five accept one optionally, and it overrides the provider's default host: use it for a regional gateway or a proxy in front of the vendor.
Each stored key shows its provider, a hint of the key, its label, any error the provider last reported, an active tick box and a delete button.
- One key per provider. Adding a second OpenAI key replaces the first.
- Deleting a key deletes the models bound to it — the toast says so: Key removed — the models bound to it went with it. A model with no key behind it could never run again.
- Unticking
activeis the non-destructive way to take a provider out of service. The key and its models stay.
What each provider can actually do
This is not uniform, and it is the thing most likely to waste an afternoon. Chat is universal; images and embeddings are not.
| Provider | Chat | Images | Embeddings |
|---|---|---|---|
| OpenAI | yes | yes | yes |
| Google (Gemini) | yes | yes | yes |
| Azure OpenAI | yes | yes, deployment-addressed | yes, deployment-addressed |
| xAI (Grok) | yes | yes | no |
| Anthropic | yes | no | no |
| DeepSeek | yes | no | no |
| Your own OpenAI-compatible server | yes | whatever it implements | whatever it implements |
A no is refused with a sentence naming a provider that can, rather than sent and failed:
This organization has a DeepSeek key, which cannot generate images. Add an OpenAI or Google (Gemini) key in its AI settings.
Anthropic has no API that can produce embeddings — OpenAI, Google (Gemini), Azure OpenAI or your own OpenAI-compatible server can.
With one exception. A key that carries an endpoint of your own is not going to that vendor at all — it is going to your gateway or proxy — so the request is attempted and whatever your endpoint answers comes back verbatim. That is the escape hatch for a real deployment that does implement it.
Your own endpoint
A separate card, because a URL, an optional key and a model identifier are one decision.
A vLLM, Ollama, LM Studio or any other server of yours, and any gateway in front of one. The whole contract is this: it must answer
POST {base URL}/chat/completionsin the OpenAI chat-completions shape — the same request and response body OpenAI documents. If it does, it works here; nothing else about it matters.
Four fields, one button:
- Base URL — for example
http://vllm.internal:8000/v1. - Model identifier — exactly what your server calls the model, for example
meta-llama/Llama-3.1-8B-Instruct. - Name (optional) — what you want to see in the models table.
- API key (optional) — leave it empty if your server has no auth, which many do not.
Press Use this endpoint and the key and the model are created together.
Three things the page says that are worth repeating, because each one is a support ticket otherwise:
- The server must be reachable from Bookbag, not only from your laptop. The call is made by the account service, from wherever it runs — not by your browser.
localhost,127.0.0.1, a machine on your desk and anything behind a VPN the platform is not on will all fail, however well they work in a terminal on your own machine. If the server is inside a private network, it needs an address the platform can route to: a public hostname, a tunnel, or a gateway you expose deliberately. - A server with no model list is fine. If it does not publish one at
{base URL}/models, that is accepted and noted against the key — which is why you type the model identifier here rather than browsing for it. - There is one of these per organization. Adding another replaces it.
Add a model
Browse what the provider offers right now. Models released after this app was built appear here on their own.
Pick a provider and press Browse models. Only providers that both support browsing and already have a key are offered; if you hold more than one active key for a provider, a Whose key picker appears. What comes back is what the provider offers right now, minus what you already have. Pick one and it is added. If there is nothing new: Nothing new to add.
Each row is labelled with its kind — Chat, Embedding, Image, Speech to text, Text to speech, Realtime. The kind is worked out from the model's identifier, because no provider's model list reports what its models can do. Well-known families are recognised; anything unfamiliar arrives as a plain chat model rather than being hidden, so a model released this morning is still selectable this afternoon.
Models
Only active models appear in pickers. The default is what the build agent uses unless a room overrides it — it must support tools, or the agent cannot edit a file.
| Column | What it is |
|---|---|
| Model | The display name. Click it and type to rename. |
| Provider | Which provider, and underneath, which key it rides on. |
| Identifier | The provider's own name for it. |
| Capabilities | Up to three badges: Tools, Vision, Voice. |
| Rate | A number from 1 to 100 stored on the model record. Nothing charges against it any more — the token allowance counts raw tokens, not a per-model multiple. It is left over from the credit system and is kept only because it is still part of the model record at the account service. Ignore it. |
| Active | Whether anything may pick it. |
| Default | The star. |
Starring a model makes it the default for its kind, clears the star from every other model of that kind, and activates it — a default nobody can pick is a trap. Only chat models can be starred from this table; other kinds show Defaults apply to chat models. An organization can hold a default chat model and a default image model at the same time.
If you have chat models but none is switched on, an amber note appears: No chat model is active, so nothing in this organization can call a model yet.
Managed by us
The four cards above are replaced by two, and the Provider keys card is not disabled — it is absent. There is no key of yours in this arrangement, so there is nothing to show you.
We run and pay for these. The platform holds the key and settles the provider bill. You configure no key here at all — which is why there is no Provider keys card in this mode.
- The first card names the model a call will answer on, and lists the platform's active models with their capabilities and which one is starred. If nothing is starred: No model is starred as the default yet, so the first active one answers.
- The platform catalog lists what the platform offers organizations — model, provider, identifier and notes, with retired entries marked. It is reference only: nothing here needs a decision from you, and nothing here costs you a provider account. If it is empty, "The catalog is empty. A platform administrator fills it in at Bookbag."
You cannot pick from the catalog. What runs is the platform's starred default; the list is there so you can see what you are getting.
What each mode means for the bill
| Self hosted | Managed by us | |
|---|---|---|
| Whose provider account is charged | Yours, directly by the provider | The platform's |
| What you paste | A key per provider | Nothing |
| Which models are available | The ones you added | The platform's active models |
| What Openbook adds on top | Nothing — it does not resell tokens | Nothing extra beyond your plan |
This switch is what decides whether anything is metered at all. Every model call in Openbook — the assistant, the build agent, a workflow, the concierge, an image, an embedding — goes through the Bookbag account service, which records what it cost as the tokens are spent.
| Self hosted | Managed by us | |
|---|---|---|
| Counted against the token allowance | Recorded, but as zero | Yes |
| Can be refused for being over it | Never | Yes, before any provider is called |
The allowance caps what the platform pays for, not what you may use. An organization on its own key costs the platform nothing, so there is nothing to cap. See AI usage & the token allowance.
Openbook's credits are gone. There is no balance, no monthly top-up and no per-plan credit allowance any more; tokens are metered once, at the account service, against the organization owner's account and shared with every Bookbag product. Any balance you had was carried across as one-off headroom. See What happened to credits.
Who can change these settings
Only the organization's owner. Not admins, not members.
Everyone else in the organization sees the page, read-only, under a banner:
Only the organization owner can change these. You can see what is available.
That is deliberate — a model picker in a room needs the list of models, so members must be able to read it. Behind the page the rule is the same: every write is refused for anyone but the owner with "Only the organization owner can change AI settings.", and someone who is not in the organization at all gets "You are not a member of this organization."
Owner-only extends further than you might expect: Browse models and the platform catalog are owner-only too, because both are reference data an owner decides against.
| Action | Who |
|---|---|
| Open the page and read what runs | Any member of the organization |
| Read the token usage bar | Any member |
| Switch between self hosted and managed | Owner |
| Add, deactivate or remove a provider key | Owner |
| Configure your own endpoint | Owner |
| Browse, add, rename, activate, star or remove a model | Owner |
| Set the per-space agent gates | Owner |
| Configure the platform's keys and catalog | A platform admin, at the account service |
Ownership itself is changed at the Bookbag account — see Transferring ownership.
The platform's own keys
The key the platform runs on, and the catalog it offers organizations in managed mode, are a platform administrator's job and are set at the account service, not in Openbook:
- Platform AI —
/admin/aiat the account service. The platform's own provider keys and models. - Model catalog —
/admin/model-catalogthere. What organizations are offered in managed mode.
Openbook's own admin area has no AI page any more. Its The platform brain section carries two outbound links, Platform AI ↗ and Model catalog ↗, which open those pages. See Platform administration.
When something will not run
The refusals name the fix and say where, and which one you get depends on the mode:
| In self hosted mode | In managed mode |
|---|---|
| This organization has no chat model. Add a provider key and a model in this organization's AI settings. | The platform has no chat model. A platform administrator configures it at Bookbag SSO — or switch this organization to self hosted and use your own key. |
| This organization has chat models but none are switched on. | The platform has chat models but none are switched on. |
And in either mode, when the model that is running cannot call tools:
The active models here cannot call tools, so the agent cannot read a file or write a story. Activate one that supports tools (GPT-4o or Claude Sonnet, for example).
If keys cannot be stored at all, an amber strip reads "Keys cannot be stored yet" with the reason. That means the account service has no encryption key configured — there is deliberately no plaintext fallback — and it is for whoever operates the installation to fix.
Where to go next
- Where the assistant shows up once this is configured: The AI assistant
- What the allowance is and what it caps: AI usage & the token allowance
- The agent that works against a repository: The build agent
- The chat that builds spaces and rooms for you: The concierge