Introduction

View as Markdown

Umbra pins small, sharp, true-black widgets to the Windows desktop. They sit under every window, never steal focus, stay visible with Win+D and start with Windows.

A widget is a folder with a widget.json and a web page (HTML, CSS and JavaScript). Umbra’s host app, written in C# on .NET 10, opens each enabled widget in its own borderless WebView2 window and pins it to the desktop. The host knows nothing about any particular widget, so anyone can build one.

Why it feels different

It stays where it belongs. Widget windows are owned by the desktop shell and kept at the bottom of the window stack, so your apps always cover them.
It’s sharp. Windows are opaque true black with corners and a hairline border drawn by Windows itself, so text keeps full ClearType quality. On an OLED screen the black pixels are simply off, and each card seems to float on your wallpaper.
It’s safe. A widget can only reach the HTTPS hosts it declares. The host blocks everything else. An update that asks for new access waits for your OK, and a widget can start a local program only if it declared that exact command and you approved it.
It’s private. No account, no telemetry. Settings, widget data and logs stay in %APPDATA%\Umbra.
It’s scriptable. The umbractl command line and a built-in MCP server let scripts and AI agents arrange widgets, take screenshots and write new widgets.

Where to go next

You want to…	Read
Install Umbra and add your first widgets	Install, then Quickstart
Arrange, theme and tune your desktop	Using Umbra
Build a widget	Your first widget and the SDK reference
Script Umbra or connect an AI agent	Automate
Work on the app itself	Internals

Requirements

Windows 10 version 1809 or later, or Windows 11. Umbra uses the WebView2 runtime, which ships with current Windows; the installer tells you if it’s missing. A Linux version is in progress (#172).

Umbra is free and open source under the MIT license.