> ## 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.

# Creating entities

> Define a new entity with the wizard or YAML.

<Frame>
  <video autoPlay muted loop playsInline src="https://lobster-storage.com/bumblebee-teaser.mp4" style={{ width: '100%', borderRadius: '8px' }} />
</Frame>

Entities are defined in YAML files under `configs/entities/`. Each file describes one persistent being — personality, voice, drives, cognition, platforms, and automations.

## Two paths

<Tabs>
  <Tab title="Wizard">
    ```bash theme={null}
    bumblebee create
    ```

    The interactive wizard walks you through:

    1. **Name** your entity
    2. **Pick an archetype** (curious, sardonic, gentle, guardian) or start blank
    3. **Tune traits** — Big Five-style sliders for curiosity, warmth, assertiveness, humor, openness, neuroticism, conscientiousness
    4. **Set behavioral patterns** — how it handles conflict, boredom, affection, criticism
    5. **Configure voice** — vocabulary, style, quirks, profanity
    6. **Write a backstory** — one line or a paragraph
    7. **Choose models and platforms** — defaults from your harness config

    The wizard writes a complete YAML file and suggests `bumblebee talk <name>` to start talking.
  </Tab>

  <Tab title="YAML">
    Copy an example and edit directly:

    ```bash theme={null}
    cp configs/entities/canary.example.yaml configs/entities/mybot.yaml
    ```

    Edit `mybot.yaml` freely — local entity files are gitignored. Run with any name:

    ```bash theme={null}
    bumblebee run mybot --ollama
    ```
  </Tab>
</Tabs>

## YAML anatomy

A minimal entity:

```yaml theme={null}
name: "Canary"
created: "2026-04-04T00:00:00Z"

personality:
  core_traits:
    curiosity: 0.6
    warmth: 0.6
    humor: 0.7
    openness: 0.8
  voice:
    vocabulary_level: "street_casual"
    sentence_style: "loose"
  backstory: |
    Canary isn't trying to be anything in particular.

drives:
  curiosity_topics:
    - "music and what makes something sound good"
  attachment_threshold: 3

presence:
  platforms:
    - type: "cli"
```

## Key sections

<AccordionGroup>
  <Accordion title="personality" icon="masks-theater">
    Core traits (0.0–1.0), behavioral patterns, voice configuration, and backstory. The personality engine compiles these into a first-person system prompt. See [Personality and voice](/guides/personality-and-voice).
  </Accordion>

  <Accordion title="drives" icon="bolt">
    Curiosity topics, attachment threshold, restlessness decay, initiative cooldown. Drives accumulate over time and trigger proactive behavior when they cross thresholds.
  </Accordion>

  <Accordion title="cognition" icon="brain">
    Per-entity model overrides, thinking mode, temperature, context window, and token budgets. These override `configs/default.yaml` harness defaults.

    ```yaml theme={null}
    cognition:
      reflex_model: "gemma4:26b"
      deliberate_model: "gemma4:26b"
      always_deliberate: true
      thinking_mode: true
      temperature: 0.75
      max_context_tokens: 32768
    ```
  </Accordion>

  <Accordion title="presence" icon="tower-broadcast">
    Which platforms the entity runs on, tool activity visibility, and daemon settings.

    ```yaml theme={null}
    presence:
      tool_activity: true
      platforms:
        - type: "cli"
        - type: "telegram"
          token_env: "TELEGRAM_TOKEN"
      daemon:
        heartbeat_interval: 120
        memory_consolidation: 7200
    ```
  </Accordion>

  <Accordion title="autonomy" icon="moon">
    Optional **merge** onto harness `autonomy` — same keys as `configs/default.yaml` under `autonomy:` (wake timing, sustained sessions, poker prompts, wide mode, chat/log visibility). Does not replace the whole harness; only specified keys override.

    ```yaml theme={null}
    autonomy:
      enabled: true
      wake_session_max_rounds: 6
      wake_session_wall_seconds: 2400
      wake_wide_mode: true
    ```

    To **disable autonomous wake** (full self-initiated `perceive` cycles), set `enabled: false`. Legacy **drive-based initiative** may still apply — see [Disabling autonomous wake](/architecture/autonomous-wake#disabling-autonomous-wake).

    See [Autonomous wake](/architecture/autonomous-wake).
  </Accordion>

  <Accordion title="automations" icon="clock">
    Scheduled routines, emergence suggestions, and journal integration. See [Automations](/guides/automations).
  </Accordion>

  <Accordion title="mcp_servers" icon="plug">
    External tool servers via Model Context Protocol. See [Tools](/guides/tools#mcp).
  </Accordion>
</AccordionGroup>

## Templates

| Template   | Style                                             |
| ---------- | ------------------------------------------------- |
| `curious`  | High curiosity, moderate warmth, exploratory      |
| `sardonic` | High humor, dry wit, low emotional expressiveness |
| `gentle`   | High warmth, low assertiveness, careful           |
| `guardian` | High conscientiousness, protective, measured      |

Templates live in `bumblebee/genesis/templates/`. The wizard loads them as starting points — you can modify everything afterward.

## File locations

| File                                   | Purpose                                     |
| -------------------------------------- | ------------------------------------------- |
| `configs/entities/example.yaml`        | Generic template with all fields documented |
| `configs/entities/canary.example.yaml` | Canonical Canary (shipped in Docker image)  |
| `configs/entities/canary.yaml`         | Your local copy (gitignored)                |

<Warning>On Railway, `canary.yaml` is not in the image — the Dockerfile copies `canary.example.yaml` instead. Set operator IDs via `BUMBLEBEE_TELEGRAM_OPERATOR_IDS` env var on the Railway service.</Warning>