INDEX

Deskbrid Documentation

The HAL your Linux desktop agents are missing.

Deskbrid is a single Rust binary that auto-detects your desktop environment and provides a unified JSON-over-Unix-socket protocol for desktop automation on Linux. One daemon, one protocol, one binary — works across GNOME, Hyprland, KDE, wlroots compositors, and X11.

Quick Links

• Installation — install Deskbrid and configure desktop dependencies
• Quick Start — get running in a few minutes
• Protocol Overview — JSON protocol fundamentals
• v1.0.0 Release Notes — stable release notes, breaking changes, migration

Features

Full feature documentation by domain — every action, parameter, and example:

Domain	Actions	Doc
Apps	apps.list, apps.search, apps.get	Apps
Audio	audio.volume, audio.mute, audio.sinks	Audio
Audit	audit.query, audit.clear	Audit
Backlight	backlight.list, backlight.get, backlight.set	Backlight
Battery	battery.get	Battery
Bluetooth	bluetooth.list, bluetooth.pair, bluetooth.remove	Bluetooth
Browser	browser.cdp	Browser CDP
Clipboard	clipboard.read, clipboard.write, clipboard.history	Clipboard
Color Picker	color_picker	Color Picker
Confirmation	confirm.challenge, confirm.resolve	Confirmation
Connection	connection.subscribe, connection.unsubscribe, connection.disconnect	Connection
Cron	cron.schedule, cron.list, cron.remove	Cron
D-Bus	dbus.call	D-Bus
Desktop Portal	portal.screenshot, portal.screencast	Desktop Portal
Desktop Settings	settings.get, settings.set, settings.schema	Desktop Settings
Files	file.search, file.read, file.write, file.watch	Files
Hotkeys	hotkey.bind, hotkey.unbind	Hotkeys
Keyboard Layouts	layouts.list, layouts.switch, layouts.add, layouts.remove	Keyboard Layouts
Keyring	keyring.get, keyring.set, keyring.delete	Keyring
Location	location.get	Location
Lock/Mutex	lock.acquire, lock.release, lock.list	Lock/Mutex
Macros	macro.record, macro.replay	Macros
MPRIS Media	mpris.list, mpris.control, mpris.nowplaying	MPRIS
Mailbox	mailbox.send, mailbox.read, mailbox.delete	Mailbox
Monitor	monitor.list, monitor.set	Monitor
Network	network.wifi, network.status	Network
Notifications	notification.send, notification.close, notification.history	Notifications
Persistence	state.get, state.set, state.delete	Persistence
Print	print.list, print.jobs, print.file	Print
Process	process.list, process.kill	Process
Rules Engine	rules.list, rules.create, rules.trigger	Rules
Schedule	schedule.list, schedule.add, schedule.remove	Schedule
Screenshot	screenshot, screenshot.ocr, screenshot.diff	Screenshot
Screencast	screencast.start, screencast.stop	Screencast
Secrets	secrets.set, secrets.get, secrets.delete	Secrets
Self Update	update.check, update.apply	Self Update
Services	service.list, service.start, service.stop, service.status	Services
Sessions	session.list, session.switch, session.lock, session.logout	Sessions
System	system.info, system.health, system.power, system.pressure, system.idle, system.confinement, system.sessions, system.lock_session, system.switch_user, system.inhibit, system.release_inhibit, system.thermal, system.cpu_frequency, system.cpu_governor, system.set_cpu_governor, system.elevate, system.check_auth, system.capabilities	System
System Tray	tray.menu, tray.action	System Tray
Terminal PTY	terminal.create, terminal.write, terminal.read, terminal.kill	Terminal
Unified Search	search.query	Unified Search
Wait For	wait.for	Wait For
Windows	windows.list, windows.focus, windows.get, windows.close, windows.minimize, windows.maximize, windows.move_resize, windows.tile, windows.activate_or_launch	Windows
Workspaces	workspaces.list, workspaces.switch	Workspaces

Protocol

• Overview — JSON protocol fundamentals, dispatch rules, error codes
• Events — real-time event subscription and event types
• MCP Integration — Model Context Protocol server setup and tool map

Integrations

• Python Client — Python library with sync and async APIs
• AI Agents — Claude Desktop, Cursor, and MCP client configuration

Development

Document	Description
Architecture	System design, data flow, backend abstraction

API Reference

Document	Description
API.md	All actions and parameters
Protocol.md	Protocol implementation, action table, permissions
Backends.md	Backend provider details

Supported Desktops

Desktop	Session	Status	Backend
GNOME 46–50	Wayland/X11	Supported	MPRIS/Shell RemoteDesktop + Shell Extension
Hyprland	Wayland	Supported	hyprctl + ydotool + grim + wlr-randr
KDE Plasma	Wayland	Supported	KWin D-Bus + ydotool + spectacle
Sway	Wayland	Supported	swaymsg + ydotool + grim + wlr-randr
Niri	Wayland	Partial	niri IPC + ydotool + grim
Wayfire	Wayland	Partial	wf-ipc + ydotool + grim + wlr-randr
Labwc	Wayland	Supported	wlrctl + wdotool + grim + wlr-randr
COSMIC	Wayland	Partial	cosmic-helper + cosmic-randr + ydotool + grim
Cinnamon / MATE / XFCE	X11	Supported	xdotool + wmctrl + xclip + import

Auth / Permission Rules

• Elevated/system-mutating system.* actions require authorization through the Dashboard / confirmation UI by default.
• Safer path is via confirm.challenge / confirm.resolve rather than bypassing confirmation on the socket.
• Safe path = follow dashboard/confirm flow first.

Quick Links

• Installation: installation.md
• Quick Start: quick-start.md
• Protocol Overview: protocol/overview.md
• Events: protocol/events.md
• MCP: protocol/mcp.md
• Python Client: integrations/python.md
• AI Agents: integrations/agents.md
• Architecture: ../ARCHITECTURE.md
• API Reference: ../API.md
• Backends: ../BACKENDS.md
• v1.0.0 Release Notes: ../deskbrid-v1.0.0.md

Web Dashboard

Access the dashboard at http://localhost:20129. It provides live system information and interaction surface for the agentic loop.

Repository

• Source: src/
• CI: .github/workflows/
• Install script: install.sh
• Distributions: Docker images for Debian 13 / Bookworm and Ubuntu 25.04.