Configuration

Configuration lives inside your folder at .folderbot/config.toml.

Run folderbot init from your folder to create it interactively.

Basic Configuration

telegram_token = "YOUR_TELEGRAM_BOT_TOKEN"
anthropic_api_key = "YOUR_API_KEY"  # Or set FOLDERBOT_API_KEY env var
allowed_user_ids = [123456789]  # Your Telegram user ID

# root_folder is implicit — the parent of .folderbot/
model = "anthropic/claude-sonnet-4-20250514"  # or openai/gpt-4o, etc.

Required Fields

telegram_token

Your Telegram bot token from @BotFather.

allowed_user_ids

List of Telegram user IDs allowed to use the bot. Get yours from @userinfobot.

Optional Fields

root_folder

Path to the folder the bot has access to. Defaults to the parent of .folderbot/. Only needed if you want to override this default.

api_key

Your LLM provider API key. Can also be set via FOLDERBOT_API_KEY env var or the provider’s own env var (e.g., ANTHROPIC_API_KEY, OPENAI_API_KEY). Optional if the provider’s env var is already set.

model

The LLM model to use. Format: provider/model-name. Default: anthropic/claude-sonnet-4-20250514.

user_name

The name the bot uses when addressing you. Default: User.

auto_log_folder

Subdirectory for auto-logging conversations. Default: logs/.

whisper_model

Model for voice transcription. Default: base. Options: tiny, base, small, medium, large-v3.

max_history_chars

Maximum character budget for conversation history sent to the LLM. Default: 50000.

max_context_chars

Maximum character budget for file context. Default: 10000.

Supported Providers

Folderbot uses instructor for LLM integration, supporting 18+ providers:

Provider

Model format

Env var

Anthropic

anthropic/claude-sonnet-4-20250514

ANTHROPIC_API_KEY

OpenAI

openai/gpt-4o

OPENAI_API_KEY

Azure OpenAI

azure_openai/gpt-4

AZURE_OPENAI_API_KEY

AWS Bedrock

bedrock/anthropic.claude-3-sonnet

AWS credentials

Google

google/gemini-2.0-flash

GOOGLE_API_KEY

Groq

groq/llama-3.1-70b

GROQ_API_KEY

Mistral

mistral/mistral-large-latest

MISTRAL_API_KEY

Ollama

ollama/llama3.1

(local, no key needed)

DeepSeek

deepseek/deepseek-chat

DEEPSEEK_API_KEY

OpenRouter

openrouter/openai/gpt-4-turbo

OPENROUTER_API_KEY

See the instructor docs for the full list of supported providers.

Read Rules

Control which files the bot can access:

[read_rules]
include = ["**/*.md", "**/*.txt"]
exclude = ["**/docs/**", ".git/**"]
append_allowed = ["**/todo.md"]
include

Glob patterns for files the bot can read. Default: all files.

exclude

Glob patterns for files to skip. Default: none.

append_allowed

Glob patterns for files the bot can append to (not just overwrite).

File Watching

Configure file change notifications:

[watch]
debounce_seconds = 3.0
ignore_patterns = ["*.tmp", ".git/**"]

Multi-Bot Configuration

Run multiple bots with different folders from a single config:

api_key = "SHARED_KEY"

[bots.work]
telegram_token = "WORK_BOT_TOKEN"
root_folder = "~/work/notes"
allowed_user_ids = [123456789]

[bots.personal]
telegram_token = "PERSONAL_BOT_TOKEN"
root_folder = "~/personal/notes"
allowed_user_ids = [123456789]

Run a specific bot:

folderbot run --bot work
folderbot run --bot personal

Each bot gets its own systemd service when installed:

folderbot service install --bot work
folderbot service install --bot personal

Tool Configuration

Tools can be configured under the [tools] section, with subsections per tool:

[tools.web_search]
google_api_key = "YOUR_GOOGLE_API_KEY"
google_cx = "YOUR_SEARCH_ENGINE_ID"

[tools.whisper]
model = "base"  # Options: tiny, base, small, medium, large-v3

Each tool reads its own [tools.<name>] section. Custom tools (see below) can also define their own configuration sections.