Switchyard

A rules-based URL router for Linux.

Set up smart, automatic routing. Or choose your browser on the fly.

Features

• Rule-based routing: Automatically open URLs in specific browsers based on powerful patterns.
• Multi-condition rules: Combine multiple conditions with AND/OR logic for precise control.
• Multiple pattern types: Exact Domain, URL Contains, Wildcard, and Regex matching.
• Custom URI scheme: Create links that specify browser preferences directly with switchyard:// URLs.
• Quick browser picker: When no rule matches, choose from your installed browsers with keyboard or mouse.
• Keyboard shortcuts: Press Ctrl+1-9 to instantly select a browser.
• Lightweight: Runs only when needed, no background processes.
• GTK4 + libadwaita: Native GNOME look and feel.

Installation

Flatpak (Recommended)

Requires just for building.

# Build and install (automatically installs Flatpak runtimes if needed)
just flatpak

Nix Flake

A flake is provided for NixOS or Nix users. It also supplies a devShell and a formatter.

Add this repository to your flake inputs:

{
  inputs.switchyard.url = "github:alyraffauf/switchyard";
}

Then, add this to your NixOS configuration:

# Add to your NixOS configuration
{
  environment.systemPackages = [
    inputs.switchyard.packages.${system}.default
  ];
}

Building from Source

For non-Flatpak builds, requires Go 1.24+, GTK4/libadwaita development libraries, and just.

# Install dependencies (Fedora)
just install-deps

# Build
just build

# Install to /usr/local
sudo just install

# Or install to custom prefix
sudo PREFIX=/usr just install

Set as Default Browser

After installation, set Switchyard as your default browser so it can route all clicked links:

xdg-settings set default-web-browser io.github.alyraffauf.Switchyard.desktop

Or use your desktop environment's graphical settings to set Switchyard as the default browser.

Usage

# Open settings
flatpak run io.github.alyraffauf.Switchyard

# Open a URL (typically called automatically by the system)
flatpak run io.github.alyraffauf.Switchyard "https://example.com"

# Non-Flatpak
switchyard
switchyard "https://example.com"

Keyboard Shortcuts

In the picker:

• Ctrl+1-9 - Select browser by number
• Escape - Close picker

In settings:

• Ctrl+Q - Quit

Documentation

• Configuration - Config file format, rules, and settings.
• URI Scheme - Custom switchyard:// URLs for specifying browser preferences.
• Prior Art - Similar tools that inspired Switchyard.

Development

Running Tests

The project includes unit tests for the core rule matching logic. Tests can run without GTK dependencies.

# Run tests
just test

# Run tests with coverage report
just test-coverage

# View HTML coverage report
go tool cover -html=coverage.out

Tests are automatically run in CI on every push and pull request.

License

GPL-3.0-or-later