Deploy and Host LobeHub on Railway

LobeHub is an open-source AI workspace for creating, organizing, and operating AI agents. It provides multi-provider model support, persistent conversations, file uploads, knowledge features, agent tools, authentication, and collaborative workflows through a polished web interface that can be self-hosted under your own Railway project and domain.

About Hosting LobeHub

This Railway template deploys a complete server-side LobeHub stack rather than a stateless web container. It includes the LobeHub application, ParadeDB for PostgreSQL-compatible persistent data and search capabilities, Redis for caching and coordination, an S3-compatible Railway Storage Bucket for uploaded files, and persistent volumes for database, Redis, and authentication key data. Services communicate through Railway private networking whenever possible. Database migrations run automatically when LobeHub starts, while deployment-time passwords and encryption secrets are generated with Railway template functions. You only need to configure an AI provider key or connect a compatible model endpoint after deployment.

Common Use Cases

Run a private AI chat and agent workspace for personal, educational, or internal team use.
Build and operate reusable AI agents with persistent conversations, files, tools, knowledge, and multiple model providers.
Self-host a centralized interface for OpenAI-compatible APIs, local models, commercial AI providers, and custom inference services.

Dependencies for LobeHub Hosting

ParadeDB / PostgreSQL — stores users, authentication data, conversations, agents, settings, encrypted credentials, and application state. ParadeDB also packages PostgreSQL search functionality and can work alongside pgvector for vector or hybrid search.
Redis — provides a low-latency cache and coordination layer for LobeHub. The template protects Redis with a deployment-generated password and stores persistent data on a Railway Volume.
Railway Storage Bucket — provides private S3-compatible object storage for attachments, avatars, images, documents, and other uploaded content.
Persistent Railway Volumes — preserve ParadeDB data, Redis data, and the generated LobeHub JWKS signing key across restarts and redeployments.
AI model provider — at least one supported API key or compatible model endpoint must be configured before LobeHub can generate AI responses.
Upstash QStash, optional — required only for LobeHub features that depend on durable background workflows or scheduled task dispatching. The application can start and handle ordinary chats without it.

Deployment Dependencies

Implementation Details

Included Services

The template creates the following resources:

LobeHub
├── ParadeDB over Railway private networking
├── Redis over Railway private networking
├── Railway S3-compatible Storage Bucket
└── Persistent JWKS volume mounted at /data

ParadeDB
└── Persistent PostgreSQL volume

Redis
└── Persistent Redis volume

LobeHub is the only service that needs a public HTTP domain. ParadeDB and Redis are consumed through internal Railway references such as DATABASE_URL and REDIS_URL. Public TCP proxies are optional and should only be enabled when direct external database administration is required.

Automatic Database Migrations

The LobeHub service defines:

DATABASE_DRIVER="node"
DATABASE_URL="${{paradedb.DATABASE_URL}}"

DATABASE_DRIVER=node tells the official LobeHub launcher to run its packaged database migrations before starting the web application. A healthy deployment should contain logs similar to:

[Database] Start to migration...
Database migration passed.

The private ParadeDB URL is intentionally used instead of DATABASE_PUBLIC_URL, avoiding an unnecessary public route and keeping application traffic inside the Railway project.

Deployment-Generated Secrets

Railway template functions generate unique secrets whenever a user deploys the template. Examples include:

AUTH_SECRET="${{secret(32)}}"
KEY_VAULTS_SECRET="${{secret(32)}}"
POSTGRES_PASSWORD="${{secret(32)}}"
REDIS_PASSWORD="${{secret(32, \"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ\")}}"

AUTH_SECRET protects authentication sessions. KEY_VAULTS_SECRET is used to protect stored credentials and API secrets. PostgreSQL and Redis receive independent passwords. These values must remain stable after the first deployment; replacing them can invalidate sessions, prevent database access, or make previously encrypted credentials unreadable.

Persistent JWKS Generation

LobeHub requires JWKS_KEY to be a valid RSA private key represented as a JSON Web Key Set. It cannot be replaced by a normal random string generated with ${{secret(...)}}.

