Set Up a Linux Host · pocketty docs

Set up a Linux computer or server for pocketty, from the SSH server to the pocketty CLI and your phone's key.

pocketty connects to Linux over plain SSH. You need a terminal on the host, on its own screen or over SSH from another computer. Do each step as your own user. pocketty signs in as you, not as root.

TIP

We recommend Tailscale on the host and on the phone. The host then gets one address that works on any network, with no port open to the internet. See Connect with Tailscale.

1. Start the SSH Server

Most servers have one already. To check:

systemctl status ssh sshd

Debian and Ubuntu call the service ssh. Fedora calls it sshd. If neither is found, install the SSH server and start it:

# Debian and Ubuntu
sudo apt install openssh-server
sudo systemctl enable --now ssh
# Fedora
sudo dnf install openssh-server
sudo systemctl enable --now sshd

If a firewall runs on the host, let SSH through. With ufw, run sudo ufw allow OpenSSH.

2. Find the Address

The phone needs an address it can reach:

With Tailscale: the host’s MagicDNS name, for example server.tail1234.ts.net. The Tailscale admin console shows it under Machines.
On your home network: a LAN address. hostname -I prints the host’s addresses.
A public server: its domain name or public IP address.

3. Install the pocketty CLI

The CLI runs the pocketty daemon. The daemon sends agent notifications from herdr, and it adds your phone’s key after you type a code. For a plain shell, you can skip this step. To install herdr itself, see herdr.dev.

Run the install script as your own user, not with sudo:

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

The script puts pocketty in ~/.local/bin and starts it as the systemd user service pocketty. For Homebrew, mise or an install by hand, see Install the Daemon.

A systemd user service stops when you log out. On a server, keep it running:

loginctl enable-linger "$USER"

Then check it:

pocketty status

The daemon needs herdr or Tailscale on the host. With neither, the script installs pocketty but does not start it.

4. Add the Host on Your Phone

Tap + on the host list, and type the Address from step 2. Then give the host your phone’s key, in one of these ways:

Connect with a Code, if the CLI and Tailscale run on the host.
Connect with a Setup Command, on any SSH server.
Connect with Tailscale, if Tailscale SSH is on for the host.

5. Connect

Tap the host. The dot next to its name turns green when pocketty is connected.

If herdr runs on the host, its workspaces show on the host screen. See herdr Panes.
With the CLI on the host, the phone pairs for notifications when it connects. pocketty devices then lists your phone. See Agent Notifications.

If It Does Not Connect

Check SSH from another computer first: ssh you@address.
Timeouts: check the address and the port. With Tailscale, check that it is up on both ends.
Sign-in refused: the host does not have your key. Do step 4 again.
Send key to host cannot reach the host: check that the daemon runs, with systemctl --user status pocketty. Its log is in journalctl --user -u pocketty -f.

See Troubleshooting for more.