Configuration

Bub reads configuration in this order, highest priority first:

1. Environment variables (the BUB_ prefix);
2. .env, loaded from the current workspace at CLI startup, or read by settings classes that declare env_file=".env";
3. ~/.bub/config.yml, created by bub onboard.

Fields not declared in the configuration use the settings class defaults. See the full example for every writable field.

Before you begin

• Make sure the Bub CLI is installed.
• You have an API key from a model provider, or you have completed OAuth with bub login codex (OpenAI only).

1. Finish the initial setup

Run the following command in your terminal to start the interactive setup. When it finishes, it writes the result to ~/.bub/config.yml.

bub onboard

2. Check the config file

Now check whether ~/.bub/config.yml contains the content described in the full example. Here is an example:

~/.bub/config.yml

model: openrouter:openrouter/free
api_key: sk-or-...
telegram:
  token: "123456789:your-telegram-bot-token"
  allow_users: "123456789,your_username"

Danger

By default, your keys are written directly to the config file in plain text. If you need stronger security and want to avoid storing model provider API keys locally in plain text, pass environment variables when running Bub to set or override them instead.

3. Override with environment variables

Commonly used environment variables include:

Variable	Description
BUB_MODEL	Model identifier, such as openrouter:openrouter/free or codex:<model>.
BUB_API_KEY	API key for the current provider; not needed with bub login codex.
BUB_API_BASE	Provider service URL; leave it blank for the default endpoint.
BUB_HOME	Runtime data directory, default ~/.bub.
BUB_<PROVIDER>_API_KEY	Key for a specific provider, such as BUB_OPENROUTER_API_KEY.
BUB_<PROVIDER>_API_BASE	Service URL for a specific provider.

See the settings reference for the full table.

4. Configure the model and fallback models

The model setting uses the provider:model format. To try fallback models in order when the primary model is unavailable, configure them in ~/.bub/config.yml:

model: openai:gpt-5-mini
fallback_models:
  - openrouter:openrouter/free

Each candidate provider needs its own valid credentials. Fallbacks only cover failures while creating a client and opening a request; errors after the message stream has started are not retried with another model, to avoid duplicate side effects. See Models and fallback for the full rules.

5. Configure the Telegram channel (optional)

If you want to use Bub as a Telegram bot, use the built-in Telegram channel. Example configuration:

BUB_TELEGRAM_TOKEN=123456789:your-telegram-bot-token
BUB_TELEGRAM_ALLOW_USERS=123456789,your_username
BUB_TELEGRAM_ALLOW_CHATS=-1001234567890
BUB_TELEGRAM_PROXY=http://127.0.0.1:7890   # optional

See Telegram channel for more configuration options.

6. Verify

Now try talking to Bub:

$ bub run "Can you introduce yourself?"

[cli:local]
I'm a virtual assistant designed to support a wide range of tasks including coding, design, research, and automation. I can integrate with code repositories, access web resources, leverage specialized skills, and streamline workflows. If you have specific tasks or questions about my capabilities, feel free to ask!