AI configuration
Who runs the models for your organization — your own provider keys, or ours. The switch that decides whether a build costs credits, what self hosted asks for, and who can change it.
Bookbag holds no AI provider key. Which models your builds can run on, 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. Bookbag asks it for a model when a build starts; no key is stored here and none reaches your browser.
The same configuration therefore answers in Openbook and Madebook too. One organization, one arrangement, three products.
This used to be a setting on your account. Bringing your own AI key was per-person, at
/account/ai, and it is not there any more. A provider key belongs to the organization a project is filed under, not to a person, and there is one place a key lives now. The bargain is unchanged — your key, your provider's bill, no credits — but it is set on the organization's AI page and it applies to everyone building in that organization.
The page
Pick your organization in the sidebar and open AI self hosted, between Storage and Settings. Its address is /organizations/<id>/ai.
Who runs the models for this organization, and which ones.
The builder and everything else here pick from what is configured below. Keys are held by Bookbag and never reach this page.
You can also get there from Bring your own AI on your account page, which is now a link rather than a form:
Set on {your organization} — switch it to self hosted, add your own provider key, and builds cost no credits because the provider bills you directly.
The sidebar item is called AI self hosted whichever mode you are in. It does not rename itself when you hand the models back to us, so read the switch at the top of the page rather than the label in the sidebar.
The one decision
Who runs the models. 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, and a build costs no credits. |
| Managed by us | We run the models and pay the provider. Nothing to configure, and no key of yours involved — builds are metered in Bookbag credits instead. |
This is the switch that decides whether builds spend credits. It is the whole of the difference:
| Self hosted | Managed by us | |
|---|---|---|
| Credits charged | Zero | Yes, per run |
| Credit check before a run | Skipped | Yes |
| Run stops if credits hit zero | Not applicable | Yes, mid-run, keeping what was built |
| Who bills you | Your provider, directly | Bookbag, in credits |
| Which model | Your starred default | The platform's starred default |
| Everything else about a build | identical | identical |
Sandboxes, the preview, publishing, version history, the security check and the step limits are all exactly the same either way.
Neither mode falls back to the other, deliberately. An organization that switched to its own key and then broke it gets an error naming the fix — it does not quietly become a metered run on the platform's bill. Quietly spending credits while somebody believed they were on their own key is the worse surprise, so it does not happen.
Switching is one click and applies to the next build. A toast confirms it: We run the models now, or You run the models now.
Managed by us is greyed out with "Nothing is on offer yet — the platform has no model configured" when the installation has no usable platform key. Until an administrator fixes that, self hosted is the only working choice — and on an installation in that state, nothing builds until an organization brings its own key.
Which to pick
- Self hosted if you would rather pay the provider at cost with no credits in the way, if you want a model Bookbag does not offer, or if you already have a provider account with negotiated rates or spending controls.
- Managed by us if you would rather not hold a key at all. Credits exist for exactly that; they are not the only way in.
It applies to everyone in the organization
Credits are yours — your balance, your monthly top-up, your ledger. Whether a build spends them is the organization's.
So switching an organization to self hosted stops credits being spent by everyone building in it, not just by whoever flipped the switch. And switching it back to managed means every member's builds start drawing on their own balances again. Bear that in mind before changing it in an organization you share.
Self hosted
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. With none: "No keys yet. Without one, nothing in this organization can call a model."
Six providers take a key:
| Provider | Where the key comes from | Shape |
|---|---|---|
| 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 others take one optionally, where it overrides the vendor's default host — a regional gateway, or a proxy.
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 replaces the first.
- Deleting a key deletes the models bound to it: 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.
What each provider can actually do
Chat is universal, and chat is what the builder needs. Images and embeddings are not, and it is worth knowing before you pick a vendor for anything beyond building.
| 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.
One exception. A key that carries an endpoint of your own is not reaching that vendor at all — it is reaching your gateway or proxy — so the call is attempted and whatever your endpoint answers comes back verbatim.
Your own endpoint
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 and 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: Your endpoint is configured.
Three things the page says that are each otherwise a support ticket:
- 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 and not by your machine.
localhost,127.0.0.1, a box on your desk and anything behind a VPN the platform is not on will all fail, however well they work in your own terminal. A server on a private network 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}/modelsthat 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.
A model added this way is taken at your word about its capabilities, and it is marked as supporting tools — which the builder requires.
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 — only ones that both support browsing and already have a key are offered, otherwise the picker reads Add a key first — and press Browse models. With more than one active key for a provider, a Whose key picker appears. What comes back is what the provider offers now, minus what you already have. If there is nothing: Nothing new to add.
Each row is labelled by kind — Chat, Embedding, Image, Speech to text, Text to speech, Realtime — worked out from the 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 builder uses unless a project overrides it — it must support tools, or the builder 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 | Tools, Vision, Voice. |
| Rate | Credits per 1,000 tokens, 1 to 100. It applies to managed builds; a self-hosted build charges nothing whatever this says. |
| Active | Whether anything may pick it. |
| Default | The star. |
Starring makes a model the default for its kind, clears every other star of that kind, and activates it — a default nobody can run is a trap. Only chat models can be starred from this table; others show Defaults apply to chat models.
Tools are not optional
The builder works entirely by calling tools: reading files, writing files, running commands. A model that cannot call tools cannot build anything. Make sure the starred default carries the Tools badge.
With chat models but none active: "No chat model is active, so nothing in this organization can call a model yet."
The starred default is, in practice, the only control over which model builds your app. The page's copy mentions a project overriding it, and a project does carry a pinned model that the builder honours — but there is no control anywhere in the interface that sets one. Unless somebody set it another way, every build in the organization runs on the starred default.
Managed by us
The four cards above are replaced by two, and the Provider keys card is absent, not disabled. 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 build will answer on, and lists the platform's active models with their capabilities and which one is starred. With nothing 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. 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 do not pick from the catalog. What runs is the platform's starred default, and what you spend on it is the Rate the platform set for that model. See How a build spends credits.
Who can change these settings
An owner or an admin of the organization. Members and viewers see the page read-only, under a banner:
Only an owner or an admin of this organization can change these. You can see what is available.
Everybody can read it, because a project's model picker needs the list, and because what a build will run on is not a secret from the person starting it.
| Action | Who |
|---|---|
| Open the page and read what runs | Any member of the organization, viewers included |
| Switch between self hosted and managed | Owner or admin |
| Add, deactivate or remove a provider key | Owner or admin |
| Configure your own endpoint | Owner or admin |
| Browse, add, rename, activate, star or remove a model | Owner or admin |
| Configure the platform's keys and catalog | A platform admin, at the account service |
Roles are held at your Bookbag account and are the same in every product — see Roles and permissions. A platform administrator can also reach the page for any organization.
The server re-checks every write, so a member who reaches the controls another way is still refused: Only an owner or an admin can change this.
The platform's own keys
The key the platform runs on, and the catalog it offers organizations in managed mode, are set at the account service and not in Bookbag. The admin area links out to both — see Platform AI.
When a build will not start
| Message | What it means | The fix |
|---|---|---|
| No models are configured yet. | Nothing has been added in the resolved scope. | Add a key and a model here, or ask an administrator to configure the platform's. |
| Models exist but none are switched on. | Everything is deactivated. | Tick Active on a chat model. |
| The active models cannot call tools, so the builder cannot read or write a file. | The active model cannot call tools. | Activate one with the Tools badge. |
No active <provider> API key is configured. |
The starred model's provider has no active key. | Re-add the key, or tick it active. |
| You are out of credits. | Managed mode, and your balance is at or below zero. | Wait for the top-up, ask an administrator, or switch this organization to self hosted. |
If an amber strip reads "Keys cannot be stored yet", the installation has no encryption key configured. There is deliberately no plaintext fallback — a key that cannot be encrypted is not stored at all — and it is for whoever runs the installation to fix.