Bringing your own AI key
Add your own provider key and your builds run on it, billed by the provider, spending no Bookbag credits. Setting it up takes about a minute.
Bookbag lets you supply the AI yourself. Add a key from OpenAI, Anthropic, DeepSeek or xAI under Account → AI, and every build you start runs on your key. Your provider bills you for exactly the tokens used. Bookbag charges nothing.
This is a first-class path, not a workaround. The page's own framing:
Add your own provider key and your builds run on it — billed by the provider, at cost, with no Bookbag credits spent. Remove it any time and you fall back to the platform model.
Why you might
- Cost. You pay the provider's price with no markup, and you see it on their bill.
- Model choice. You can run any tool-capable chat model your key can reach, including one released after this version of Bookbag was written.
- Your own arrangements. If you already have a provider account with negotiated rates or spending controls, builds go through it.
Setting it up
/account/ai, reached from the Bring your own AI card on /account.
1. Add the key
The first card is Your provider keys:
Checked against the provider before they are stored, then encrypted. Only a hint is ever shown, and the key never leaves the server. Adding a key for a provider replaces the one it already has.
Three fields:
- Provider — OpenAI, Anthropic, DeepSeek or xAI (Grok).
- Label (optional) — for your own reference, e.g.
Personal key. - API key — a password field. The placeholder shows the shape the provider uses:
sk-…,sk-ant-…,xai-….
Press Add key.
The key is checked against the provider before it is stored. If it does not work you are told immediately rather than at your next build:
| Message | Meaning |
|---|---|
| That API key was rejected by the provider. | Wrong key, or it has been revoked. |
The provider returned <status>. |
The provider answered with something else. |
| Paste an API key. | The field was empty. |
| Unknown provider. | Should not happen from the UI. |
On success: Key verified and saved.
The key is encrypted at rest with AES-256-GCM and is never sent back to the browser. All you ever see afterwards is a hint — the first four and last four characters.
You may hold one key per provider. Adding a second for the same provider replaces the first.
2. Add a model
The second card is Add a model:
Browse what your key can reach right now. Only models that support tool calling are listed — a builder that cannot call tools cannot write a file.
Choose the provider and press Browse models. Bookbag asks the provider what your key can reach and shows the new ones as pills. Click one and it is added.
That filter matters: the builder works by calling tools — reading files, writing files, running commands. A model that cannot call tools is useless here, so those are not offered.
If the list is empty you get Nothing new to add for that provider. — everything the provider offers is already in your catalogue.
Adding a model by name. A model released very recently may not be recognised as tool-capable and so may not appear. Open Add a model by identifier, type the provider's exact model name and a display name, and press Add. Bookbag takes you at your word about its capabilities.
3. That is it
The first model you add automatically becomes your default, and the default is what runs your builds. One key plus one model is the whole setup.
The badge at the top of the page turns green and reads <provider> · <model> — for example anthropic · claude-sonnet-4-5. Before that it reads Using platform AI.
Choosing which model runs your builds
The third card, Your models:
The starred default runs your builds. While any of these is active, you are not spending credits.
A table with Model, Provider, Identifier, Active and Default. The star makes a model the default; making a model the default also activates it, because a default nobody can run is a trap.
The starred default is the only control you have over which model builds your app. There is no per-project or per-run model picker. If you have no models of your own, the platform's default is used.
Going back to credits
Two ways:
- Untick Active on your models. With no active model, builds fall back to the platform's and spend credits again.
- Remove the key. The trash button is tooltipped Remove this key and its models — removing a key also removes every model for that provider, because with one key per provider there is nothing left to run them on.
The one failure mode to know about
If you have an active model but no working key for its provider — you unticked the key, or it was revoked — builds do not fall back to credits. They fail:
Your
<provider>key could not be read — re-add it under Account → AI, or deactivate your models to fall back to the platform model.
This is deliberate. The alternative — quietly spending platform credits while you believed you were on your own key — would be the worse surprise. The message tells you both ways out.
What changes, and what does not
| On credits | On your own key | |
|---|---|---|
| Credits charged | Yes, per run | Zero |
| Credit check before a run | Yes | Skipped |
| Run stops if credits hit zero | Yes | Not applicable |
| Who bills you | Bookbag, in credits | Your provider, directly |
| Which model | The platform default | Your 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.
The four providers
| Provider | Key looks like |
|---|---|
| OpenAI | sk-… |
| Anthropic | sk-ant-… |
| DeepSeek | sk-… |
| xAI (Grok) | xai-… |
An installation can also point any of these at a self-hosted, OpenAI-compatible server, so your administrator may have configured something else behind one of these names.
If keys cannot be stored
If the installation has no encryption key configured, an amber strip appears at the top of the page and no key can be added. The message is one of:
No encryption key is configured. Set BOOKBAG_ENCRYPTION_KEY to 64 hex characters (openssl rand -hex 32) and restart.
BOOKBAG_ENCRYPTION_KEY is set but is not 32 bytes — it must be 64 hex characters or a 32-byte base64 value.
Both are for whoever runs the installation. Bookbag deliberately has no plaintext fallback — a key that cannot be encrypted is not stored at all.
Next
- Administration — if you run the installation.