Hybrid Railway deployments have three persistence layers:
Volume setup
The volume is not optional. Without it, knowledge.md, journal.md, and soma state are destroyed on every container redeploy.
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:
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:
Backup and restore
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:
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
