Desktop App Usage Guide

Overview

Routa Desktop is the recommended distribution for Routa. It provides a native application experience with an embedded server, local database, and seamless agent orchestration. The desktop app is built using:

Tauri 2.0 - Rust-based desktop framework
SQLite - Embedded database (no external setup required)
Next.js - Frontend bundled into the application
Embedded Server - Rust-based server running locally on port 3210

Installation

Prerequisites

Install Node.js

Download and install Node.js 22+ LTS version.

Install Rust (for building)

If building from source, install Rust toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Install System Dependencies

macOS:

xcode-select --install

Linux (Ubuntu/Debian):

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

Windows: Install WebView2 Runtime (usually pre-installed on Windows 11).

Building from Source

Clone and Install

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

Run Development Build

npm run tauri dev

This starts the desktop app with hot reload enabled.

Build Production Binary

npm run build:desktop
npm run tauri build

Binaries will be in apps/desktop/src-tauri/target/release/bundle/

Configuration

Application Settings

The desktop app stores configuration in:

~/Library/Application Support/com.routa.desktop/

Database Location

The SQLite database is stored at:

Development: apps/desktop/src-tauri/routa.db
Production: {app_data}/routa.db

The database is created automatically on first launch.

Environment Variables

Create a .env file in the project root:

.env

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

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

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

# Database (SQLite by default)
ROUTA_DB_DRIVER=sqlite
ROUTA_DB_PATH=./routa.db

# Server configuration
PORT=3210
HOST=127.0.0.1

Features

Window Configuration

The desktop app window is configured in apps/desktop/src-tauri/tauri.conf.json:

tauri.conf.json

{
  "app": {
    "windows": [
      {
        "label": "main",
        "title": "Routa",
        "width": 1440,
        "height": 900,
        "minWidth": 900,
        "minHeight": 600,
        "resizable": true
      }
    ]
  }
}

Tauri Plugins

The desktop app includes the following plugins:

Dialog

Native file/folder picker dialogs

File System

Read/write files with permission prompts

Notifications

System notifications for agent events

Process

Spawn and manage child processes

Shell

Execute shell commands securely

SQL

Direct SQLite database access

Agent Spawning

The desktop app can spawn AI agents locally:

Claude Code - via @anthropic-ai/claude-agent-sdk
OpenCode - via opencode-ai (if installed)
Codex - via @openai/codex (if installed)
Gemini - via @google/generative-ai-cli (if installed)

Agents run as child processes with MCP connection to the embedded server at http://127.0.0.1:3210/mcp.

Usage Workflows

Starting a Coordination Session

Launch the App

Open Routa Desktop from your applications folder or run npm run tauri dev.

Create a Workspace

Click “New Workspace” and select a local directory or import a GitHub repository.

Start a Conversation

Type your task description in the chat panel. The coordinator will parse your intent and create a structured plan.

Monitor Agent Activity

Watch the Agents panel to see spawned specialists and their progress.

Review Results

Verification agents (GATE) will validate the work before marking tasks complete.

Using Custom Specialists

Custom specialists are loaded from:

Database (highest priority)
User files at ~/.routa/specialists/*.md or ~/.routa/specialists/*.yaml
Bundled specialists in resources/specialists/
Hardcoded fallbacks

See Custom Specialists for details.

Managing MCP Servers

Add custom MCP servers via the Settings panel:

Open Settings → MCP Servers
Click “Add Server”
Configure stdio, HTTP, or SSE connection
Enable the server
Restart agents to use the new MCP tools

See Custom MCP Servers for configuration examples.

Troubleshooting

App Won’t Launch

macOS: 'App is damaged' error

Remove the quarantine attribute:

xattr -cr /Applications/Routa.app

Linux: Missing shared libraries

Install WebKit dependencies:

sudo apt-get install -y libwebkit2gtk-4.0-37

Windows: WebView2 not found

Download and install WebView2 Runtime.

Database Issues

# Reset the database (deletes all data)
rm ~/Library/Application\ Support/com.routa.desktop/routa.db

# Or specify a new database location in .env
ROUTA_DB_PATH=/custom/path/routa.db

Port Conflicts

If port 3210 is in use, change it in .env:

PORT=3211

Restart the app for changes to take effect.

Agent Spawn Failures

Check that API keys are set in .env
Verify agent CLIs are installed (opencode-ai, @openai/codex, etc.)
Check logs in the console (View → Developer → Developer Tools)

CLI Integration

The desktop distribution includes a routa CLI:

# Full coordinator flow
routa -p "Implement feature X"

# Agent management
routa agent list
routa agent create --specialist CRAFTER
routa agent status <agent-id>

# Task management
routa task list
routa task create --title "Task title" --body "Task body"
routa task get <task-id>

# Interactive chat
routa chat

See the CLI section in Architecture for more commands.

Next Steps

Custom Specialists

Create your own specialist roles

Custom MCP Servers

Integrate external MCP tools

Workflows

Automate multi-step processes

GitHub Integration

Work with remote repositories

Get Started

Core Concepts

Protocols

Guides

Specialists

Development

​Overview

​Installation

​Prerequisites

​Building from Source

​Configuration

​Application Settings

​Database Location

​Environment Variables

​Features

​Window Configuration

​Tauri Plugins