Web Deployment Guide

The web version is available for demo purposes only. The desktop app is the primary distribution. Use web deployment for testing or team-shared instances.

Overview

Routa can be deployed as a Next.js web application with:

Database: PostgreSQL (Neon, Supabase) or SQLite (not recommended for production)
Platforms: Vercel, Railway, Render, Fly.io
Features: Full MCP server, ACP agent spawning, A2A federation

Vercel Deployment

Vercel is the recommended platform for web deployment.

Create Neon Postgres Database

Sign up at neon.tech
Create a new project
Copy the connection string (starts with postgresql://...)

Fork the Repository

Fork routa-js to your GitHub account.

Deploy to Vercel

Go to vercel.com and sign in
Click “New Project”
Import your forked repository
Configure environment variables (see below)
Click “Deploy”

Configure Environment Variables

Add these in the Vercel dashboard (Settings → Environment Variables):

DATABASE_URL=postgresql://user:password@host/database?sslmode=require
ANTHROPIC_AUTH_TOKEN=sk-ant-...
ROUTA_DB_DRIVER=postgres

Run Database Migrations

After deployment, run migrations via Vercel CLI:

npm install -g vercel
vercel login
vercel env pull .env.local
npm run db:push

Environment Variables for Vercel

.env.production

# Database (required)
DATABASE_URL=postgresql://user:[email protected]/routa?sslmode=require
ROUTA_DB_DRIVER=postgres

# Anthropic API (required for Claude specialists)
ANTHROPIC_AUTH_TOKEN=sk-ant-...

# Optional: Custom API endpoint
# ANTHROPIC_BASE_URL=https://api.anthropic.com

# Optional: Model configuration
# ANTHROPIC_MODEL=claude-4-sonnet-20250514
# ANTHROPIC_SMALL_FAST_MODEL=claude-4-haiku-20250514

# Optional: Request timeout (milliseconds)
# API_TIMEOUT_MS=600000

# Optional: GitHub integration
# GITHUB_TOKEN=ghp_...
# GITHUB_WEBHOOK_SECRET=your-webhook-secret

# Optional: Disable Claude Code non-essential traffic
# CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

Vercel Configuration

The project includes vercel.json for optimal configuration:

vercel.json

{
  "rewrites": [
    {
      "source": "/api/:path*",
      "destination": "/api/:path*"
    }
  ],
  "headers": [
    {
      "source": "/api/mcp",
      "headers": [
        { "key": "Cache-Control", "value": "no-store" }
      ]
    }
  ]
}

Railway Deployment

Railway provides built-in PostgreSQL and simpler configuration.

Create Railway Account

New Project from GitHub

Click “New Project”
Select “Deploy from GitHub repo”
Choose your forked routa-js repository

Add PostgreSQL Database

Click “New” → “Database” → “Add PostgreSQL”
Railway automatically sets DATABASE_URL

Configure Environment Variables

In Railway dashboard, add:

ROUTA_DB_DRIVER=postgres
ANTHROPIC_AUTH_TOKEN=sk-ant-...

Deploy

Railway automatically builds and deploys on push to main.

Build Configuration for Railway

Create railway.json:

railway.json

{
  "build": {
    "builder": "NIXPACKS",
    "buildCommand": "npm install --legacy-peer-deps && npm run build"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/api/health",
    "restartPolicyType": "ON_FAILURE",
    "restartPolicyMaxRetries": 3
  }
}

Render Deployment

Create Render Account

New Web Service

Click “New” → “Web Service”
Connect your GitHub repository
Configure as follows:

Configuration

Name: routa-app
Environment: Node
Build Command: npm install --legacy-peer-deps && npm run build
Start Command: npm start

Add PostgreSQL

Click “New” → “PostgreSQL”
Note the Internal Database URL
Add to web service environment variables

Environment Variables

DATABASE_URL=<internal_postgres_url>
ROUTA_DB_DRIVER=postgres
ANTHROPIC_AUTH_TOKEN=sk-ant-...

Self-Hosted (VPS)

Deploy on your own server with PM2.

Prerequisites

# Install Node.js 22+
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install PM2
sudo npm install -g pm2

Clone and Build

git clone https://github.com/routa/routa-js.git
cd routa-js
npm install --legacy-peer-deps
npm run build

Configure Environment

Create .env.production:

DATABASE_URL=postgresql://routa:password@localhost:5432/routa
ROUTA_DB_DRIVER=postgres
ANTHROPIC_AUTH_TOKEN=sk-ant-...
PORT=3000
NODE_ENV=production

Start with PM2

pm2 start npm --name routa -- start
pm2 save
pm2 startup

Setup Nginx Reverse Proxy

/etc/nginx/sites-available/routa

server {
    listen 80;
    server_name routa.yourdomain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }

    location /api/mcp {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Enable and restart:

sudo ln -s /etc/nginx/sites-available/routa /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl restart nginx

Database Setup

PostgreSQL (Recommended)

# No setup needed - managed service
DATABASE_URL=postgresql://user:[email protected]/routa?sslmode=require

SQLite (Development Only)

SQLite is not recommended for production web deployments. Use PostgreSQL instead.

.env

ROUTA_DB_DRIVER=sqlite
ROUTA_DB_PATH=/tmp/routa.db

Running Migrations

npm run db:push

Health Checks

Routa exposes a health endpoint at /api/health:

curl https://your-deployment.vercel.app/api/health

Response:

{
  "status": "ok",
  "version": "0.2.3",
  "database": "connected",
  "timestamp": "2026-03-03T12:00:00.000Z"
}

Monitoring

Vercel Analytics

Enable in Vercel dashboard → Analytics → Enable.

Custom Logging

Routa logs to stdout. Configure log drains: Vercel: Settings → Integrations → Log Drains Railway: Built-in logs in dashboard Self-hosted: Use PM2 logs:

pm2 logs routa
pm2 logs routa --lines 100

Troubleshooting

Database connection timeout

Verify DATABASE_URL is correct
Check database is accessible from deployment region
For Neon: ensure connection pooling is enabled
Add ?connection_limit=1 to SQLite URLs on serverless

Build failures

Ensure --legacy-peer-deps flag is used
Check Node.js version is 22+
Clear build cache and retry

MCP connection errors

Verify WebSocket support is enabled
Check CORS settings allow MCP endpoints
Ensure /api/mcp route is not cached

Agent spawn failures

ACP agents (OpenCode, Codex) may not work on serverless (no persistent processes)
Use Claude Code SDK for serverless environments
Consider Docker or VPS deployment for full agent support

Next Steps

Docker Deployment

Deploy with Docker for full feature support

Custom MCP Servers

Integrate external tools via MCP

Workflows

Automate tasks with YAML workflows

GitHub Integration

Connect GitHub repositories

Get Started

Core Concepts

Protocols

Guides

Specialists

Development

Web Deployment Guide

Overview

Vercel Deployment

Environment Variables for Vercel

Vercel Configuration

Railway Deployment

Build Configuration for Railway

Render Deployment

Self-Hosted (VPS)

Database Setup

PostgreSQL (Recommended)

SQLite (Development Only)

Running Migrations

Health Checks

Monitoring

Vercel Analytics

Custom Logging

Troubleshooting

Next Steps

Docker Deployment

Custom MCP Servers

Workflows

GitHub Integration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Protocols

Guides

Specialists

Development

​Overview

​Vercel Deployment

​Environment Variables for Vercel

​Vercel Configuration

​Railway Deployment

​Build Configuration for Railway

​Render Deployment

​Self-Hosted (VPS)

​Database Setup

​PostgreSQL (Recommended)

​SQLite (Development Only)

​Running Migrations

​Health Checks

​Monitoring

​Vercel Analytics

​Custom Logging

​Troubleshooting

​Next Steps

Docker Deployment

Custom MCP Servers

Workflows

GitHub Integration

Build docs developers (and LLMs) love

Overview

Vercel Deployment

Environment Variables for Vercel

Vercel Configuration

Railway Deployment

Build Configuration for Railway

Render Deployment

Self-Hosted (VPS)

Database Setup

PostgreSQL (Recommended)

SQLite (Development Only)

Running Migrations

Health Checks

Monitoring

Vercel Analytics

Custom Logging

Troubleshooting

Next Steps