Persistence

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

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

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

Getting started

Guides

Deployment

Agents

Build

Volume setup

First startup

Postgres

Seeding knowledge

Backup and restore

S3-compatible attachment storage

Troubleshooting

​Volume setup

​First startup

​Postgres

​Seeding knowledge

​Backup and restore

​S3-compatible attachment storage

​Troubleshooting

Volume setup

First startup

Postgres

Seeding knowledge

Backup and restore

S3-compatible attachment storage

Troubleshooting