Hybrid Railway deployments have three persistence layers:
| Layer | What it stores | Durability |
|---|
| Postgres | Episodic memory, relationships, beliefs, entity state, automations | Durable |
Railway volume (/app/data) | knowledge.md, journal.md, soma checkpoint, workspace files | Durable (survives redeploy) |
| Container disk | Code, configs, logs | Ephemeral (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
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 /
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
| Symptom | Cause | Fix |
|---|
| Knowledge lost on redeploy | No volume or BUMBLEBEE_EXECUTION_WORKSPACE_DIR not set | Add volume and set the env var |
| Soma state resets | Soma checkpoint on ephemeral disk | Ensure workspace dir points to volume |
| Entity can’t write files | Workspace dir doesn’t exist | Verify volume mount path matches env var |
