Documentation

Everything you need to bend Umbra to your will.

Getting Started

Umbra works hard out of the box and bends completely to your config. Start with defaults; tear it down whenever you're ready.

  • Launch Umbra from your applications menu or run the binary from the terminal (add --safe to boot with all plugins and user config disabled).
  • On first launch, an interactive setup helps you choose your theme and layout combination with zero manual setup required.
  • Everything is driven by a single config file at ~/.config/umbra/umbra.toml. The Settings GUI (Ctrl+,) writes this file under the hood.
  • The built-in ad/tracker blocker is enabled by default and removable, like every other component.
  • Press Ctrl+K for the command palette: searchable settings, actions, layouts, themes, and open tabs.

Configuration

Umbra's entire behavior lives in one TOML file at ~/.config/umbra/umbra.toml: theme preset and custom design tokens, layout presets (compact, minimal, sidebar, zen), keybindings, feature flags (adblock, modal_mode, notify_reload, …), plugins, a new-tab page section, and a User-Agent override.

  • Hot reload: save the file and changes apply live via a filesystem watcher with zero restart.
  • Validation & rollback: config is schema-validated before applying. Every successful reload snapshots a last-known-good copy; a broken edit rolls back automatically with a toast, so a typo never takes your browser down.
  • Safe mode: launch with --safe to disable all plugins and user config.

Themes & Packages

Theming works in layers: design tokens (colors, radius, blur, fonts, easing) handle most reskins with a single file swap; full component replacement goes further for themes that need different rendering entirely. Glassmorphism is the default aesthetic; built-in presets include glass (default), material (Material 3), gruvbox, nord, catppuccin, and ocean.

Themes and plugins distribute as .umbrapkg packages: zip archives with a manifest.toml, optional token overrides, components, scripts, and assets. Install one-click from the community gallery (GitHub topics umbra-theme / umbra-plugin) or paste a GitHub URL or local path in Settings → Plugins → Packages & Gallery. Every install shows a diff of exactly what will change before it's applied.

Plugins

Plugins are sandboxed Lua (with a WASM tier for compiled extensions), each declaring capability flags in its manifest: fs, net, ui. Nothing outside the declared capabilities is granted. Per-plugin memory caps (32 MiB) and CPU budgets mean a runaway plugin errors out instead of pegging your machine.

A plugin registers components into named slots (top-bar, tab-strip, bookmarks-bar, sidebar-left/right, status-bar, overlay) via the umbra.register_component{component=…, slot=…} API, plus capability-gated hosts like umbra.net.request{…}. Plugin logs and errors surface in the console panel (Ctrl+Shift+C).

Import & Sync

On first launch — or any time from Settings → Import — Umbra scans the default XDG paths for installed browser profiles and imports bookmarks and history from Chromium-family browsers (Chrome, Chromium, Brave, Edge, Vivaldi, Opera, Arc, Epiphany) and Firefox-family browsers (Firefox, LibreWolf, Zen, Waterfox, Floorp). Passwords are intentionally never imported.

Settings → Sync pushes and pulls umbra.toml + bookmarks.toml to a private GitHub gist you configure with a personal-access token (stored with 0600 permissions). Browsing data — history, tabs — is never synced.

Browser Identity

Umbra renders through WebKitGTK, but its default User-Agent presents as desktop Firefox on Linux so sites don't treat it as an unknown mobile Safari. Presets (Firefox, Chrome, Edge, Brave, Safari) and a free-text custom value live in Settings → Browser, persisted as user_agent in umbra.toml. The UMBRA_USER_AGENT environment variable overrides both.

Control Socket

Umbra exposes a Unix socket at ~/.config/umbra/umbra.sock for external scripting, hyprctl-style:

SOCK=~/.config/umbra/umbra.sock

echo "ping" | socat - UNIX-CONNECT:$SOCK   # → pong
echo "tabs" | socat - UNIX-CONNECT:$SOCK   # JSON list of tabs
echo "new https://example.com" | socat - UNIX-CONNECT:$SOCK
echo "layout sidebar" | socat - UNIX-CONNECT:$SOCK
echo "quit" | socat - UNIX-CONNECT:$SOCK

Commands include ping, tabs, open, new, reload, layout, slots, plugins, bm, safe, quit, and help.

Building from Source

See the Downloads page for the full guide. Short version: install the Rust toolchain and Linux WebKitGTK dependencies, run npm --prefix umbra/ui install, then cargo build --release from src-tauri/ (or use cargo tauri dev / cargo tauri build).

FAQ

Is Umbra based on Firefox, LibreWolf, or Chromium?

No. Umbra is an independent browser: a Rust backend under Tauri v2, with pages rendered by WebKitGTK (webkit2gtk-4.1). There is no Gecko, no LibreWolf, and no Chromium codebase involved — nothing to compile for hours, and no upstream browser you have to rebase onto. The only Firefox-shaped thing is the default User-Agent string, which is cosmetic and fully configurable.

Can I use Firefox or Chrome extensions?

No. Umbra's extensibility model is different: sandboxed Lua and WASM plugins with capability manifests, themes built on design tokens, and slot-based component replacement. Anything a traditional extension would do can be built as a plugin instead.

How do I report a bug?

Open an issue on the GitHub repository.

Does Umbra have auto-updates?

Not yet. For now, download new releases manually or rebuild from source by checking the GitHub releases page when updates ship.