Skip to main content

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.

Hybrid Railway deployments have three persistence layers:
LayerWhat it storesDurability
PostgresEpisodic memory, relationships, beliefs, entity state, automationsDurable
Railway volume (/app/data)knowledge.md, journal.md, soma checkpoint, workspace filesDurable (survives redeploy)
Container diskCode, configs, logsEphemeral (lost on redeploy)

​
Volume setup

The volume is not optional. Without it, knowledge.md, journal.md, and soma state are destroyed on every container redeploy. 
railway service bumblebee-worker
railway volume add --mount-path /app/data
railway variable set BUMBLEBEE_EXECUTION_WORKSPACE_DIR=/app/data
railway redeploy --service bumblebee-worker --yes
BUMBLEBEE_EXECUTION_WORKSPACE_DIR redirects knowledge, journal, and soma paths onto the volume. Without it, those files land on the ephemeral container disk under ~/.bumblebee.

​
First startup

If no knowledge.md exists at the configured path, the entity writes a minimal template automatically. No manual seeding required for a fresh deploy.

​
Postgres

Set DATABASE_URL on the Railway service: 
DATABASE_URL=postgresql://user:pass@host:5432/bumblebee
When set, all structured memory (episodes, relationships, beliefs, automations, reminders) uses Postgres instead of SQLite. Schema migrations run automatically on startup.

​
Seeding knowledge

To pre-populate knowledge.md on a fresh volume: 
railway ssh --service bumblebee-worker
cat > /app/data/entities/canary/knowledge.md << 'EOF'
## [locked] about yourself
You are Canary, the first entity on Bumblebee.
EOF

​
Backup and restore

# Backup
railway ssh --service bumblebee-worker
tar czf /tmp/backup.tar.gz /app/data/entities/

# Restore
railway ssh --service bumblebee-worker
tar xzf /tmp/backup.tar.gz -C /
For Postgres, use pg_dump / pg_restore via the Railway database service.

​
S3-compatible attachment storage

In local mode, images and audio from chats are saved to disk. On ephemeral cloud disks, those files disappear on redeploy. For hybrid deployments, use S3-compatible object storage: 
BUMBLEBEE_ATTACHMENTS_BACKEND=object_s3_compat
BUMBLEBEE_S3_ENDPOINT_URL=https://...
BUMBLEBEE_S3_BUCKET=bumblebee-attachments
BUMBLEBEE_S3_ACCESS_KEY=...
BUMBLEBEE_S3_SECRET_KEY=...
The setup wizard (bumblebee setup) prompts for S3 configuration on the hybrid path. Any S3-compatible API works — Cloudflare R2, Backblaze B2, MinIO, AWS S3.

​
Troubleshooting

SymptomCauseFix
Knowledge lost on redeployNo volume or BUMBLEBEE_EXECUTION_WORKSPACE_DIR not setAdd volume and set the env var
Soma state resetsSoma checkpoint on ephemeral diskEnsure workspace dir points to volume
Entity can’t write filesWorkspace dir doesn’t existVerify volume mount path matches env var