Set up kudde.

Three steps, once kudde is on your phone: add a machine, place the phone key on it, and turn on alerts. Not installed yet? Start with Install.

Add a machine

In kudde, tap “Add machine” and enter the machine’s address, port and user.

Before you go on, compare the host key fingerprint kudde shows with the machine’s own. On the machine, this prints it:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

kudde remembers that host key, and a changed key stops the connection.

Place the phone key

kudde made a key for this phone in its secure hardware, and the key never leaves it. Tap “Add the phone key”, then Copy, and get the line to the machine. A note or a message to yourself works: the line is public.

On the machine, run this, paste the line, press Enter, then Ctrl-D:

mkdir -m 700 -p ~/.ssh && cat >> ~/.ssh/authorized_keys

The line lets the key run only herdr-core: no shell session, no forwarding. herdr-core can still run commands as that user, so treat the key like a shell login.

The first connection starts herdr-core, so the card may show “Unreachable” once before it connects.

Turn on alerts

kudde-push runs on the machine as a systemd user service. It watches herdr-core and sends an encrypted push when an agent needs you or finishes, through your ntfy server to the ntfy app on the phone.

On the machine

  1. From the latest release, download the kudde-push for your machine (uname -m names it: kudde-push-x86_64 or kudde-push-aarch64), its .sig and SHA256SUMS, and check them. Then install it:

    install -m 755 kudde-push-$(uname -m) ~/.local/bin/kudde-push
  2. Put an ntfy access token in ~/.config/kudde-push/ntfy-token (mode 600), for a dedicated ntfy user that may only write to up* topics, never read. On your own ntfy server, as its admin:

    ntfy user add kudde-push
    ntfy access kudde-push 'up*' write-only
    ntfy token add kudde-push

    On a server someone else runs, ask its admin for such a user and a token.

  3. Write ~/.config/kudde-push/config with the core to watch and the ntfy server pushes may go to:

    # find the socket with ls /run/user/$(id -u)/herdr-core/
    socket = /run/user/1000/herdr-core/default.sock
    allow = https://ntfy.example.org
  4. Install and start the service with the unit file from contrib/kudde-push.service:

    mkdir -p ~/.config/systemd/user
    curl -fsSL -o ~/.config/systemd/user/kudde-push.service \
      https://raw.githubusercontent.com/enhulsman/kudde/main/contrib/kudde-push.service
    systemctl --user daemon-reload
    systemctl --user enable --now kudde-push
    loginctl enable-linger "$USER"

    On WSL, systemd must be on.

On the phone

  1. Install the ntfy app and point it at your ntfy server. If the server denies anonymous access, sign in with a user that may read up* topics.
  2. In kudde, tap “Turn on” on the machine card’s Alerts row, and allow notifications.
  3. Tap “Send” on “Send test alert”. The row says “Test received” when the alert arrives.

“Finished” alerts are silent by default. To hear them, open Android settings, go to kudde’s notifications, open “Finished”, and set it to alerting.

The full kudde-push guide on GitHub

Curious how it stays safe?

Read about security