Skip to content
Bub Bub Bub

Configure

This page shows how to configure Bub: which model to call, which provider to call it through, and which channel credentials to load on startup.

Bub reads its own configuration from these places, in order of precedence (highest first):

  1. Process environment (BUB_* variables).
  2. .env values loaded during CLI startup or by settings classes that explicitly declare env_file=".env".
  3. ~/.bub/config.yml (created by bub onboard).

When no explicit Bub key is supplied, Bub reads <PROVIDER>_API_KEY and <PROVIDER>_API_BASE, using Republic provider names with hyphens replaced by underscores. Examples include OPENROUTER_API_KEY, GOOGLE_API_KEY, and AZURE_OPENAI_API_KEY. Explicit BUB_* settings take precedence.

Before you begin

Section titled “Before you begin”
  • Bub is installed (bub --help works).
  • You have one model provider’s API key, or you have run bub login codex for OAuth.

1. Run the interactive setup

Section titled “1. Run the interactive setup”

bub onboard guides you through provider selection, API key and URL (when needed), connection checking, searchable model selection, channels, and streaming settings. Hosted providers use their default URL; choose OpenAI-compatible for a custom OpenAI-compatible server. Leave the API key blank to use environment credentials. If the model list is unavailable, you can edit the connection, retry, or enter a model ID manually. The connection check fetches models without generating a completion. Selecting Codex skips model discovery and uses manual model entry. The collected configuration replaces ~/.bub/config.yml; existing values supply prompt defaults and are preserved unless updated. Plugins may add prompts through the onboard_config hook.

bub onboard

The file lives at ~/.bub/config.yml by default. BUB_HOME controls bub.home, including history, tapes, and the managed plugin project; it does not move the default config file. Use BubFramework(config_file=...) when embedding Bub and you need a different config path.

2. Inspect the config file

Section titled “2. Inspect the config file”

A minimal config looks like this:

# ~/.bub/config.yml
model: openrouter:openrouter/free
api_key: sk-or-v1-...
telegram:
  token: "123456:abcdef..."
  allow_users: "123456789,your_username"

Top-level keys map to AgentSettings in src/bub/builtin/settings.py. Per-channel keys (such as telegram:) map to that channel’s Settings subclass.

3. Override at runtime with environment variables

Section titled “3. Override at runtime with environment variables”

Every YAML key has a matching environment variable. The pattern is BUB_<UPPERCASE_KEY>:

Variable Purpose
BUB_MODEL Model identifier, e.g. openrouter:openrouter/free or codex:<model>.
BUB_API_KEY API key for the active provider. Leave unset when using bub login codex.
BUB_API_BASE Override the provider’s base URL. Leave unset to use the selected provider’s default endpoint.
BUB_HOME Bub’s runtime data directory (history, tapes, managed plugin project). Default ~/.bub; does not move the default config file.
BUB_<PROVIDER>_API_KEY Per-provider key, e.g. BUB_OPENROUTER_API_KEY.
BUB_<PROVIDER>_API_BASE Per-provider base URL.

Republic reads and refreshes Codex file credentials from $CODEX_HOME/auth.json or ~/.codex/auth.json. Install the Codex CLI for a new login, then select codex:<model> and leave BUB_API_KEY unset. Use openai:<model> with API credentials for OpenAI API access.

To reach an endpoint that speaks a supported API under a name of its own (a company proxy, a relay, a second account), declare it under providers and use that name as the model prefix; see Custom providers.

For the full table, including channel debounce knobs and advanced model-client settings, see Settings reference.

4. Configure channel credentials

Section titled “4. Configure channel credentials”

Each channel has its own settings prefix. The builtin Telegram channel reads BUB_TELEGRAM_*:

BUB_TELEGRAM_TOKEN=123456:abcdef...
BUB_TELEGRAM_ALLOW_USERS=123456789,your_username
BUB_TELEGRAM_ALLOW_CHATS=-1001234567890
BUB_TELEGRAM_PROXY=http://127.0.0.1:7890   # optional

For the message-handling and access-control behavior these variables drive, see Telegram.

5. Verify

Section titled “5. Verify”

Print the loaded hook mapping:

bub hooks

Then run one turn end-to-end:

bub run "say hi"

Expected output prints each outbound as a prefix line ([<channel>:<chat_id>]) followed by the message content.

Next steps

Section titled “Next steps”