Installation Guide

Routa supports three deployment methods:

Desktop Application (Recommended) — Tauri-based native app with embedded Rust server
Web Deployment — Next.js application on Vercel or self-hosted
Docker — Containerized deployment with PostgreSQL or SQLite

Desktop

Native performance, embedded database, offline capable

Web

Serverless deployment, multi-user, PostgreSQL backend

Docker

Self-hosted, isolated, easy scaling

System Requirements

Desktop
Web
Docker

Desktop Application

Operating System: Windows 10+, macOS 11+, or Linux (Ubuntu 20.04+)
Node.js: 22.x or later
Rust: 1.70+ (installed automatically by rustup)
Memory: 4GB RAM minimum, 8GB recommended
Disk Space: 500MB for application + workspace storage

Platform-Specific Dependencies

Linux

Ubuntu/Debian

sudo apt update
sudo apt install -y \
  libwebkit2gtk-4.0-dev \
  build-essential \
  curl \
  wget \
  file \
  libssl-dev \
  libgtk-3-dev \
  libayatana-appindicator3-dev \
  librsvg2-dev

Fedora

sudo dnf install -y \
  webkit2gtk4.0-devel \
  openssl-devel \
  curl \
  wget \
  file \
  gtk3-devel \
  librsvg2-devel

macOS

Install Xcode Command Line Tools:

xcode-select --install

Install Homebrew (if not already installed):

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Windows

Install Visual Studio Build Tools
During installation, select “Desktop development with C++”
Install WebView2 (usually pre-installed on Windows 11)

Installation Methods

Desktop
Web
Docker

Desktop Application

Install Rust

If you don’t have Rust installed:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Verify installation:

rustc --version
cargo --version

Clone Repository

git clone https://github.com/yourusername/routa.git
cd routa

Install Node Dependencies

npm install --legacy-peer-deps

The --legacy-peer-deps flag is required for npm due to peer dependency conflicts in some dependencies.

Build and Run

Development
Production Build

npm run tauri dev

This starts the desktop app in development mode with hot reload.

npm run tauri build

The installer will be created in:

Windows: apps/desktop/src-tauri/target/release/bundle/msi/
macOS: apps/desktop/src-tauri/target/release/bundle/dmg/
Linux: apps/desktop/src-tauri/target/release/bundle/deb/ or .AppImage

Configure on First Launch

On first launch, you’ll need to:

Set API Keys: Configure your AI provider API keys in Settings
Create Workspace: Set up your first workspace directory
Install ACP Agents: (Optional) Install OpenCode, Claude CLI, or other agents

The SQLite database will be automatically created at:

Windows: %APPDATA%/com.routa.app/routa.db
macOS: ~/Library/Application Support/com.routa.app/routa.db
Linux: ~/.local/share/com.routa.app/routa.db

CLI Installation (Optional)

Build the Rust CLI for terminal-based coordination:

cargo build --release --manifest-path crates/routa-cli/Cargo.toml

The binary will be at crates/routa-cli/target/release/routa. Add it to your PATH:

# Linux/macOS
sudo cp crates/routa-cli/target/release/routa /usr/local/bin/

# Or add to PATH in your shell profile
export PATH="$PATH:$(pwd)/crates/routa-cli/target/release"

Verify:

routa --version

Web Deployment

Local Development

Clone and Install

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

Configure Environment

Create .env.local in the project root:

.env.local

# Database Configuration
ROUTA_DB_DRIVER=sqlite
ROUTA_DB_PATH=./data/routa.db

# For PostgreSQL (production):
# ROUTA_DB_DRIVER=postgres
# DATABASE_URL=postgresql://user:password@localhost:5432/routa

# AI Provider API Keys
ANTHROPIC_AUTH_TOKEN=sk-ant-...
# Or OpenAI:
# OPENAI_API_KEY=sk-...

# Optional: Custom endpoints
# ANTHROPIC_BASE_URL=https://api.anthropic.com
# API_TIMEOUT_MS=600000

Initialize Database

npm run db:sqlite:push

Start Development Server

npm run dev

Open http://localhost:3000

Vercel Deployment

Connect Repository

Push your repository to GitHub
Import project in Vercel Dashboard
Select the repository

Configure Environment Variables

In Vercel project settings, add:

ROUTA_DB_DRIVER=postgres
DATABASE_URL=postgresql://user:password@host/database?sslmode=require
ANTHROPIC_AUTH_TOKEN=your_key_here

Use Neon or Vercel Postgres for the database. Vercel automatically provisions DATABASE_URL if you add Vercel Postgres.

Deploy

npm run build
vercel --prod

