Skip to main content

​
Quickstart Guide

This guide will get you up and running with Routa in 5 minutes. You’ll start the application and run your first multi-agent coordination workflow.
Routa primarily provides a desktop application (Tauri-based). The web version is available for demo purposes only.

​
Prerequisites

Before you begin, ensure you have:
  • Node.js 22 or later
  • npm or another package manager
  • Git (for cloning the repository)
  • An AI provider API key (Anthropic, OpenAI, etc.)

​
Choose Your Path

Desktop App

Recommended for production use

Web Demo

Quick testing and evaluation
The desktop app provides the full Routa experience with an embedded Rust server and SQLite database.
1

Clone the Repository

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

Install Dependencies

npm install --legacy-peer-deps
The --legacy-peer-deps flag is required due to peer dependency conflicts in some packages.
3

Start the Desktop App

npm run tauri dev
This will:
  • Build the Next.js frontend
  • Compile the Rust backend
  • Launch the Tauri desktop application
  • Initialize the SQLite database
4

Configure API Keys

On first launch, configure your AI provider in Settings:
  1. Click the Settings icon in the sidebar
  2. Navigate to API Configuration
  3. Add your API key for your preferred provider:
    • Anthropic (Claude)
    • OpenAI (GPT models)
    • Google (Gemini)
Keep your API keys secure. Never commit them to version control.

​
Your First Coordination

Once the application is running, let’s try a simple multi-agent coordination workflow.
1

Create a Workspace

  1. Click Workspaces in the sidebar
  2. Click New Workspace
  3. Name it “Quick Test”
  4. Set the path to an empty directory or test project
2

Start a Coordination Session

Click the Chat panel and enter a task:
Create a simple Python calculator module with functions for add, subtract, multiply, and divide. Include unit tests.
3

Watch the Agents Work

You’ll see the coordination flow:

🔵 Coordinator Agent

  • Analyzes your requirement
  • Creates a structured Spec with tasks
  • Breaks down into:
    1. Implement calculator functions
    2. Write unit tests
    3. Verify implementation
  • Two CRAFTER agents spawn in parallel
  • One implements the calculator module
  • Another writes the test suite
  • Both report completion to the coordinator
  • GATE agent reviews the implementation
  • Runs unit tests
  • Validates against acceptance criteria
  • Reports verification results
4

Review the Results

Once complete, you’ll see:
  • Files Created: calculator.py, test_calculator.py
  • Tests Passed: All unit tests green
  • Verification: Complete with evidence
Check the Agent Panel to see conversation history and task details.

​
Understanding the Workflow

Here’s what happened behind the scenes:

​
CLI Alternative

You can also use the Rust CLI for coordination: 
# Quick coordination with a single command
routa -p "Create a Python calculator with tests"

# With custom workspace
routa -p "Add OAuth login" --workspace-id my-project

​
Next Steps

Core Concepts

Learn about specs, tasks, and coordination patterns

Specialists

Understand roles and create custom specialists

Configuration

Configure workspaces, MCP servers, and API providers

API Reference

Explore the full REST and protocol APIs

​
Troubleshooting

Issue: Tauri build fails or app crashes on launchSolutions:
  • Ensure you have Rust installed: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • On Linux, install WebKit dependencies: sudo apt install webkit2gtk-4.0
  • On Windows, install Visual Studio Build Tools
  • Check logs in the terminal for specific errors
Issue: SQLite database errors on first runSolutions:
  • Delete the database file and restart: rm routa.db
  • Check file permissions in the data directory
  • Ensure better-sqlite3 is properly installed: npm rebuild better-sqlite3
Issue: Cannot spawn OpenCode or other ACP agentsSolutions:
  • Verify the agent binary is installed and in PATH
  • For OpenCode: npx opencode-ai@latest --version
  • For Claude: Install from VS Code marketplace
  • Check Settings → ACP Providers for configuration
Issue: Authentication failures with AI providersSolutions:
  • Verify your API key is valid and has proper permissions
  • Check rate limits and quota on your provider account
  • For Anthropic: Ensure you have access to Claude Code SDK
  • Add API key to Settings → API Configuration

​
Getting Help

If you run into issues:
  • Check the full installation guide for detailed setup instructions
  • Review common issues on GitHub
  • Join our community discussions
  • File a bug report with logs and reproduction steps

Build docs developers (and LLMs) love

Get started for freeTalk to us