Install the Daemon

The daemon is one small program, pocketty. You need it for three things:

• Agent notifications. It watches herdr and sends a sealed alert when an agent is blocked or done.
• Code setup. It takes your phone’s key over Tailscale, after you type a code on the computer.
• Turn diffs. It saves the snapshots behind Last turn and Session in Review Changes.

For a plain SSH shell, you need nothing on the host.

What It Does and Does Not Do

• It runs as your user, and keeps its state in ~/.local/state/pocketty. It changes one other file: when you approve a code, it adds your phone’s key to ~/.ssh/authorized_keys.
• It opens one port, 7450, and only on the host’s Tailscale addresses. It also announces itself on the local network with Bonjour, for Nearby.
• It never edits your agents’ config files. It learns agent state from herdr.
• It does not keep terminal sessions. herdr does that.

The daemon needs herdr or Tailscale. With neither, it stops with an error.

Install

Use the install script or Homebrew, not both. Run either one on the computer, as your own user.

On macOS, both install the daemon as the app pocketty.app. macOS then tells you that pocketty can run in the background, and lists it in System Settings under Login Items.

With the Install Script

curl -fsSL https://pocketty.app/install.sh | sh

The script works on macOS and Linux, on Intel and ARM. It:

1. Downloads pocketty for your system and checks its SHA-256 sum. On Linux, it puts the binary in ~/.local/bin/pocketty. On macOS, it puts the app in ~/.local/share/pocketty/pocketty.app and links ~/.local/bin/pocketty to it.
2. Starts it as a service that runs as you: the launchd agent app.pocketty.daemon on macOS, or the systemd user service pocketty on Linux.
3. Tells you the line to add if your shell does not find pocketty yet. The App finds it either way: it looks on the PATH of a login shell, then in ~/.local/bin.

If the computer has neither herdr nor Tailscale, the script installs pocketty but does not start it. Install one of them, then run the script again.

You can read the script first at pocketty.app/install.sh.

With Homebrew

brew install lukeed/tap/pocketty
brew services start pocketty

brew services runs the daemon as you, with launchd on macOS or a systemd user service on Linux.

With mise

If you manage your tools with mise, it can install the same binary. Add this to ~/.config/mise/config.toml, then run mise install:

[tools."http:pocketty"]
version = "latest"
url = 'https://dl.pocketty.app/{{ version }}/pocketty-{{ arch(x64="x86_64", arm64="aarch64") }}-{{ os(macos="apple-darwin", linux="unknown-linux-musl") }}.tar.gz'
checksum_url = "https://dl.pocketty.app/{{ version }}/SHA256SUMS"
version_list_url = "https://dl.pocketty.app/latest"

mise installs only the binary:

• It does not run the daemon as a service. Run pocketty daemon with your own service manager.
• It does not restart the daemon after mise upgrade. Restart it yourself.
• The App looks for pocketty on the PATH of a login shell, then in ~/.local/bin. Put mise’s shims on your login PATH, for example in ~/.zprofile.
• mise checks the download against SHA256SUMS only when you lock your tools with mise lock.

For notifications with no extra setup, use the install script or Homebrew.

By Hand

If you would rather not pipe a script into sh, download and check the binary yourself.

On Linux:

v=$(curl -fsSL https://dl.pocketty.app/latest)
t=$(uname -m)-unknown-linux-musl
# Download pocketty for this computer
curl -fsSLO "https://dl.pocketty.app/$v/pocketty-$t.tar.gz"
# Check it against the published SHA-256 sums, then put the binary in ~/.local/bin
curl -fsSL "https://dl.pocketty.app/$v/SHA256SUMS" | grep " pocketty-$t.tar.gz$" | sha256sum -c && mkdir -p ~/.local/bin && tar -xzf "pocketty-$t.tar.gz" -C ~/.local/bin

Then run it as a systemd user service:

# Write the service file
mkdir -p ~/.config/systemd/user && cat > ~/.config/systemd/user/pocketty.service <<'EOF'
[Unit]
Description=pocketty host daemon

[Service]
ExecStart=%h/.local/bin/pocketty daemon
Restart=always
RestartSec=2

[Install]
WantedBy=default.target
EOF
# Start the daemon now and at each login
systemctl --user daemon-reload && systemctl --user enable --now pocketty

On macOS:

v=$(curl -fsSL https://dl.pocketty.app/latest)
t=$(uname -m | sed s/arm64/aarch64/)-apple-darwin
# Download pocketty for this Mac
curl -fsSLO "https://dl.pocketty.app/$v/pocketty-$t.tar.gz"
# Check it against the published SHA-256 sums, then put the app in ~/.local/share/pocketty
curl -fsSL "https://dl.pocketty.app/$v/SHA256SUMS" | grep " pocketty-$t.tar.gz$" | shasum -a 256 -c && mkdir -p ~/.local/share/pocketty ~/.local/bin && rm -rf ~/.local/share/pocketty/pocketty.app && tar -xzf "pocketty-$t.tar.gz" -C ~/.local/share/pocketty pocketty.app
# Link it from ~/.local/bin
ln -sf ~/.local/share/pocketty/pocketty.app/Contents/MacOS/pocketty ~/.local/bin/pocketty

To run it as a launchd agent, run the install script afterwards. It keeps your app when it is the latest version, and only adds the service.

Check It

pocketty status

state      /Users/luke/.local/state/pocketty
daemon key 3f9c…
devices    1
herdr      /opt/homebrew/bin/herdr
session    default (running)

devices counts the phones that get notifications from this host. It is 0 until the App pairs.

To check that the service runs:

# Install script on Linux
systemctl --user status pocketty
# Install script on macOS
launchctl print "gui/$(id -u)/app.pocketty.daemon" | grep state
# Homebrew
brew services info pocketty

Updates

• Install script: run the install command again. It downloads a new version only when there is one, and then restarts the service.
• Homebrew: run brew upgrade pocketty. The daemon sees the new version within 30 seconds, exits, and the service starts it.
• mise: run mise upgrade http:pocketty, then restart the daemon.

The App and the daemon never need matching versions. Update either one first. See Versions.

Remove It

With the install script:

curl -fsSL https://pocketty.app/install.sh | sh -s -- --uninstall

With Homebrew:

brew services stop pocketty
brew uninstall pocketty

With mise, stop the daemon, remove the http:pocketty entry from your config, and run mise prune.

The install script and Homebrew both stop the service and remove the binary. They keep ~/.local/state/pocketty. Delete that folder to forget the paired phones too.

The keys of your phones stay in ~/.ssh/authorized_keys. To remove a phone’s key too, see Remove a Phone.