Gravity Claw Railway Operating Log

Scope: deploy and manage a Gravity Claw AI agent on Railway without running two Telegram bot instances against the same token.

Project Details

Fill these values in once, then use them through the workflow.

Key	Value
Project name	Your Railway project name
Service name	Your Railway service name
Environment	`production`
Project directory	Path to the Gravity Claw folder
Dashboard URL	Your Railway project URL

Prerequisites

Railway CLI

Install the Railway CLI and confirm it is available:

npm install -g @railway/cli
railway --version

Authenticate with Railway:

railway login --browserless

Link the Project

Run this inside the Gravity Claw folder:

railway link

Select the correct Railway project and service when prompted.

Set Environment Variables

Push every required value from .env into Railway:

railway variables set TELEGRAM_BOT_TOKEN="your-token"
railway variables set OPENROUTER_API_KEY="your-key"
# Repeat for every required variable.

Development Cycle

1. Pause Railway -> 2. Test locally -> 3. Deploy -> 4. Verify

Phase 1: Pause Railway

Before local testing, always pause the Railway service.

Two bot instances polling the same Telegram token will fight over messages: some updates go to Railway, some go to the laptop, and neither environment behaves reliably.

railway down

Phase 2: Test Locally

Start the local dev server with hot reload:

npm run dev

This runs tsx watch src/index.ts and restarts automatically on code changes. Test the bot through Telegram while the local process is running.

When testing is complete, stop the local server with Ctrl+C.

Phase 3: Deploy to Railway

Type-check before deploying:

npx tsc --noEmit

If new environment variables were added, set them before deployment:

railway variables set NEW_VAR_NAME="value"

Deploy:

railway up --detach

Railway starts a Docker build. Expect roughly 60 to 90 seconds of rebuild time. The bot can briefly go offline and then reconnect automatically.

Phase 4: Verify

After the build has had time to finish, inspect the logs:

railway logs --lines 40

Expected signals:

Soul loaded (soul.md)
Connected as @your_bot_name
Heartbeat scheduled
No crash traces
No unhandled errors

Quick Reference

Task	Command
Pause the live bot	`railway down`
Start local development	`npm run dev`
Type-check	`npx tsc --noEmit`
Deploy to Railway	`railway up --detach`
View live logs	`railway logs --lines 100`
Set a new env var	`railway variables set KEY="value"`
List env vars	`railway variables`
Open dashboard	`railway open`

Operational Notes

SQLite Resets on Deploy

Railway’s filesystem is ephemeral. The local SQLite database, usually gravity-claw.db, starts fresh on each deploy. Short-term conversation memory resets.

Pinecone semantic memory is cloud-hosted and persists across deploys.

Files Deployed by the Dockerfile

These files and folders are expected to be part of the deployed artifact:

src/
tsconfig.json
soul.md
mcp.json
package.json
package-lock.json

Files Excluded by `.dockerignore`

These files should not be deployed:

.env
node_modules/
gravity-claw.db

Troubleshooting

Problem	Response
Build failed	Run `railway logs --lines 100` and look for npm or TypeScript errors.
Bot crashes on startup	Check for missing variables with `railway variables`.
Messages go to the wrong place	Two instances are running; run `railway down` before `npm run dev`.
Rollback needed	Fix locally, then deploy again with `railway up --detach`.

For Antigravity or Gemini-style AI coding agents, place the deployment workflow files in the project’s .agent/ folder. The agent can then run the pause, test, deploy, and verify cycle without manual Railway commands.

File	Location
Skill	`.agent/skills/railway-deploy/SKILL.md`
Workflow	`.agent/workflows/deploy.md`

In practice, the operator should be able to say “deploy” and have the agent execute the full Railway workflow.