Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
R

runst

> 编程语言
Open source

A dead simple notification daemon

351 stars0 likes0 views
WebsiteGitHub

About

A dead simple notification daemon

Desktop notifications are small, passive popup dialogs that notify the user of particular events in an asynchronous manner. These passive popups can automatically disappear after a short period of time.

runst is the server implementation of freedesktop.org - Desktop Notifications Specification and it can be used to receive notifications from applications via D-Bus. As of now, only X11 is supported.

Features

  • Fully customizable notification window (size, location, text, colors).
  • Template-powered (Jinja2/Django) notification text.
  • Auto-clear notifications based on a fixed time or estimated read time.
  • Run custom OS commands based on the matched notifications.
  • Z-Bus based notification backend (Rust IPC handling over the D-Bus protocol)

Roadmap

runst is initially designed to show a simple notification window. On top of that, it combines customization-oriented and semi-innovative features. In the future, I'm aiming to shape runst functionality based on new ideas and feedback.

Feel free to submit an issue if you have something in mind or having a problem!

Installation

From crates.io

runst can be installed from crates.io:

bash
$ cargo install runst

The minimum supported Rust version is 1.70.0.

Arch Linux

runst can be installed from the extra repository using pacman:

bash
$ pacman -S runst

Or you can install the available AUR packages with using an AUR helper. For example:

bash
$ paru -S runst-git

Alpine Linux

runst is available for Alpine Edge. It can be installed via apk after enabling the testing repository.

bash
apk add runst

Binary releases

See the available binaries for different operating systems/architectures from the releases page.

Release tarballs are signed with the following PGP key: AEF8C7261F4CEB41A448CBC41B250A9F78535D1A

Build from source

Prerequisites

  • Z-Bus
  • ZVariant
  • Pango

Instructions

  1. Clone the repository.
bash
$ git clone https://github.com/orhun/runst && cd runst/
  1. Build.
bash
$ CARGO_TARGET_DIR=target cargo build --release

Binary will be located at target/release/runst.

Usage

On Xorg startup

You can use xinitrc or xprofile for autostarting runst.

xinitrc

If you are starting Xorg manually with xinit, you can runst on X server startup via xinitrc:

$HOME/.xinitrc:

bash
runst &

Long-running programs such as notification daemons should be started before the window manager, so they should either fork themself or be run in the background via appending & sign. Otherwise, the script would halt and wait for each program to exit before executing the window manager or desktop environment.

In the case of runst not being available since it's started at a faster manner than the window manager, you can add a delay as shown in the example below:

bash
{ sleep 2; runst; } &

xprofile

If you are using a display manager, you can utilize an xprofile file which allows you to execute commands at the beginning of the X user session.

The xprofile file, which is ~/.xprofile or /etc/xprofile, can be styled similarly to xinitrc.

As a D-Bus service

Although runst now uses a Z-Bus backend internally, it still exposes the standard org.freedesktop.Notifications interface on the session D-Bus. In other words, Z-Bus handles the backend inside runst, while the activation mechanism is still D-Bus. Because of that, you can still use a regular D-Bus service file to launch runst automatically on the first notification action. For example, you can create the following service configuration:

/usr/share/dbus-1/services/org.orhun.runst.service:

ini
[D-BUS Service]
Name=org.freedesktop.Notifications
Exec=/usr/bin/runst

Whenever an application sends a notification by sending a signal to org.freedesktop.Notifications, D-Bus activates runst.

Also, see #1 for systemd integration.

Commands

runst can be controlled with sending commands to D-Bus via dbus-send(1).

bash
dbus-send --print-reply --dest=org.freedesktop.Notifications /org/freedesktop/Notifications/ctl "org.freedesktop.Notifications.${command}"

Available commands are:

  • History: show the last notification.
  • Close: close the notification.
  • CloseAll: close all the notifications.

For example:

bash
# show the last notification
dbus-send --print-reply \
          --dest=org.freedesktop.Notifications \
          /org/freedesktop/Notifications/ctl \
          org.freedesktop.Notifications.History

An example usage for i3:

bash
# Notification history
bindsym $mod+grave exec dbus-send --print-reply \
        --dest=org.freedesktop.Notifications /org/freedesktop/Notifications/ctl org.freedesktop.Notifications.History

