Skip to content
The world does revolve around you.

Pairing the iOS app#

The iOS app is the Ostler app on your iPhone. It is paired to one Hub – the Mac that runs your knowledge graph – and reaches it over your local Wi-Fi or over Tailscale when you are out and about.

This page covers pairing the iOS app the first time, what changes when you are off your home network, and what the iOS app can and cannot do when the Hub is asleep.

Before you start#

You need:

  1. A Hub that is up and running. The Doctor dashboard at http://localhost:8089/doctor should show all services healthy. If it does not, fix the Hub first – the iOS app is just a remote view of it.
  2. The iOS app installed on your iPhone. Available from the App Store.
  3. Both devices on the same trusted network for the first pair. Home Wi-Fi or a Tailscale network you own are the safe paths. Public Wi-Fi (coffee shop, hotel, conference) often blocks devices from reaching each other; the rare public network that does not also exposes the one-time pair code to anyone else on it. The Hub is reachable from your phone over your LAN.
  4. (Recommended) Tailscale on the Hub. This is what lets the iOS app reach the Hub from anywhere – the office, a coffee shop, a hotel. The Hub installer offered to set this up; if you skipped it, see adding Tailscale later below.

Pairing on the same Wi-Fi#

This is the path you will use the first time you launch the iOS app at home. In v1.0 the iOS app drives pairing as a guided five-step flow – there is no plain hub-URL text-field anywhere in the app. The iOS app learns the Hub's address from the QR code itself.

1. Generate a QR code on the Hub#

Open the Doctor dashboard on your Hub Mac:

http://localhost:8089/doctor

The Pair iOS device panel shows a one-time QR code. The QR encodes everything the iOS app needs to find the Hub and prove it is talking to the right one:

  • The Hub's LAN address (your Mac's 192.168.1.x IP).
  • The Hub's Tailscale address if you set Tailscale up at install.
  • A short-lived pairing token (rotates if you walk away).
  • The cryptographic material that pins the iOS app to your specific Hub.

The iOS app API binds to port 8089 on the Hub – you do not need to open it in any firewall, your home router treats both devices as on the same network.

2. Walk through the iOS app's pairing flow#

On first launch, the iOS app drops you into a five-step pairing flow. There is no point in the flow where you are asked to type in a hub URL – the QR carries the address.

  1. Welcome. A short explanation of what you are about to do. Tap Pair with your Hub to begin. (If you opened the iOS app just to look around and your Hub is not reachable yet, Not now in Settings preserves a partial setup; onboarding mode hides the skip because a fresh iOS app has nothing to do without a Hub.)
  2. Scan the QR. Camera view. Point your phone at the QR on the Doctor dashboard. The iOS app handles the rest as soon as the camera sees a valid payload.
  3. Pairing in progress. A spinner with the Hub's address shown for visual confirmation. The iOS app exchanges keys with the Hub over the LAN, pins the Hub's TLS certificate, and stores the paired-device record. This step takes a few seconds.
  4. Success. The Hub confirms the pair, you see the Hub name and a tick. Tap Done to land on the iOS app home screen.
  5. Error. If anything goes wrong (token expired, network blip, wrong Hub) the flow shows a clear message and a Retry button that drops you back to the welcome step rather than leaving you in a half-paired state.

Today, the QR is the only pairing path on the Doctor dashboard. Camera access is required on the iPhone you intend to pair – if you previously denied camera permission to the iOS app, grant it in iOS Settings > Ostler > Camera before launching.

3. The first sync#

After pairing, the iOS app downloads a manifest from the Hub – the list of people, recent timeline events, and conversation threads it should know about. Your phone is not copying your full knowledge graph. Most queries continue to round-trip to the Hub; the iOS app just caches enough to feel snappy and to work offline for a minute or two if your network blips.

The first sync takes thirty seconds to a minute on a normal-sized library. After that, syncs are incremental and barely noticeable.

If your Hub is a MacBook that travels with you, or if you ever want to reach it from outside your home Wi-Fi, you need Tailscale.

At v1.0 the Hub installer treats Tailscale as a dedicated "Connect your iPhone & Watch" step rather than a quiet line in the log; the screen explains why Tailscale matters and offers to install it inline. If you said yes there, you are already done – your Tailscale IP is in ~/.ostler/config/.env and the QR code on the Doctor dashboard already includes it.

If you said no at install time, you can add it later. See adding Tailscale later below.

On the iOS app, install Tailscale on your iPhone too (free for personal use), sign in with the same account, and the iPhone gets its own 100.x.y.z address on the same private network. The iOS app now reaches the Hub at the Tailscale address whether you are home, at the office, or on a different continent.

The Hub never has a public address. Nothing is exposed to the internet. The connection is end-to-end encrypted by Tailscale.

What the iOS app can do#