Or push to main branch for automatic deployments.

Run Migrations

After first deployment:

vercel env pull .env.production.local
npm run db:push:ci

Self-Hosted (PM2)

Build for Production

npm run build

Install PM2

npm install -g pm2

Start with PM2

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

Configure Reverse Proxy

server {
    listen 80;
    server_name routa.example.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;
    }
}

Docker Deployment

SQLite (Default)

Simplest deployment with no external database required:

Clone Repository

git clone https://github.com/yourusername/routa.git
cd routa

Build and Start

docker compose up --build

The application will be available at http://localhost:3000

Run in Background

docker compose up -d

View logs:

docker compose logs -f app

PostgreSQL (Production)

For production deployments with better concurrency:

Create Environment File

Create .env in the project root:

.env

ROUTA_DB_DRIVER=postgres
DATABASE_URL=postgresql://routa:routa_secret@postgres:5432/routa
POSTGRES_PASSWORD=routa_secret

# AI Provider Keys
ANTHROPIC_AUTH_TOKEN=your_key_here

Change routa_secret to a strong password for production!

Start with Postgres Profile

docker compose --profile postgres up --build

This starts both the app and a PostgreSQL container.

Verify Health

curl http://localhost:3000/api/health

Expected response:

{
  "status": "ok",
  "database": "connected",
  "version": "0.2.3"
}

External PostgreSQL

To use an external managed database (AWS RDS, Azure Database, etc.):

Configure External Database

Update .env:

.env

ROUTA_DB_DRIVER=postgres
DATABASE_URL=postgresql://user:password@external-host:5432/routa?sslmode=require

Start App Only

docker compose up app

The postgres service won’t start since we’re using an external database.

Docker Compose Configuration

The docker-compose.yml includes:

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      ROUTA_DB_DRIVER: sqlite
      ROUTA_DB_PATH: /app/data/routa.db
    volumes:
      - routa_data:/app/data
    restart: unless-stopped

volumes:
  routa_data:

Backup and Restore

SQLite
PostgreSQL

Backup

docker compose cp app:/app/data/routa.db ./backup-$(date +%Y%m%d).db

Restore

docker compose cp ./backup-20260303.db app:/app/data/routa.db
docker compose restart app

Backup

docker compose exec postgres pg_dump -U routa routa > backup-$(date +%Y%m%d).sql

Restore

docker compose exec -T postgres psql -U routa routa < backup-20260303.sql

Post-Installation Setup

Configure API Keys

Add your AI provider API keys in one of these ways:

Web UI: Settings → API Configuration
Environment Variables: Add to .env.local or .env
Desktop App: Settings panel on first launch

Supported providers:

Anthropic (Claude)
OpenAI (GPT models)
Google (Gemini)
Custom OpenAI-compatible APIs

Install ACP Agents (Optional)

Install agent binaries for delegation:

npm install -g opencode-ai@latest
# Or use npx (no install required)

Create Your First Workspace

Open the application
Navigate to Workspaces
Click New Workspace
Set name and directory path
Optionally configure Git repository

Verify Installation

Test the coordination system:

Web UI
CLI

Open the Chat panel
Enter: “Create a hello.py file that prints Hello World”
Watch the agent coordination flow
Verify the file was created

routa -p "Create a hello.py file that prints Hello World"

You should see agent activity and file creation.

Configuration Files

Environment Variables Reference

ROUTA_DB_DRIVER

string

default:"sqlite"

Database driver: sqlite or postgres

ROUTA_DB_PATH

string

default:"./routa.db"

SQLite database file path (only used when ROUTA_DB_DRIVER=sqlite)

DATABASE_URL

string

PostgreSQL connection string (only used when ROUTA_DB_DRIVER=postgres)Format: postgresql://user:password@host:port/database?sslmode=require

ANTHROPIC_AUTH_TOKEN

string

Anthropic API key for Claude models

OPENAI_API_KEY

string

OpenAI API key for GPT models

ANTHROPIC_BASE_URL

string

default:"https://api.anthropic.com"

Custom Anthropic-compatible API endpoint

API_TIMEOUT_MS

number

default:"600000"

API request timeout in milliseconds (10 minutes default)

CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC

boolean

default:"false"

Disable non-essential telemetry for Claude Code

GITHUB_TOKEN

string

GitHub personal access token for webhook and virtual workspace features

GITHUB_POLLING_ENABLED

boolean

default:"false"

Enable GitHub issue polling adapter (alternative to webhooks)

GITHUB_POLLING_INTERVAL

number

default:"30"

Polling interval in seconds (minimum: 10)

Troubleshooting

Rust build fails

