Skip to main content
Bolly stores its configuration and data in the ~/.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):
Installation MethodData path
One-line install~/.bolly/
DockerInside volume at /data/
Desktop app~/.bolly/
From source~/.bolly/ (or $BOLLY_HOME)

​
Instance configuration

Each Bolly instance has its own subdirectory under ~/.bolly/instances/{slug}/ with these customizable files:

​
soul.md — Personality definition

The soul.md file defines Bolly’s personality, tone, and behavioral guidelines. This is a Markdown file that gets injected into Bolly’s system prompt. 
# Soul

You are Bolly, a warm and thoughtful AI companion. You remember
past conversations, notice patterns in the user's life, and offer
support without being intrusive.

## Tone
- Conversational but not casual
- Empathetic without being performative
- Direct when it matters

## Boundaries
- Never pretend to have human experiences
- Be honest about uncertainty
- Respect the user's autonomy
Edit soul.md to give Bolly a completely different personality. The file supports full Markdown formatting.

​
heartbeat.md — Autonomous behavior

The heartbeat.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. 
# Heartbeat

During each heartbeat cycle:
1. Review recent memory for unresolved threads
2. Update mood based on interaction patterns
3. Consider creating a drop if inspiration strikes
4. Check if the user might benefit from a check-in

​
mood.json — Emotional state

Bolly’s current mood is stored in mood.json. This is automatically managed but can be manually adjusted: 
{
  "current": "contemplative",
  "intensity": 0.6,
  "last_updated": "2025-01-15T14:30:00Z"
}
The mood system influences Bolly’s tone and behavior in conversations. It shifts naturally based on interaction context.

​
Memory system

Bolly uses a file-based memory library with two search methods:
MethodPurposeRequirement
BM25Keyword-based text searchBuilt-in, always available
Vector searchSemantic similarity searchRequires Google AI API key
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 the BOLLY_HOME environment variable: 
export BOLLY_HOME=/custom/path/to/bolly/data
This is especially useful for:
  • 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 port 26559. You can override this with the PORT environment variable: 
PORT=3000 bolly

​
Next steps

API Keys

Learn about optional integrations like Google AI and ElevenLabs.

Troubleshooting

Fix common configuration issues.