Skip to Content
Baseera Docs

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

PartWhat it isWhat it holds
PlatformThe 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.
RuntimeThe 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 appThe product your users already use.Your tools, your API and your user sessions.

Where keys live

KeyWhere it livesWho 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 tokenSigned 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.

Next steps

On this page