First run#

This page walks through the first time you launch the installer, from the moment the licence is verified to the moment the recovery key appears at the end. If you have not yet started the installer, see installation first.

What you will be asked#

The installer collects everything it needs up front so you can walk away during the long unattended phase. The 15 questions take about three minutes. Each screen shows Question X of 15 at the top and a sidebar on the left with tick markers for the steps you have already finished. Back is available on every screen except Question 15.

Q1 – macOS permissions#

Before any question is asked, the installer requests four permissions in sequence via macOS's standard Transparency, Consent, and Control (TCC) dialogs:

Contacts. Lets the installer read your name to pre-fill later questions.
Desktop folder access. Lets the installer scan ~/Desktop for any platform-export ZIPs you have already downloaded.
Downloads folder access. Lets the installer scan ~/Downloads.
Documents folder access. Lets the installer scan ~/Documents.

You can decline any of them. The Q12 platform-export search just has a smaller area to look in.

Q2 to Q5 – Confirming who you are#

The installer reads your macOS contact card to pre-fill your name, country, and phone number, then asks you to confirm each value. If you granted Contacts at Q1, the card was already read; if you declined, you type these in by hand.

A side effect of granting Contacts at Q1: your full address book is exported to ~/.ostler/imports/icloud-contacts.vcf so the knowledge graph can use it. A backup copy is also saved under ~/.ostler/backups/ before anything else touches your contacts, so a botched import never costs you data.

You will see four screens:

Q2 – Full name. Pre-filled from your contact card if available.
Q3 – What should your assistant call you? Pre-filled from your first name. This is the friendly identifier the assistant uses when talking to you.
Q4 – Country code. E.g. 44 for the UK, 1 for the US, 852 for Hong Kong. Used to normalise phone numbers so the same person across LinkedIn, WhatsApp, and your address book is recognised as one person.
Q5 – Timezone. Pre-filled from macOS. Used by morning briefs, daily summaries, and "stale contact" detection.

Q6 – Name your assistant#

Your assistant lives on your Mac. It manages your knowledge graph, answers questions about your own data, and reaches you through the messaging channels you set up later. The setup wizard suggests an assistant name. Pick anything you like.

A name is required – there is no default if you press Enter without typing one.

Q7 and Q8 – Set a passphrase#

Q7 takes the passphrase; Q8 asks you to confirm by typing it again. These two screens only run if your install does not already have one. The passphrase encrypts all your databases on disk. Your data is unreadable without it – not by you, not by us, not by anyone with physical access to the Mac.

This is the most important password you will set

A weak passphrase is a real risk. Ostler will hold every relationship, every conversation, and every pattern in your life. Pick something you will remember and that nobody else will guess.

The installer enforces a minimum length: 16 characters or four words. Sentences work well:

mango sunset river telescope
my cat hates the vacuum cleaner
coffee before nine or everything burns

After you confirm at Q8, the installer generates a recovery key and stores the passphrase via your Mac's standard secure storage. The recovery key appears at the end of the install. Without your passphrase and your recovery key, your data is gone forever. We cannot help. That is the design.

Q9, Q10, Q11 – Messaging channels#

The installer asks one question per channel. Each is optional and you can revisit any of them later from the Doctor dashboard.

Q9 – Email. Whether the assistant should reach you by email, and the address to use.
Q10 – iMessage. Whether the assistant should reach you via iMessage. The assistant uses your existing macOS Messages app; there is no separate Ostler account.
Q11 – WhatsApp. Whether the assistant should reach you via WhatsApp. Wires up WhatsApp Web; you scan a QR code in the Doctor dashboard later. The screen explains the WhatsApp Web caveat (unofficial protocol, your number is yours, banning risk) and links to data exports for the WhatsApp account-report instructions.

Q12 – Platform exports already downloaded#

The installer scans ~/Downloads, ~/Desktop, and ~/Documents (subject to the TCC permissions you granted at Q1) for recognisable export files: LinkedIn Connections.csv, Facebook friends.json, Instagram followers_and_following, Google Takeout zips and Gmail mboxes, Twitter / X tweet.js, and so on.

Anything found is shown in a list. You can confirm or skip the import.

If nothing is found, the screen points you at data exports – the long-form page that lists request URLs and typical wait times for every supported platform. You can run ostler-import later when the export emails arrive; the install does not need them.

Q13 – Pick which Mac sources to learn from#

