Configuration

Most people never write this file by hand — boba init generates it. This page is the reference for when you outgrow it. A fully annotated example ships in the repository at botbandit.config.example.yaml.

Where the config comes from

Boba looks for botbandit.config.yaml (or .yml) in:

1. The path in BOTBANDIT_CONFIG_PATH, if set — and fails if it is missing.
2. The current directory, so a project can carry its own.
3. The application home, ~/.botbandit/ — where the wizard writes it.

The first file found wins outright; they are not merged. Within a run, values resolve environment variables → the YAML file → defaults.

Set BOTBANDIT_HOME to move the application home itself.

The config has three main sections: profiles (what a session is made of), providers (the models), and extensions (the tools and behaviors).

Profiles

A profile bundles a provider with a set of extensions. Boba runs the profile named by the top-level profile: key, or one you pass with --profile.

profile: default
 
profiles:
  default:
    provider: alibaba
    extensions: [systemPrompt, baseTools, skills, approval, compaction, memory, documents, subAgents]
 
  coder:
    # Codex is a complete coding agent with its own prompt/tools/skills,
    # so we proxy to it directly and add only what we need.
    provider: codex
    extensions: [approval, memory]

Providers

Boba is provider-neutral. Define the models you want under providers: and reference the provider from a profile.

providers:
  # ChatGPT Plus/Pro subscription via OAuth — no API key to manage.
  # First-time login: `boba auth login openai-codex`
  openai-codex:
    models:
      gpt-6.1-sol:
      gpt-6-astra:
 
  # Standard OpenAI API via API key.
  openai:
    models:
      gpt-5:
      gpt-5-mini:
    apiKey: env:OPENAI_API_KEY
 
  # Any OpenAI-compatible chat-completions endpoint.
  openai-compatible:
    name: OpenAICompatible
    baseURL: https://api.example.com/v1
    apiKey: env:OPENAI_COMPATIBLE_API_KEY
    models:
      my-model:
 
  # OpenRouter — model IDs in provider/model form.
  openrouter:
    models:
      openai/gpt-5:
    apiKey: env:OPENROUTER_API_KEY
 
  # Alibaba / DashScope.
  alibaba:
    models:
      qwen3-coder-plus:
    apiKey: env:ALIBABA_API_KEY
 
  # Ollama (local or remote).
  ollama:
    baseURL: http://localhost:11434
    models:
      "qwen3-coder:480b-cloud":

Derive a custom endpoint from a base provider with baseProvider:

providers:
  my-endpoint:
    baseProvider: openai-compatible
    name: MyEndpoint
    baseURL: https://my.host/v1
    apiKey: env:MY_API_KEY
    model: my-model

Extensions

Extensions inject prompts, tools, and behaviors into a session. Common ones:

• systemPrompt — the base instructions.
• baseTools — filesystem, shell, and web search.
• skills — discovered SKILL.md capabilities (with optional allow/blocklist).
• approval — gate risky tool calls (see Concepts).
• compaction — auto-compact long transcripts.
• memory — cross-session recall.
• documents — a local markdown vault the agent can read/write.
• subAgents — delegate to specialized profiles (your crew).

Define defaults under extensions:; profiles can override inline.

Secrets in config values

Config values support two schemes:

• plain:<value> (default)
• env:<ENV_VAR_NAME> — read the value from an environment variable

Resident extensions

A few extensions are not attached to a profile — they run for the life of the daemon and read their own top-level block: telegram, accountStatus, selfHelp and the scheduler. Adding them to a profile’s extensions: list does nothing.

selfHelp is on by default: it writes a short reference to ~/.botbandit/BOTBANDIT.md and adds one sentence to every session’s prompt telling the agent to read it when you ask about botbandit itself. Switch it off with selfHelp: { enabled: false }, or narrow it with subAgents: false or skipProfiles: [...].

extensions:
  telegram:
    token: env:BOTBANDIT_TELEGRAM_TOKEN
    allowedUsers: [123456789]

Restart the daemon (boba daemon restart) after changing any of them.

Web UI

The supabaseBridge extension connects the daemon to a self-hosted web UI. Unlike the residents above, it is listed on profiles: on every profile whose sessions should mirror, including the default. It also needs service.enabled: true. boba init writes all of it when you choose Connect to a Boba web app. See Connect the agent for the hand-written form, and Self-host for the full path: a scripted, roughly twenty-minute setup against a free Supabase project.