~/.bolly/ directory. Most setup — including your API key — happens through the web interface when you first open Bolly. This page covers the advanced configuration you can customize beyond the UI.
Data directory
All Bolly data lives in~/.bolly/ by default (configurable via BOLLY_HOME environment variable):
Instance configuration
Each Bolly instance has its own subdirectory under~/.bolly/instances/{slug}/ with these customizable files:
soul.md — Personality definition
Thesoul.md file defines Bolly’s personality, tone, and behavioral guidelines. This is a Markdown file that gets injected into Bolly’s system prompt.
heartbeat.md — Autonomous behavior
Theheartbeat.md file controls what Bolly does during its autonomous wake cycles (every 45 minutes by default). During heartbeats, Bolly can reflect, update its mood, and create drops.
mood.json — Emotional state
Bolly’s current mood is stored inmood.json. This is automatically managed but can be manually adjusted:
Memory system
Bolly uses a file-based memory library with two search methods:
Memory files are stored in
~/.bolly/instances/{slug}/memory/ as individual files. Bolly automatically creates, retrieves, and manages memories during conversations.
Drops
Drops are autonomous creative artifacts — art concepts, writing fragments, code sketches, reflections — that Bolly generates during idle heartbeat cycles. They’re stored in~/.bolly/instances/{slug}/drops/.
Drops are Bolly’s way of expressing creativity when not actively in conversation.
Skills
Bolly supports installable skills that extend its capabilities. Skills are stored in~/.bolly/instances/{slug}/skills/ and can add new tools, behaviors, or integrations.
Environment variables
You can override the data directory using theBOLLY_HOME environment variable:
- Running multiple Bolly instances with different data
- Docker deployments with custom volume mounts
- Testing configurations without affecting your main setup
Port configuration
By default, Bolly runs on port26559. You can override this with the PORT environment variable:
Next steps
API Keys
Learn about optional integrations like Google AI and ElevenLabs.
Troubleshooting
Fix common configuration issues.