How it works
The parts of Baseera, what each one holds, and what happens during one chat turn.
Baseera has three parts that you touch, and one rule that ties them together: your tools and your users' sessions stay in your app, and your model key stays on Baseera's server.
The parts
| Part | What it is | What it holds |
|---|---|---|
| Platform | The dashboard at baseera.dev. | Organizations, agents and their versions, knowledge, test cases, keys, members, sessions and the audit log. Data is in Postgres, with row-level security on every table. |
| Runtime | The API your SDK calls (paths start with /v0). | Nothing between requests. It checks keys and tokens, builds the prompt, searches knowledge, calls the model and streams the reply. Turn state lives in the database. |
| SDK | @baseera/core, @baseera/react, @baseera/node, @baseera/ui. | core is the framework-free client, react has the provider and hooks, node signs user tokens on your server, ui is the chat surface and approval cards. |
| Your app | The product your users already use. | Your tools, your API and your user sessions. |
Where keys live
| Key | Where it lives | Who sees it |
|---|---|---|
| Model provider key (Anthropic, OpenAI, Google, OpenRouter) | Stored encrypted by the platform. Read only by the runtime's model gateway, for the agent that owns it. | Nobody after you save it. The dashboard shows the provider, a label and the last four characters. |
Publishable key (pk_...) | In your browser code. | Anyone. It only works from the agent's allowed domains. |
Secret key (sk_...) | On your server, in an environment variable. | Only you, once, when you create it. Baseera keeps a hash and the public half. |
| User token | Signed by your server with the secret key, held by the browser for up to an hour. | The signed-in user's browser. |
One chat turn
1. The browser asks your server for a user token
BaseeraProvider calls your getUserToken function. Your server signs a token that names the user and their tenant, using the secret key.
2. The SDK starts a session
POST /v0/sessions carries the publishable key and the user token. The runtime checks the key, then the request's origin against the allowed domains, then the token. It returns a session id.
3. The user sends a message
POST /v0/sessions/{id}/turns carries the message, the list of tools your app has registered (names, descriptions and schemas) and optional page context. The runtime stores the turn and opens an event stream.
4. The runtime builds the prompt and calls the model
The system prompt is your agent's prompt, then your app's context, then Baseera's platform rules, which always come last. If the agent has knowledge, the runtime searches it, either on every turn or when the model asks, using the knowledge base's own key. Only passages the user is allowed to read are returned.
5. The reply streams back
Text arrives as it is written. When the answer cites knowledge, the runtime sends the cited sources just before the turn ends.
6. A tool call goes back to your app
If the model wants a tool, the runtime does not run it. It sends a tool.call event to the browser and waits. A read tool runs at once in the SDK. A draft or write tool shows an approval card and waits for the user.
7. The SDK posts the result
Your tool runs in the browser as the signed-in user, calls your API, and the SDK posts the result (or the user's rejection) to /v0/sessions/{id}/tool-results. The same stream continues, and the model reads the result and keeps going.
A turn ends when the model stops, after 8 model steps, or if no tool result arrives within 5 minutes. Every message, tool call, approval and timing is recorded and shows in the agent's Sessions page.
What this means for you
- Baseera never runs your tools and never stores their code. It sees a tool's name, kind, description and schema, and lists them on the Tools page.
- Approval is enforced in the SDK in the user's browser. Your own API must still check permissions.
- The runtime is stateless between requests, so any instance can continue a turn.