The iOS app is a thin client. The Hub does all the work.

  • Search. Look up a person, a meeting, an email, a place. The query runs on the Hub; the iOS app shows results.
  • Timeline. Scroll your life chronologically. Today, yesterday, last week, two years ago.
  • People. Open a person's page – what you have talked about, when you last met, shared timeline.
  • Quick capture. Snap a photo, paste a URL, jot a note. Queues to the Hub for processing.
  • Suggestions. "You haven't spoken to your mum in three weeks." "James's birthday is on Friday."
  • Status. Live indicator – Hub is online, catching up, or offline.

What the iOS app cannot do#

By design, the iOS app is not a replacement for the Hub.

  • It does not hold a copy of your full knowledge graph.
  • It does not run the AI model. Conversation goes through the Hub.
  • It does not export, upload, or sync any data outside your private Tailscale network.
  • It does not authenticate to third-party APIs (Gmail, WhatsApp, etc.). Those credentials live on the Hub.

If your Hub is offline (sleeping, off-network, powered down), the iOS app shows a clear Offline badge and falls back to whatever it has cached. Quick captures queue locally and send to the Hub the moment it is reachable again.

When your Hub sleeps#

The Hub can sleep – you closed your MacBook, the Mac Mini lost power, you took the laptop on a trip and the AC adapter is in the office.

Three things happen:

  1. The iOS app's status indicator changes from green (Online) to amber (Catching up) to red (Offline) over a minute or so as keepalives time out.
  2. New captures from the iOS app queue locally on the phone.
  3. Active queries fall back to whatever local cache the iOS app has – which is enough for "who is this", "when did I last see them", and the most recent timeline page, but not enough for novel questions that need the Hub's AI to reason over your data.

When the Hub comes back, the queue drains in seconds and the cache refreshes silently.

Adding Tailscale later#

If you skipped Tailscale at install time, here is how to retrofit it.

On the Hub#

# Install Tailscale
brew install --cask tailscale

# Open the app and sign in (Apple, Google, or Microsoft)
open -a Tailscale

# Once signed in, find your Tailscale address
tailscale ip --4

That prints something like 100.96.7.31. Add it to your config:

# Edit ~/.ostler/config/.env and set:
OSTLER_TAILSCALE_IP="100.96.7.31"

The Doctor dashboard will pick up the new value and start including the Tailscale address in the next QR code it generates.

On the iOS app#

Install the Tailscale iOS app from the App Store, sign in with the same account, and re-pair Ostler on your iPhone (Settings > Re-pair Hub) so it picks up the new Tailscale address.

Pairing more than one device#

You can pair as many phones, tablets, and (eventually) Watches as you like to one Hub. Each pair shows up as a row in the Doctor dashboard's Paired devices panel. You can revoke any pairing from there at any time – the iOS app immediately loses access and shows a "this device has been unpaired" screen.

There is no per-device sync conflict to worry about. The iOS app is a window onto the Hub; the Hub is the source of truth.

Re-pairing#

If you reset your phone, get a new phone, or want to start fresh:

  1. On the Hub, open the Doctor dashboard and revoke the old pairing.
  2. On the new device, install the iOS app and follow the QR / pair code flow as above.

The new pair is independent of the old one. Nothing is lost.

Troubleshooting#

The iOS app says 'Hub not reachable'.

Three things to check, in order:

  1. Is the Hub awake and on the same network? Open the Doctor dashboard locally on the Hub Mac at http://localhost:8089/doctor. If that does not load, the Hub services are not running – fix that first.
  2. Are you on the same Wi-Fi as the Hub? Some guest networks block client-to-client traffic; the iOS app cannot see the Hub on those.
  3. If you are remote, do you have Tailscale running on both ends? The Tailscale apps must be on, not just installed.
QR scanning is failing.

Make sure the Doctor dashboard is showing a fresh QR – the pairing token rotates every ten minutes. Click Generate new pair code on the Doctor panel to refresh, then try scanning again.

I see 'pair token expired' in the iOS app.

The pair-code flow uses a short-lived token to keep the pairing handshake from being replayable. Generate a new token on the Doctor dashboard and try again.

I want to use the iOS app on a public Wi-Fi without Tailscale.

Don't. The iOS app-to-Hub link assumes a trusted network. Tailscale is the trusted network when your home Wi-Fi is not. Public Wi-Fi without Tailscale will either fail to connect (most likely) or expose traffic patterns we would rather not expose.

Apple Watch#

The iOS app ships with a watchOS app at v1.0. It pairs through Ostler on your iPhone automatically – there is no separate Watch pairing flow. Once your iPhone is paired to the Hub, the Watch app becomes available and shows two complications you can pin to a watch face:

  • Hub Status (corner / circular) – a single dot for whether the Hub is online, catching up, or offline.
  • Next Meeting (rectangular) – the next item from your calendar, lock-screen safe (no attendee names by default; see widgets for the privacy toggle).

The Watch app itself is glanceable today.

Today, a second Mac on your LAN can already open the Doctor dashboard, the wiki, and the Hub APIs in Safari. One Hub per person is the design.

See the changelog for what shipped and when.

Next#