How-to and FAQ

Connecting servers, reaching them away from home, backing up settings, and using widgets, Live Activities and Siri.

Add a service

1. Open More or Settings and choose Add service. You can also start from Discover on this network, or import a Homepage or Homarr config.
2. Pick the service type. The default port is filled in for you.
3. Enter the address you use on your network — usually a local hostname or LAN IP, or a VPN / Tailscale address when you’re away.
4. Add the API key or username and password that service expects. Keys are saved in the iOS Keychain, not in a Harbarr account.
5. Test the connection, then save. You can add more than one instance of the same type (for example Radarr 4K and Radarr HD).

Most *arr apps use an API key from Settings → General. qBittorrent, Transmission, Deluge, NZBGet, Flood, rTorrent, Glances and Docker use a username and password. Plex can sign in with a plex.tv PIN in Safari, or you can paste a token. Jellyfin and Emby use a media-browser token. Unraid uses a Connect API key; Portainer uses an API key; Tdarr, Seerr, Unpackerr and similar use the key those apps provide.

Default ports and a one-line description for every type are on the services page.

Remote access, VPN and Tailscale

Harbarr does not relay traffic through our servers. It opens a connection from your phone to the address you typed. At home, that’s usually a LAN address. When you’re out, use a VPN or Tailscale (or another overlay you already trust), then enter the address that path provides — for example a Tailscale magic DNS name or the VPN IP of the host.

You can keep two setups, one for home and one for away, and switch them in the app. Connection profiles can also choose a path automatically when you leave the LAN. Don’t expose API ports to the public internet just for Harbarr; a VPN is the better pattern.

iCloud backup

Turn on Sync with iCloud in Settings if you want setups, layouts and non-secret settings to follow your Apple ID. Keys go in iCloud Keychain, not in a file we can read. This is your personal iCloud, not a Harbarr cloud. If you prefer to stay off iCloud, leave it off — everything still lives on the device.

Export and import, including API keys

Settings → Data & Demo can export your configuration and import it again, for example on a new phone. By default the file has no API keys. Turn on Include API keys and set a password; keys are sealed with PBKDF2 and AES-GCM. Import asks for that password and writes keys back to the Keychain. A wrong password imports nothing. Keep the file somewhere you trust.

Widgets, Live Activities and the Dynamic Island

Add Harbarr widgets from the Home Screen or Lock Screen gallery. You can leave the setup picker empty to follow the setup you’re using in the app, or pin a widget to a specific setup. Coming Up, download speed or counts, and Host status are available in the families listed in the widget gallery.

Live Activities can start when downloads (or a Tdarr transcode) are running. They appear on the Lock Screen and in the Dynamic Island. Settings → Live Activities can turn them off, or show one again if you swiped it away. They currently update while Harbarr is open or refreshing in the background; a push relay is planned so they can move while the app is closed.

Siri and Shortcuts

Harbarr registers shortcuts such as “What’s downloading?”, “Pause all downloads”, “Resume all downloads”, “What’s on today?” and “Open <service>”. Pause and resume ask for confirmation. Spotlight can also index series and movie titles from your library cache (demo titles in demo mode).

FAQ