Skip to content

Installation (Development)

This guide covers how to install Sovara from source for development purposes.

Prerequisites

  • Python 3.10 or higher
  • Node.js 22 or higher (matches CI for UI development)
  • Git

uv is a fast Python package installer that simplifies dependency management.

Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with Homebrew
brew install uv

Clone and Install

git clone https://github.com/SovaraLabs/sovara.git
cd sovara

# Install with all development dependencies
uv sync --extra dev --extra docs

This installs:

  • dev - Testing tools (pytest, black) and provider SDKs
  • docs - Documentation tools (mkdocs-material)

Running Commands

With uv, use uv run to execute commands in the project environment:

# Run the server
uv run so-server start

# Record a script
uv run so-record script.py

# Run tests
uv run pytest

# Build documentation
uv run mkdocs serve

Option 2: Using Conda + pip

Traditional installation using conda for environment management and pip for package installation.

Create Environment

# Create and activate conda environment
conda create -n sovara python=3.13 -y
conda activate sovara

# Clone the repository
git clone https://github.com/SovaraLabs/sovara.git
cd sovara

# Install in development mode with all extras
pip install -e ".[dev,docs]"

Running Commands

With conda, activate the environment first:

conda activate sovara

# Run the server
so-server start

# Record a script
so-record script.py

# Run tests
pytest

# Build documentation
mkdocs serve

VS Code Extension Development

The VS Code extension requires additional setup:

cd ui/vscode_extension

# Install npm dependencies
npm install

# Build the extension
npm run compile

# Or watch for changes during development
npm run watch

To test the extension in VS Code:

  • If you opened the repo root, use the Run Extension launch configuration.
  • If you opened ui/user-interface.code-workspace, use Run VS Code Extension.

Then press F5.

Standalone Web App Development

The standalone web app lives in ui/web_app and uses the same backend as the VS Code extension.

cd ui

# Install UI dependencies
npm run install:all

# Start the web app dev server
npm run dev:webapp

If you change backend route shapes or websocket payloads, restart the backend before reloading the web app.

Verifying Installation

After installation, verify everything works:

# Check CLI tools are available
so-server --help
so-record --help

# Start the server
so-server start

# Check server logs
so-server logs

# Run a simple test
uv run pytest tests/non_billable/ -v --tb=short

Next Steps