To keep the template deployable without asking users to manually create an RSA key, the LobeHub wrapper performs the following process at container startup:

Check whether JWKS_KEY was explicitly supplied.
Otherwise, check for /data/jwks.json on the attached Railway Volume.
Load the existing key when the file is present.
Generate a new 2048-bit RSA key pair using RS256 when no key exists.
Export the private key as a single-line JWKS document and save it to /data/jwks.json with restricted permissions.
Inject the resulting JSON into JWKS_KEY before launching the official LobeHub server.

The first deployment should log:

New persistent JWKS generated.

Later restarts and redeployments should log:

Persistent JWKS loaded.

Do not delete or replace the LobeHub /data volume unless you intentionally want to rotate the signing key. Losing this volume generates a new key and can invalidate tokens signed with the previous key. The template should use one LobeHub replica by default because the JWKS file is stored on a single attached volume. Multi-replica deployments should instead inject one externally managed JWKS_KEY shared by every replica.

Object Storage

The Railway Storage Bucket is connected through S3-compatible variables:

S3_BUCKET="${{S3 Bucket.BUCKET}}"
S3_REGION="${{S3 Bucket.REGION}}"
S3_ENDPOINT="${{S3 Bucket.ENDPOINT}}"
S3_ACCESS_KEY_ID="${{S3 Bucket.ACCESS_KEY_ID}}"
S3_SECRET_ACCESS_KEY="${{S3 Bucket.SECRET_ACCESS_KEY}}"
S3_ENABLE_PATH_STYLE="0"
S3_SET_ACL="0"

Railway buckets are private. LobeHub uses the S3 API and controlled file URLs for uploads and downloads. S3_SET_ACL=0 avoids ACL operations that are unnecessary for a private bucket, while S3_ENABLE_PATH_STYLE=0 uses virtual-hosted-style addressing expected by current Railway bucket credentials.

Redis Persistence and Security

Redis runs with password authentication and stores its data under /data on a persistent Railway Volume. The application connects using the private service hostname. Redis should not require a public TCP proxy for normal LobeHub operation.

RDB snapshots provide compact point-in-time persistence, but recent writes can be lost if Redis stops between snapshots. Operators who require stronger durability can enable AOF persistence in the Redis startup command, for example:

redis-server --requirepass "$REDIS_PASSWORD" --save 60 1 --appendonly yes --dir /data

Optional QStash Workflows

Without QSTASH_TOKEN, LobeHub may log a warning similar to:

QStash: QSTASH_TOKEN not set. Skipping schedule creation.

This warning does not prevent the web application, database, authentication, ordinary conversations, Redis, or S3 uploads from starting. Configure QSTASH_TOKEN, QSTASH_CURRENT_SIGNING_KEY, and QSTASH_NEXT_SIGNING_KEY when durable background workflows and scheduled dispatching are required.

AI Provider Configuration

The template does not bundle paid model access. After deployment, configure a supported provider through LobeHub or add the corresponding environment variables, such as an OpenAI, Anthropic, Google, OpenRouter, Groq, or OpenAI-compatible endpoint. Provider usage and API charges remain the responsibility of the template user.

Persistence, Backups, and Production Notes

Railway Volumes survive ordinary service restarts and deployments, but self-hosted database services remain operator-managed.

ParadeDB documentation describes its Community container as suitable primarily for hobby, development, and staging workloads, and warns that some production guarantees require ParadeDB Enterprise. Review ParadeDB's current deployment guarantees before using this template for business-critical or high-availability workloads. For simpler production requirements, operators may also choose a supported PostgreSQL deployment with the extensions required by their LobeHub configuration.

Before publishing or upgrading the template, verify that:

- The JWKS hash remains unchanged after a redeployment.
- LobeHub reports a successful database migration.
- A user can register, sign out, and sign back in.
- Conversations and agents remain after restarting LobeHub.
- Uploaded files remain accessible after a redeployment.
- Redis responds to an authenticated PING command.
- ParadeDB and Redis are accessed through private networking.
- Database and volume backups are configured and tested.

Why Deploy LobeHub on Railway?

By deploying LobeHub on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.