Files

Cameron 3e3d81b9f2 feat: add Railway volume support for persistent storage (#113 )

Auto-detect RAILWAY_VOLUME_MOUNT_PATH and use it for all persistent data
(agent ID, cron jobs, logs). On local machines, data stays in project
directory. Template now includes volume by default.

- Add src/utils/paths.ts with getDataDir() and getWorkingDir() helpers
- Update Store, cron service, CLI tools to use data directory
- Log storage locations on startup for debugging
- Update deploy button URLs with UTM tracking

Written by Cameron ◯ Letta Code

"The best way to predict the future is to invent it." - Alan Kay

2026-02-03 16:49:08 -08:00

4.2 KiB

Raw Blame History

Railway Deployment

Deploy LettaBot to Railway for always-on hosting.

One-Click Deploy

Fork this repository
Connect to Railway
Set environment variables (see below)
Deploy!

No local setup required. LettaBot automatically finds or creates your agent by name.

Environment Variables

Required

Variable	Description
`LETTA_API_KEY`	Your Letta Cloud API key (get one here)

Channel Configuration (at least one required)

Telegram:

TELEGRAM_BOT_TOKEN=your-bot-token
TELEGRAM_DM_POLICY=pairing

Discord:

DISCORD_BOT_TOKEN=your-bot-token
DISCORD_DM_POLICY=pairing

Slack:

SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

Optional

Variable	Default	Description
`AGENT_NAME`	`LettaBot`	Agent name (used to find/create agent)
`MODEL`	`zai/glm-4.7`	Model for new agents (ignored for existing agents)
`LETTA_AGENT_ID`	-	Override auto-discovery with specific agent ID
`CRON_ENABLED`	`false`	Enable cron jobs
`HEARTBEAT_INTERVAL_MIN`	-	Enable heartbeats (minutes)
`HEARTBEAT_TARGET`	-	Target chat (e.g., `telegram:123456`)
`OPENAI_API_KEY`	-	For voice message transcription

How It Works

Agent Discovery

On startup, LettaBot:

Checks for LETTA_AGENT_ID env var - uses if set
Otherwise, searches Letta Cloud for an agent named AGENT_NAME (default: "LettaBot")
If found, uses the existing agent (preserves memory!)
If not found, creates a new agent on first message

This means your agent persists across deploys without any manual ID copying.

Build & Deploy

Railway automatically:

Detects Node.js and installs dependencies
Runs npm run build to compile TypeScript
Runs npm start to start the server
Sets the PORT environment variable
Monitors /health endpoint

Persistent Storage

The Railway template includes a persistent volume mounted at /data. This is set up automatically when you deploy using the button above.

What Gets Persisted

Agent ID - No need to set LETTA_AGENT_ID manually after first run
Cron jobs - Scheduled tasks survive restarts
Skills - Downloaded skills persist
Attachments - Downloaded media files

Volume Size

Free plan: 0.5 GB (sufficient for most use cases)
Hobby plan: 5 GB
Pro plan: 50 GB

Manual Deployment (Without Template)

If you deploy manually from a fork instead of using the template, you'll need to add a volume yourself:

In your Railway project, click + New and select Volume
Connect the volume to your LettaBot service
Set the mount path to /data

LettaBot automatically detects RAILWAY_VOLUME_MOUNT_PATH and uses it for persistent data.

Channel Limitations

Channel	Railway Support	Notes
Telegram	Yes	Full support
Discord	Yes	Full support
Slack	Yes	Full support
WhatsApp	No	Requires local QR pairing
Signal	No	Requires local device registration

Troubleshooting

"No channels configured"

Set at least one channel token (TELEGRAM_BOT_TOKEN, DISCORD_BOT_TOKEN, or SLACK tokens).

Agent not found / wrong agent

Check AGENT_NAME matches your intended agent
Or set LETTA_AGENT_ID explicitly to use a specific agent
Multiple agents with the same name? The most recently created one is used

Health check failing

Check Railway logs for startup errors. Common issues:

Missing LETTA_API_KEY
Invalid channel tokens

Data not persisting

If data is lost between restarts:

Verify a volume is attached to your service
Check that the mount path is set (e.g., /data)
Look for [Storage] Railway volume detected in startup logs
If not using a volume, set LETTA_AGENT_ID explicitly

Deploy Button

Or add to your README:

[![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/lettabot?utm_medium=integration&utm_source=template&utm_campaign=generic)

4.2 KiB Raw Blame History