Symptoms: Errors during npm run tauri dev or cargo buildSolutions:

Update Rust: rustup update
Clear build cache: cargo clean
On Linux, install missing dependencies (see platform-specific section)
On Windows, ensure Visual Studio Build Tools are installed
Check disk space (needs ~2GB for debug builds)

Database connection errors

Symptoms: Connection refused or Database locked errorsSolutions:

For SQLite: Check file permissions and ensure directory exists
For PostgreSQL: Verify DATABASE_URL is correct and database is running
Test connection: psql $DATABASE_URL
Run migrations: npm run db:push
For “database locked”: Close other connections or use PostgreSQL

Node dependencies fail to install

Symptoms: Peer dependency conflicts or build failuresSolutions:

Use the --legacy-peer-deps flag with npm
Try pnpm: pnpm install --shamefully-hoist
Clear cache: npm cache clean --force
Delete node_modules and reinstall
Ensure Node.js version is 22.x or later

Docker build fails

Symptoms: Build errors or container won’t startSolutions:

Ensure Docker daemon is running
Update Docker to latest version
Clear build cache: docker builder prune
Check available disk space
On Windows/Mac, increase Docker memory allocation (Settings → Resources)
Review logs: docker compose logs app

ACP agent spawn fails

Symptoms: Cannot delegate to OpenCode, Claude, or other agentsSolutions:

Verify agent binary is installed and in PATH
Test manually: opencode --version or claude --version
Check Settings → ACP Providers for correct configuration
For npx-based agents: Ensure internet connection
Review agent logs in the UI or database

Port 3000 already in use

Symptoms: EADDRINUSE: address already in use :::3000Solutions:

Change port: PORT=3001 npm run dev
Find and kill process: lsof -ti:3000 | xargs kill (Linux/Mac)
Or: npx kill-port 3000
For Docker: Change port mapping in docker-compose.yml

Next Steps

Quickstart

Run your first multi-agent coordination in 5 minutes

Configuration

Configure workspaces, MCP servers, and custom specialists

Core Concepts

Learn about specs, tasks, and coordination patterns

API Reference

Explore the REST and protocol APIs

Upgrading

To upgrade to a newer version:

Desktop
Web
Docker

git pull origin main
npm install --legacy-peer-deps
npm run tauri build

Install the new build from the target/release/bundle/ directory.

git pull origin main
npm install --legacy-peer-deps
npm run db:push  # Run migrations
npm run build

Then restart your deployment.

git pull origin main
docker compose down
docker compose up --build -d

Always backup your database before upgrading!

Get Started

Core Concepts

Protocols

Guides

Specialists

Development

Installation

Installation Guide

Desktop

Web

Docker

System Requirements

Desktop Application

Platform-Specific Dependencies

Web Deployment

Docker Deployment

Installation Methods

Desktop Application

CLI Installation (Optional)

Web Deployment

Local Development

Vercel Deployment

Self-Hosted (PM2)

Docker Deployment

SQLite (Default)

PostgreSQL (Production)

External PostgreSQL

Docker Compose Configuration

Backup and Restore

Post-Installation Setup

Configuration Files

Environment Variables Reference

Troubleshooting

Next Steps

Quickstart

Configuration

Core Concepts

API Reference

Upgrading

Build docs developers (and LLMs) love

Get Started

Core Concepts

Protocols

Guides

Specialists

Development

​Installation Guide

Desktop

Web

Docker

​System Requirements

​Desktop Application

​Platform-Specific Dependencies

​Web Deployment

​Docker Deployment

​Installation Methods

​Desktop Application

​CLI Installation (Optional)

​Web Deployment

​Local Development

​Vercel Deployment

​Self-Hosted (PM2)

​Docker Deployment

​SQLite (Default)

​PostgreSQL (Production)

​External PostgreSQL

​Docker Compose Configuration

​Backup and Restore

​Post-Installation Setup

​Configuration Files

​Environment Variables Reference

​Troubleshooting

​Next Steps

Quickstart

Configuration

Core Concepts

API Reference

​Upgrading

Build docs developers (and LLMs) love

Installation Guide

System Requirements

Desktop Application

Platform-Specific Dependencies

Web Deployment

Docker Deployment

Installation Methods

Desktop Application

CLI Installation (Optional)

Web Deployment

Local Development

Vercel Deployment

Self-Hosted (PM2)

Docker Deployment

SQLite (Default)

PostgreSQL (Production)

External PostgreSQL

Docker Compose Configuration

Backup and Restore

Post-Installation Setup

Configuration Files

Environment Variables Reference

Troubleshooting

Next Steps

Upgrading