Reliable systemd autostart for awatcher-bundle on GNOME/Wayland (with fix for RecvError crashes)

[schmunk42]

This took me months to figure out, but I finally have a working solution for automatic ActivityWatch startup on GNOME with Wayland using systemd I want to share with you. Note: I had help from an AI.

The Problem

The commonly suggested approaches don't work reliably on GNOME/Wayland:

1. XDG Autostart (.desktop files in ~/.config/autostart/) - Service starts too early, before GNOME's D-Bus services are ready
2. Existing systemd solutions - Lack proper timing, causing crashes with ERROR aw_datastore::worker] DB worker quitting, error: RecvError

The root cause is that awatcher-bundle watchers need:

• Mutter/IdleMonitor to be fully initialized
• GNOME D-Bus services to be available
• Proper display environment variables

When started too early at boot, the watchers fail to connect and the database worker crashes.

The Solution

Create ~/.config/systemd/user/activitywatch.service:

[Unit]
Description=ActivityWatch (awatcher-bundle) - Activity tracking service
Documentation=https://docs.activitywatch.net/
After=graphical-session.target
Wants=graphical-session.target

[Service]
Type=simple
ExecStartPre=/usr/bin/sleep 5
ExecStart=/usr/bin/awatcher-bundle -vv --no-tray
Restart=on-failure
RestartSec=10
KillMode=mixed
# Ensure the service has access to the display
Environment="DISPLAY=:0"
# For Wayland
Environment="WAYLAND_DISPLAY=wayland-0"
# XDG runtime directory
Environment="XDG_RUNTIME_DIR=/run/user/%U"

[Install]
WantedBy=default.target

Enable and start:

systemctl --user daemon-reload
systemctl --user enable activitywatch.service
systemctl --user start activitywatch.service

Key Differences from Other Solutions

Compared to existing solutions (like https://gist.github.com/guillermodotn/ec9ac40932b210d6216d17cc2d61c631):

1. 5-second delay (ExecStartPre=/usr/bin/sleep 5) - This is crucial! It gives GNOME time to fully initialize D-Bus and Mutter/IdleMonitor before watchers try to connect. Without this, the service crashes on boot with RecvError.

2. --no-tray flag - Runs server and watchers without the GUI tray icon. This avoids display initialization issues in systemd context and is more reliable for background operation. The web UI still works perfectly.

3. KillMode=mixed - Ensures proper cleanup when stopping the service.

4. Uses awatcher-bundle - Targets the modern Rust implementation instead of the older Python-based aw-qt.

Why This Matters

Without the 5-second delay, you get this error pattern on every boot:

[ERROR aw_datastore::worker] DB worker quitting, error: RecvError
systemd[3011]: activitywatch.service: Consumed 193ms CPU time

The service exits immediately and doesn't restart because it exits with status 0 (clean exit, not detected as failure).

Test Results

Tested successfully on:

• OS: Arch Linux
• Desktop: GNOME with Wayland
• Version: awatcher-bundle v0.13.1 (rust)
• systemd: 256.7

After reboot:

• ✅ Server runs automatically on http://127.0.0.1:5600/
• ✅ Idle watcher active (Gnome idle/Mutter/IdleMonitor)
• ✅ Window watcher active (Gnome window extension)
• ✅ Automatic restart on crashes
• ✅ No manual intervention required

Relation to Existing Issues

This addresses concerns from:

• #403 - Lack of systemd service files in release archives
• #116 - Autostart documentation needs

While maintainers prefer .desktop autostart files, systemd provides more reliability with proper service management, logging, and automatic crash recovery - especially important for GNOME/Wayland environments.

Suggestion

Consider adding this to the documentation for GNOME/Wayland users, particularly those using awatcher-bundle. The timing issue is critical and not documented anywhere else.

[github-actions[bot]]

Hi there! As you're new to this repo, please make sure you've used an appropriate issue template and searched for duplicates (it helps us focus on actual development!). We'd also like to suggest that you read our contribution guidelines and our code of conduct. Thanks a bunch for opening your first issue! 🙏

[ideadapt]

This is very helpful! Thanks a lot. Finally having a working autostart for activitywatch on Fedora with GNOME. After updating https://extensions.gnome.org/extension/5592/focused-window-d-bus/ it works as well on GNOME 49 :) . (The error message for a non working d-bus extension is the same RecvError).

[schmunk42]

Here a newer version addressing dbus issues: https://gist.github.com/schmunk42/fbbcdee420af674798e4d2fc32a62165

But it needs a script now.