> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bumbleagi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Building on Bumblebee

> Extension points for entities, tools, presence, and inference.

Bumblebee is built so **you own the entity’s definition** and can grow capabilities without forking core cognition. This page maps the main hooks; the companion guides go deeper on **social surfaces** and **portable inference**.

## Configuration-first entities

* **Entity YAML**: personality, voice, cognition overrides, presence platforms, automations, knowledge paths.
* **Harness YAML** (`configs/default.yaml` + overlays): models, timeouts, tool defaults, deployment mode, soma knobs, execution policy.

The harness is shared; each entity file describes **one being** that loads those defaults.

## Tools and MCP

* **Built-in tools** (web, filesystem, shell, code, knowledge, …) register from harness + entity config. Both reflex and deliberate profiles use the **same tool registry**.
* **MCP** extends reach: external processes expose tools to the entity without editing Bumblebee’s Python tree.

See [Tools](/guides/tools) for the full table and MCP notes.

## Presence / social adapters

Telegram, Discord, and CLI implement the same **platform contract**: connect, receive messages, call into `Entity.perceive`, send replies and typing/tool activity. Adding a new surface means implementing that interface and registering it — the cognition stack stays unchanged.

See [Presence & social surfaces](/build/presence-and-social).

## Inference portability

The entity talks to inference through a **provider** abstraction:

* **Local**: default Ollama on your machine.
* **Remote gateway**: same OpenAI-compatible `/v1/chat/completions` and `/v1/embeddings` shape, tunneled to your home GPU.

Anything that can terminate HTTPS and forward to that narrow API can sit in the path — Cloudflare Tunnel is the documented default, but the model is **“HTTP + bearer token to an Ollama-compatible backend.”**

See [Portable inference](/build/portable-inference).

## Deployment modes

* **All-local**: `bumblebee run`, SQLite (or your choice of DB URL), tools on the host.
* **Hybrid**: worker in cloud + gateway at home (or another private host you control).
* **Execution RPC**: optional redirect of shell/code tools to a machine you designate (common when the worker should not touch the Railway filesystem for risky operations).

[Hybrid Railway](/deployment/hybrid-railway) and [Persistence](/deployment/persistence) cover storage and ops.

## Design stance

Prefer **declarative YAML**, **small composable tools**, and **one persistent identity** over per-channel bots. If you are integrating external systems, route inference and secrets through the gateway pattern rather than exposing Ollama or the host OS broadly.