This is the "instant onboarding" step. The installer can read directly from macOS apps that already hold your data – no GDPR export needed, no waiting for emails to arrive. Each source is opt-in.

Three presets, or pick each by hand:

Preset	What it includes
Recommended	Safari history + bookmarks, Apple Notes, Calendar, Reminders. Fast, privacy-friendly defaults. The pick if you are not sure.
Everything	The above + iMessage, WhatsApp, Apple Mail, browser history (Safari + Chrome), Photos events. Slower, more depth. Not Photos face recognition.
Customise	Pick each source individually. Best for users who already know which sources they want.

A few sources are off by default and require explicit opt-in:

iMessage, WhatsApp, and Apple Mail carry third-party content (other people's words). The installer's default position is "off, ask the user".
Photos face recognition is special-category data under GDPR Article 9. It is off by default and you have to tick it deliberately. If you do not understand what that means, leave it off.

You can change any of these later by editing OSTLER_FDA_SOURCES in ~/.ostler/config/.env and re-running ostler-fda. See reference > configuration.

If you have Gmail (or any other webmail account) attached to Apple Mail, Ostler reads it from the local Mail store via Full Disk Access – Google never sees that Ostler exists. See Apple Mail FDA vs Google OAuth for why this matters.

Historical depth, not just the live present

At v1.0 the installer mines the historical depth of each source you opt into, not just the most recent days:

iMessage – the full local chat.db, back to whenever you turned iMessage on.
WhatsApp – the local ChatStorage.sqlite, classified into three tiers: one-to-one chats are mined in full, intimate small groups are mined in full, and large noisy group chats are skipped so your graph stays signal-rich.
Browser history – Safari and Chrome history files.
Apple Mail – the local Mail mbox via pwg-email-ingest, subjects and senders by default; bodies only if you tick that source explicitly.

The result: when the installer finishes, the wiki, the timeline, and your assistant already have years of context. The first launch is not a blank canvas.

Q14 – Third-party data acknowledgement#

iMessage, Apple Mail, WhatsApp, and several platform exports carry the words of other people. The installer surfaces this with a short notice and asks you to confirm.

The framing on the screen is:

Some of the data you are about to import contains other people's words – the messages they sent you, the emails they wrote you, the WhatsApp conversations you have had together. You are solely responsible for processing this third-party data on your machine. Ostler is the tool; the responsibility is yours.

You confirm by ticking the box. The acknowledgement is recorded in ~/.ostler/posture/consent.json so it is auditable later.

Before Phase 3 starts, the installer recaps:

What it is about to install (Docker containers, Ollama, the AI model, the encryption module, the export watcher, your selected Mac sources, the Hub desktop app).
What it will import (your contacts, any platform exports you confirmed at Q12, your selected FDA sources from Q13).
That your personal data stays on the machine.
That you can remove everything at any time with ostler-uninstall.

You confirm by tapping Start install. Tapping the Cancel button instead exits cleanly. Nothing has been installed at this point.

What happens during the install#

You can walk away here. Phase 3 is unattended for ten to fifteen minutes. If your Mac sleeps you are fine – the installer disables sleep for the duration and restores your previous setting at uninstall.

A progress bar shows the step number, percent complete, and an ETA that gets more accurate as it goes. You will see lines like:

[████████████░░░░░░░░░░░░░░░░░] 40% (~6m remaining)
[info] Pulling qwen3.5:9b (~6.6 GB)... this may take a few minutes.
[ok]   Embedding model ready

What is being downloaded#

The big two are:

The AI model – the size depends on your RAM. See AI model selection below.
The embedding model – nomic-embed-text, around 274 MB.

Plus three small Docker images and a Python virtual environment. Around 6 to 25 GB total depending on which AI model you get.

AI model selection#

The installer picks a model based on the RAM available on your Mac. You do not get to choose, because the wrong choice on the wrong hardware is a bad first experience.

RAM	Model	Approximate size
48 GB or more	`qwen3.6:35b-a3b` (Mixture of Experts, 3B active parameters)	~23 GB
24 GB to 47 GB	`qwen3.5:9b`	~6.6 GB
16 GB to 23 GB	`gemma4:e2b`	~5 GB

The Qwen models are Apache 2.0 licensed. The Gemma fallback ships under Google's Gemma Terms of Use; the installer prints a warning before pulling it. You can change the model later via ollama pull <model> and an edit to ~/.ostler/config/.env.

Hub power policy#

If you are on a MacBook, step 3.14 installs a LaunchAgent that watches your AC / battery state and pauses Docker / Ollama on battery, then resumes them when you plug back in. This is what lets a MacBook be your Hub without destroying the battery. Mac Mini and Mac Studio installs see this LaunchAgent install but it never does anything – the watcher reports tier ac every tick and takes no action.

You can change the policy after install by editing ~/.ostler/power.conf:

POWER_POLICY=normal – default. Pauses on battery, resumes on AC.
POWER_POLICY=aggressive – pauses sooner, resumes only after a longer AC stretch.
POWER_POLICY=eco – minimal background activity, longest battery life.

Tailscale (connecting your iPhone & Watch)#

At v1.0 this is a dedicated full-screen step in the installer rather than a quiet line in the log. The screen explains why Tailscale matters – it is what lets your iPhone and Apple Watch reach the Hub from outside your home Wi-Fi – and offers to install it inline. Tailscale is a free-for-personal-use private network that gives this Mac a stable IP your phone can reach from anywhere; encrypted, no public exposure.

Without it, the iOS app only works on your home Wi-Fi.

If you say yes, the installer:

Installs the Tailscale Mac app (Homebrew Cask).
Opens it for you to sign in (Apple, Google, or Microsoft).
Reads your Tailscale IPv4 address and saves it to ~/.ostler/config/.env so the iOS app can find this Mac later.

You can skip this step and add Tailscale later. See pairing the iOS app for what changes when you do.

When the install finishes#

The installer prints a summary:

  Ostler is running!

  What was installed:
     User:          Alex Example (alex)
     Assistant:     Sarah
     Timezone:      Europe/London
     Country code:  +44
     AI model:      qwen3.5:9b
     FileVault:     Enabled
     Encryption:    Databases encrypted with passphrase
     Contacts:      1,267 exported from iCloud
     Instant data:  6 macOS source(s) extracted
     Duration:      12m 34s

Then – if you set a passphrase – the recovery key:

Last chance to capture this

The recovery key is shown once, on a dedicated screen with three capture options side-by-side:

Copy to Keychain – saves it into your macOS Keychain alongside the passphrase. Search "Ostler" in the Passwords app afterwards to find it.
Save as PDF – generates a PDF you can store wherever you store other important documents (a password manager attachment, an encrypted Notes vault, an encrypted disk image).
Print – produces a single-page printout. The classic "tuck it in the same drawer as your passport" answer.

Take at least one of them. If you decline all three, your recovery key is gone the moment you close the screen – and without it, plus the passphrase, your data is unrecoverable. Not by you. Not by us. Not by anyone.

At v1.0 the encryption posture is passphrase-primary: the passphrase decrypts your databases on every Hub start. The recovery key is the fallback if you ever forget that passphrase.

After the recovery key, you will see your dashboards, config paths, and what to do next. Read those – they are the clickable URLs you will use over the next few days.

Now what?#

Ostler is running. The Docker services are up. The AI model is loaded. Your selected Mac data has already been extracted to ~/.ostler/imports/fda/.

A few useful next steps:

Open your Doctor dashboard at http://localhost:8089/doctor. This is your local diagnostics panel – service health, what got imported, what is queued, and copy-paste fix commands if anything looks wrong.
Pair the iOS app if you want Ostler in your pocket. See pairing the iOS app.
Try the assistant. Pick something you can verify – "what was the last meeting I had with X?" or "find Y's phone number". See what to do next for a starter list.
Request your GDPR exports if you have not already. They take 1 to 3 days to arrive; the installer's export watcher will notify you when they land in ~/Downloads. See what to do next > request data exports.

If anything went red during the install, head to troubleshooting. The Doctor dashboard will probably already be telling you what to fix.

A note on patience#

At v1.0 the historical-ingest step has done a lot of the early work for you: the wiki, the timeline, and the assistant already have years of context from iMessage, WhatsApp, browser history, Apple Mail, Notes, Calendar, and the other sources you opted into. You can search and ask questions about your own past straight away.

The GDPR-import data takes longer because the platforms have not sent you the export yet. The deepest results, where the assistant starts noticing patterns across years of data and adds the platforms that live outside Apple's walled garden, take a few days of normal use to build up. That is normal. Ostler is meant to grow into your life, not impress you in five minutes.