# Close notification
bindsym $mod+shift+grave exec dbus-send --print-reply \
        --dest=org.freedesktop.Notifications /org/freedesktop/Notifications/ctl org.freedesktop.Notifications.Close

Additionally, to view the server version:

bash
dbus-send --print-reply --dest=org.freedesktop.Notifications /org/freedesktop/Notifications org.freedesktop.Notifications.GetServerInformation

Configuration

runst configuration file supports TOML format and the default configuration values can be found here.

If exists, configuration file is read from the following default locations:

  • $HOME/.config/runst/runst.toml
  • $HOME/.runst/runst.toml

You can also specify a path via RUNST_CONFIG environment variable.

Global configuration

log_verbosity

Sets the logging verbosity. Possible values are error, warn, info, debug and trace.

startup_notification

Shows a notification at startup if set to true.

geometry

Sets the window geometry. The value format is x++.

For setting this value, I recommend using a tool like slop which helps with querying for a selection and printing the region to stdout.

wrap_content

If set to true, the window is resized to match the contents.

If the content is larger than the window size, geometry option is used for maximum width and height.

font

Sets the font to use for the window.

template

Sets the template for the notification message. The syntax is based on Jinja2 and Django templates.

Simply, there are 3 kinds of delimiters:

  • {{ and }} for expressions
  • {% or {%- and %} or -%} for statements
  • {# and #} for comments

See Tera documentation for more information about control structures, built-in filters, etc.

Context

Context is the model that holds the required data for template rendering. The JSON format is used in the following example for the representation of a context.

json
{
  "app_name": "runst",
  "summary": "example",
  "body": "this is a notification ",
  "urgency": "normal",
  "unread_count": 1,
  "timestamp": 1672426610
}
Styling

Pango is used for text rendering. The markup documentation can be found here.

A few examples would be:

  • bold text: bold text
  • blue text: blue text
  • monospace text: monospace text

Urgency configuration

There are 3 levels of urgency defined in the Freedesktop specification and they define the importance of the notification.

  1. low: e.g. "joe signed on"
  2. normal: e.g. "you got mail"
  3. critical: e.g. "your computer is on fire!"

You can configure runst to act differently based on these urgency levels. For this, there need to be 3 different sections defined in the configuration file. Each of these sections has the following fields:

toml
[urgency_{level}] # urgency_low, urgency_normal or urgency_critical
    background = "#000000" # background color
    foreground = "#ffffff" # foreground color
    timeout = 10
    auto_clear = true
    text = "normal"
    custom_commands = []

timeout

This is the default timeout value (in seconds) if the notification has no timeout specified by the sender. If the timeout is 0, the notification is not automatically closed (i.e. it never expires).

auto_clear

If set to true, the estimated read time of the notification is calculated and it is used as the timeout. This is useful if you want the notifications to disappear as you finish reading them.

text

This is the custom text for the urgency level and can be used in template context as urgency. If it is not set, the corresponding urgency level is used (e.g. "low", "normal" or "critical").

custom_commands

With using this option, you can run custom OS commands based on urgency levels and the notification contents. The basic usage is the following:

toml
custom_commands = [
    { command = 'echo "{{app_name}} {{summary}} {{body}}"' } # echoes the notification to stdout
]

As shown in the example above, you can specify an arbitrary command via command which is also processed through the template engine. This means that you can use the same template context.

The filtering is done by matching the fields in JSON via using filter along with the command. For example, if you want to play a custom notification sound for a certain application:

toml
custom_commands = [
  { filter = '{ "app_name":"notify-send" }', command = 'aplay notification.wav' },
  { filter = '{ "app_name":"weechat" }', command = 'aplay irc.wav' }
]

The JSON filter can have the following fields:

  • app_name: Name of the application that sends the notification.
  • summary: Summary of the notification.
  • body: Body of the notification.

Each of these fields is matched using regex and you can combine them as follows:

toml
custom_commands = [
  { filter = '{ "app_name":"telegram|discord|.*chat$","body":"^hello.*" }', command = 'gotify push -t "{{app_name}}" "someone said hi!"' }
]

In this hypothetical example, we are sending a Gotify notification when someone says hi to us in any chatting application matched by the regex

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Rustdbusdbus-servicedesktop-notificationdesktop-notifications

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言