ClaireDocs

Type to search titles, headings, and full text.

    Ask Claire

    Search the project, not the web.

    Answers are grounded in Claire’s published documentation and include the source pages used.

    ⌘/Ctrl + J opens Ask Claire anywhere in docs.

    Deploying Claire to Railway

    A worked example of deploying the Claire API and its dependencies to a managed host.

    CurrentReviewed 2026-08-17View source ↗

    Railway is the simplest managed path for the Claire API. It suits direct mode well; a full Matrix stack is usually better placed on a VPS beside it.

    Prerequisites#

    • A Railway account
    • A Supabase project for database and auth
    • An OpenAI API key, if you want AI features

    Quick start#

    1. Install the CLI and sign in

      Terminal
      npm install -g @railway/cli
railway login

    2. Create the project

      Terminal
      railway init

    3. Add Redis

      In the dashboard: + New → Database → Redis. Railway sets REDIS_URL on the service automatically.

    4. Configure environment variables

      VariableValue
      SUPABASE_URLYour Supabase project URL
      SUPABASE_ANON_KEYSupabase anon key
      SUPABASE_SERVICE_KEYSupabase service-role key
      DATABASE_URLSupabase connection string
      JWT_SECRETRandom 32+ character string
      ENCRYPTION_KEYRandom 32 hex characters
      OPENAI_API_KEYYour OpenAI key
      PLATFORM_MODEMust be set explicitly — the server refuses to guess
      Terminal
      openssl rand -hex 32   # JWT_SECRET
openssl rand -hex 16   # ENCRYPTION_KEY

    5. Deploy

      Terminal
      railway up

      Or connect the GitHub repository for automatic deployments on push.

    Architecture options#

    Direct mode#

    Direct mode on a managed host — The Claire server and Redis run on Railway; platform APIs and Supabase and OpenAI are external.

    Cheaper and simpler, at the cost of maintaining platform integration code and reconnecting WhatsApp after restarts.

    Matrix mode#

    Matrix needs more services than a single managed service comfortably holds. Two workable shapes:

    • Run the Claire server on Railway and the Matrix stack on a VPS, pointing MATRIX_HOMESERVER_URL at the VPS.
    • Self-host everything with docker-compose.prod.yml --profile matrix.

    Resource sizing#

    TierResourcesSuitable for
    Hobby (~$5/mo)512 MB RAM, shared CPUTesting
    Pro (~$20/mo)2 GB RAM, dedicated CPUProduction, one or two users
    Team ($50+/mo)4 GB+ RAM, multiple replicasMultiple users

    WhatsApp session persistence#

    WhatsApp sessions must survive a redeploy. Either:

    • Use a volume. Volumes persist across deploys; configure one in railway.toml or the dashboard.
    • Store sessions in Supabase. Serialize the session data and restore it on startup.

    Monitoring#

    Terminal
    railway logs
railway status
railway volume list

    The health endpoint is /health, and it reports the effective platform mode along with Matrix and schema readiness.

    Troubleshooting#

    SymptomCause and fix
    “Cannot find module”The build did not run bun install. Check the Dockerfile.
    WhatsApp disconnects after a deploySessions are not on a persistent volume.
    Memory exhaustionPuppeteer needs ~1 GB. Upgrade, or switch to Matrix mode.
    Telegram bot silentCheck TELEGRAM_BOT_TOKEN, and that no second instance is running — Telegram allows only one.

    Rough cost#

    ComponentMonthly
    Railway Pro$20
    Railway Redis$5
    Supabase free tier$0
    OpenAI (estimate)$10–50
    Total$35–75

    A Hetzner CAX21 (4 GB ARM, around €7/month) running docker-compose.prod.yml is the cheaper self-hosted alternative, and is the only realistic option for the full Matrix stack.