Skip to main content

​
Production Deployment

Complete guide to deploying Lite Claw in production.
For a quick first deployment, see Quickstart. This guide covers the full production setup.

​
Architecture

Run three Railway services:
Railway project architecture showing worker (always-on) and two heartbeat cron services connecting to Telegram, Neon Postgres, Upstash Redis, and OpenRouter
ServiceCommandPurpose
workerpnpm startTelegram long polling, auth, agent loop
heartbeat-morningpnpm heartbeat:runMorning briefing (cron)
heartbeat-weeklypnpm heartbeat:runWeekly review (cron)
The heartbeat job checks heartbeat_jobs.schedule_cron and the user’s timezone at runtime. It only sends if actually due. Duplicate sends are prevented with Redis slot keys.This pattern avoids Railway cron granularity limits while keeping timezone handling in application code.

​
Prerequisites

ServicePurposeFree Tier
RailwayHosting$5 credits
NeonPostgresYes
UpstashRedisYes
OpenRouterLLM APIPay-as-you-go
Google CloudOAuth (Calendar, Gmail)Yes

​
Environment Variables

VariableDescription
TELEGRAM_BOT_TOKENFrom @BotFather
OPENROUTER_API_KEYAPI key with credits
DATABASE_URLNeon Postgres connection string
UPSTASH_REDIS_REST_URLUpstash Redis REST URL
UPSTASH_REDIS_REST_TOKENUpstash Redis token
OWNER_CLAIM_CODESecret code to claim ownership
OWNER_CLAIM_PEPPERSalt for hashing claim code
PUBLIC_BASE_URLYour public domain (for OAuth callback)
TOKEN_ENCRYPTION_KEY32-byte base64url key for encrypting tokens
GOOGLE_OAUTH_CLIENT_IDGoogle Cloud OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRETGoogle Cloud OAuth client secret

​
Generating TOKEN_ENCRYPTION_KEY

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

​
Google OAuth Setup

1

Create OAuth Client

In Google Cloud Console:
  1. Create a new project (or use existing)
  2. Go to APIs & Services → Credentials
  3. Create OAuth client ID (Web application)
2

Configure Redirect URI

Add authorized redirect URI:
https://<your-railway-domain>/oauth/google/callback
3

Enable APIs

In APIs & Services → Library, enable:
  • Google Calendar API
  • Gmail API
Scopes requested:
  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.events
  • https://www.googleapis.com/auth/gmail.readonly

​
Deploy

1

Run checks locally

pnpm install
pnpm migrate
pnpm check
pnpm build
2

Create Railway services

Create three services in your Railway project:
  • worker — Start command: pnpm start
  • heartbeat-morning — Cron service, command: pnpm heartbeat:run
  • heartbeat-weekly — Cron service, command: pnpm heartbeat:run
3

Set environment variables

Add all required variables to each service. For cron services, also set HEARTBEAT_JOB_TYPE.
4

Deploy worker first

Deploy the worker service and verify it starts without errors.
5

Deploy cron services

Deploy both heartbeat services.

​
First-Run Setup

After deployment, set up your bot in Telegram:
1

Claim ownership

/start
/claim <OWNER_CLAIM_CODE>
2

Connect integrations

/integrations connect calendar
/integrations connect gmail
/integrations weather San Francisco, CA
3

Enable heartbeats

/heartbeats morning on
/heartbeats weekly on
4

Test

What's on my calendar tomorrow?

​
Validate

Run through the Go-Live Validation checklist before considering the deployment complete.

​
Known Limits

  • Token encryption key rotation requires users to reconnect integrations
  • Calendar event extraction is heuristic-based; edge phrasing may need clarification
  • Only Google Calendar/Gmail and OpenWeather are integrated; other providers are optional extensions

​
Next Steps

Validation Checklist

Full go-live checklist

Runbook

Day-2 operations and incident response