Concepts

A quick tour of how Boba is put together. You don’t need all of this to run an agent — but it explains what you’re driving.

Sessions

A session is one running conversation with an agent: its messages, tool calls, and state. Sessions are owned by a local daemon (boba daemon) so they keep running independent of any single client — the TUI, the web UI, or Telegram all attach to the same live sessions. You can leave and resume a session later.

Profiles & extensions

A profile is the recipe for a session: which provider (model) it uses and which extensions are switched on. Extensions are where behavior comes from — the system prompt, filesystem/shell/web-search tools, skills, memory, approvals, and more. Swap profiles to get a different kind of agent (a general assistant, a coding agent, a research agent) without changing anything else.

See Configuration for the full shape.

The crew (sub-agents)

Boba isn’t limited to one agent. With the subAgents extension, an agent can delegate to other profiles — a coder, a researcher, whatever you define. Each sub-agent runs its own session with its own provider and tools, and reports back. That’s the “crew”: a lead agent coordinating specialists, not a single chatbot.

Approvals

Agents can read and write files, run shell commands, and call tools. The approval extension puts you in control of the risky ones. The policy is an ordered list of rules plus a default: the first rule that matches a tool call decides allow, deny, ask-agent, or ask-human; anything uncovered falls back to the default.

extensions:
  approval:
    default: ask-human
    rules:
      - match: "bash(git log *)"   # tool(pattern); first match wins
        action: allow
      - match: "bash(rm *)"
        action: deny

When a call needs your sign-off, Boba surfaces it inline in the TUI or web UI — approve or deny without leaving the transcript.

Memory

The memory extension gives agents durable, cross-session recall: facts worth remembering are written to a local store and surfaced back in later sessions, so your agents accumulate context over time instead of starting cold.

Providers & your infra

Providers are just models behind a common interface — hosted (OpenAI, a ChatGPT subscription, Alibaba, OpenRouter) or local (Ollama), including any OpenAI-compatible endpoint. Two kinds matter: plain model providers, where Boba supplies the agent loop, and agent providers like Claude Code and Codex, which Boba drives rather than rebuilds. See Profiles & providers.

You choose where the model runs; your files, config, and session data stay on your machines.

Your backend

Boba has no cloud. The CLI is entirely local, and the optional web UI runs against a Supabase project you own — which is what lets a browser or phone attach to the same live sessions without anything routing through a third party.

Where to go next

• Operate — running all of this day to day.
• Configuration — every key.