---
title: URL Routing and Webapps
description: Route matching URLs to Omarchy webapps while keeping the normal browser fallback.
sidebar:
  order: 7
---

The custom URL handler makes `http` and `https` links choose between two launch paths:

- Matching URLs open as standalone Omarchy webapps.
- Everything else opens in Chromium as a normal browser tab or window.

This keeps common app-like sites in dedicated windows without making every link a webapp.

## Files

The handler is part of the stowed Hypr package:

| Path | Purpose |
| --- | --- |
| `~/.config/hypr/bin/timmo-url-handler` | Runtime URL router. |
| `~/.config/hypr/bin/timmo-setup-url-handler` | Idempotent install/remove helper. |
| `~/.config/hypr/url-handler/patterns.conf` | Routing rules. |
| `~/.config/hypr/url-handler/omarchy-url-handler.desktop` | Desktop entry used by xdg mime handling. |

Edit the source files in the dotfiles repo, then run `dot stow`:

```text
~/.config/dotfiles/hypr/.config/hypr/
```

## Install the handler

Run the setup helper after the Hypr package is stowed and `~/.config/hypr/bin` is on `PATH`:

```bash
timmo-setup-url-handler
```

The setup helper:

- Creates or updates the desktop file.
- Symlinks it into `~/.local/share/applications/`.
- Sets it as the default handler for `http`, `https`, `about`, and `unknown` schemes in `~/.config/mimeapps.list`.
- Backs up `mimeapps.list` before changing it.
- Runs `update-desktop-database` when that command is available.

## Pattern rules

Rules live in:

```text
~/.config/hypr/url-handler/patterns.conf
```

Each non-comment line starts with an action and a glob pattern:

```text
webapp:discord.com
webapp:*.youtube.com
browser:*.gitlab.com
```

Patterns are checked against both the full URL and the extracted domain. The first matching rule wins.

If nothing matches, the default action is `browser`.

## Add a webapp route

1. Edit `~/.config/dotfiles/hypr/.config/hypr/url-handler/patterns.conf`.
2. Add a `webapp:<pattern>` line above any broader browser rule.
3. Run `dot stow`.
4. Test with `timmo-url-handler <url>`.


Example:

```text
webapp:calendar.google.com
webapp:*.calendar.google.com
```

## Force a normal browser route

Use `browser:<pattern>` when a site should not become a webapp:

```text
browser:gitlab.com
browser:*.gitlab.com
```

Browser routes launch Chromium directly through `uwsm-app` so the default handler does not recurse back into itself.

## Test routing

Run the handler directly:

```bash
timmo-url-handler https://github.com
timmo-url-handler https://gitlab.com
```

To check the desktop default:

```bash
xdg-mime query default x-scheme-handler/https
```

Expected output:

```text
omarchy-url-handler.desktop
```

## Remove the handler

```bash
timmo-setup-url-handler remove
```

The remove path deletes the applications symlink and desktop file. If the setup backup exists, it restores `~/.config/mimeapps.list` from that backup. If no backup exists, clean up `mimeapps.list` manually.

## Troubleshooting

If the setup script cannot find `timmo-url-handler`, check that the Hypr bin directory is on `PATH` and run `dot stow` again.

If a URL opens in the browser when it should be a webapp, put the more specific `webapp:` rule before broader `browser:` rules and test the exact URL with `timmo-url-handler`.

If every browser launch loops, check that the `browser` branch still launches `/usr/bin/chromium` directly rather than calling `xdg-open`.