Skip to content
The world does revolve around you.

Installation#

Ostler is a local-first personal AI assistant. The Hub runs on your Mac. This page covers everything you need to know to get the Hub installed and healthy at v1.0.

The first run after install is documented separately on first run. Pairing the iOS app is on pairing the iOS app. If you need the long-form version of the platform-export questions, see data exports.

TL;DR#

  1. Buy the Hub at ostler.ai/pricing.
  2. The welcome email links to the signed v1.0 disk image (OstlerInstaller.dmg) and includes a download link for your licence file (ostler-licence.json). The same licence is also available on the welcome page after checkout.
  3. Open the DMG, drag OstlerInstaller to Applications, double-click to launch.
  4. The installer asks for your licence file first (drag the JSON onto the drop zone, or paste the Stripe session ID from your receipt).
  5. After licence verification, the installer asks for permission once via the macOS admin dialog, then runs a guided 15-question setup, then completes the install unattended.

The installer is code-signed, notarised by Apple, and runs entirely on your Mac. Nothing leaves your machine during install.

v1.0 first launch is not blank

During Phase 3 the installer mines the historical depth of your existing macOS data – iMessage, WhatsApp (if you opt in), Safari, Chrome, Apple Mail, Notes, Calendar, Photos events – not just the live present. The wiki, the life timeline, and the assistant are already populated with your context the moment the installer finishes. See first run – pick which Mac sources to learn from for the source list and depth notes.

What you need#

Requirement Detail
macOS 13 (Ventura) or later. Sequoia is the version we test against.
Mac Apple Silicon (M1 or later). Intel Macs are not supported at v1.0.
RAM 24 GB recommended. 16 GB runs the compact assistant (reliable, accurate, sub-second on short questions); 24 GB runs the standard 9-billion-parameter assistant; 32 GB and above runs the larger mixture-of-experts model. 8 GB is not enough.
Disk At least 35 GB free. Docker images, the AI model, the embedding model, and your data.
Power Plugged into AC for the install. Phase 3 is ten to fifteen minutes of continuous Docker pulls and AI model downloads. On a MacBook the Hub power policy can pause those mid-install if you are on battery.
Internet Needed for the install only. After setup, Ostler runs offline.

MacBook owners

A MacBook is a perfectly valid Hub. The installer wires in a power policy that pauses Docker and Ollama on battery and brings them back when you plug in. Your battery life is roughly what it was before Ostler. Mac Mini and Mac Studio owners get always-on by default and never see a transition.

Before you start#

  1. Plug in. Do not start on battery.
  2. Enable FileVault if it is not already on. System Settings > Privacy & Security > FileVault. Without it, anyone with physical access to your Mac can read your data even if Ostler's own database encryption is on.
  3. Add Gmail / iCloud / Outlook to Apple Mail if you want their content imported. System Settings > Internet Accounts > add your account > tick Mail. Apple handles authentication; Ostler reads from the local Mail store. No Google OAuth, no IMAP password held by Ostler.
  4. Add your calendars to Apple Calendar in the same way (System Settings > Internet Accounts). Ostler reads them all together via the local store.

The Mail and Calendar trick is deliberate – Ostler reads everything from one place rather than hold credentials for half a dozen separate cloud APIs. See Apple Mail FDA vs Google OAuth for the rationale.

Opening the disk image#

When you double-click OstlerInstaller.dmg, macOS mounts a volume named Install Ostler. It contains a single application:

Install Ostler/
  OstlerInstaller.app

Drag OstlerInstaller.app onto the Applications folder shortcut shown in the window. Eject the Install Ostler volume when you are done.

The first time you launch OstlerInstaller.app from Applications, macOS Gatekeeper checks the notarisation ticket and asks you to confirm you want to open an app downloaded from the internet. The signing identity is Developer ID Application: Creative Machines – you can verify this in the dialog. Click Open.

What the installer does#

The flow is structured into four phases.

Phase 1 – Licence + admin authorisation (~10 seconds)#

The first screen has two paths:

  • Drag and drop your licence file. Drop ostler-licence.json onto the drop zone in the centre of the window. The installer verifies the signature against the embedded production public key before continuing.
  • Paste a licence or Stripe session ID. If you do not have the JSON file to hand, paste either the licence content or the cs_... Stripe Checkout session ID from your receipt. The installer fetches the licence from the Ostler licence server using that session ID. Raw licence IDs (anything that is not a cs_ session reference and is not the signed JSON) get a friendly error message pointing you back to the welcome email.

Once the licence is verified, the installer asks once for your Mac password via a standard macOS admin authorisation dialog. This is the only password prompt during the install. Behind that single authorisation, the installer:

  • Pre-creates the Homebrew install location at /opt/homebrew (so Homebrew can later install without re-prompting).
  • Spawns caffeinate to keep your Mac awake for the unattended phase.
  • Sets up ~/.ostler/ ownership so the rest of the install runs without sudo.

If anything goes wrong here, you get a clear failure banner with a Email support button that opens a pre-filled mailto:[email protected] message containing a PII-redacted summary of the log. A separate Copy log (raw) option is available behind a confirmation modal if you would prefer to send the raw, un-redacted log yourself – it is gated because the raw log may contain machine-specific identifiers.

Phase 2 – The 15-question guided setup (~3 minutes)#

The installer walks you through 15 short questions, one per screen. Each screen shows Question X of 15 at the top, a labelled control (text field, picker, or checkbox group) in the middle, and a sidebar on the left with tick markers for the steps you have already finished. You can tap Back to revise any answer.

# Question Notes
1 macOS permissions (Contacts, Desktop, Downloads, Documents) The TCC dialogs fire here. Granting them lets the installer pre-fill later questions from your contact card and find any platform exports already in your Downloads / Documents folders.
2 Your full name Pre-filled from your macOS contact card.
3 What your assistant should call you Pre-filled from your first name.
4 Country code Pre-filled from your contact card. Used to normalise phone numbers across your data.
5 Timezone Pre-filled from macOS.
6 A name for your AI assistant A few starter ideas plus an open text field. Pick one, or type your own. See first run for guidance on what to avoid.
7 Passphrase Encrypts your databases. Minimum 16 characters or four words.
8 Confirm passphrase Type it again.
9 Email channel (optional) Whether the assistant should reach you via email, and the address to use.
10 iMessage channel (optional) Whether the assistant should reach you via iMessage.
11 WhatsApp channel (optional) Whether to wire up WhatsApp Web. Links out to data exports for the WhatsApp export instructions and explains the WhatsApp Web caveat.
12 Platform exports already downloaded Asks whether you have any platform exports (Twitter / X, Facebook, Instagram, LinkedIn, Google Takeout, etc.) sitting in ~/Downloads. Links out to data exports for the per-platform request instructions.
13 FDA source preset Choose Recommended (Safari, Notes, Calendar, Reminders), Everything (the above + iMessage, WhatsApp, Apple Mail, browser history from Safari + Chrome, Photos events), or Customise to pick each source individually. Each opted-in source is mined to its full historical depth, not just the live present.
14 Third-party data acknowledgement A short notice that the data you are about to import contains other people's words (their iMessages to you, their emails, their WhatsApp messages). It explains that you are solely responsible for processing this third-party data on your machine, and asks you to confirm.
15 Consent + start install Final recap of what is about to happen. You confirm by tapping Start; anything else cancels cleanly. Nothing has been installed at this point.

After Question 15 you can walk away.

Phase 3 – Unattended install (~10 to 25 minutes depending on broadband)#

The installer runs under OSTLER_GUI=1 and does the rest sudo-free:

  1. Installs Homebrew if missing (into the pre-created /opt/homebrew).
  2. Installs Colima + the Docker CLI (lightweight, no Docker Desktop, no account signup). Falls back to Docker Desktop if Colima cannot start.
  3. Installs Ollama (the local AI engine).
  4. Installs Python 3.12 via Homebrew if your system Python is too old.
  5. Saves your config to ~/.ostler/config/.env.
  6. Sets up database encryption using your passphrase. Generates a recovery key.
  7. Extracts data from the macOS sources you opted into in Q13 (the "instant onboarding" step – meaningful results in minutes, not days). At v1.0 this mines the historical depth of each source, not just recent items: iMessage chat.db, WhatsApp ChatStorage.sqlite (three-tier classifier so noisy big groups are skipped), Safari and Chrome history, and Apple Mail mboxes via pwg-email-ingest.
  8. Starts the Docker services that store your knowledge graph: a vector database (Qdrant on 127.0.0.1:6333), an RDF triplestore (Oxigraph on 127.0.0.1:7878), and Redis (127.0.0.1:6379). All three bind to localhost only.
  9. Pulls the AI model that fits your RAM (selected automatically; see first run – AI model selection).
  10. Sets up the import pipeline (the part that reads platform exports).
  11. Runs the platform-export import if you pointed it at any in Q12.
  12. Installs the ostler-import, ostler-fda, and ostler-uninstall commands into ~/.ostler/bin, and a launchd job that scans ~/Downloads for new exports every four hours.
  13. Sets up Ostler Doctor – the local diagnostic dashboard at http://localhost:8089/doctor.
  14. Installs the Hub power policy (the LaunchAgent that pauses Docker / Ollama on battery for MacBook Hubs).
  15. Bundles the third-party attribution catalogue.
  16. Connect your iPhone & Watch. A dedicated step that explains why Tailscale matters – it is what lets the iOS app and Apple Watch reach the Hub from outside your home Wi-Fi – and offers to install it inline. Free for personal use; encrypted; nothing public. You can skip and add later. See pairing the iOS app for the iPhone side.
  17. Bundles the Ostler Hub desktop app (Ostler.app, the Tauri-based control panel) into /Applications from the resources directory of the installer bundle.

Phase 4 – Health check + recovery key#

The installer pings each service. If anything is unhappy, you see a yellow warning rather than a green pass.

Then it shows your recovery key on a dedicated screen. The screen has three capture options side by side:

  • Copy to Keychain – saves it into your macOS Keychain alongside the passphrase.
  • Save as PDF – generates a PDF you can store wherever you keep your other important documents.
  • Print – produces a single-page printout.

Take at least one. Without your passphrase and your recovery key, your data cannot be recovered – not by you, not by us. That is the point. v1.0 is passphrase-primary: the passphrase decrypts your databases on every Hub start; the recovery key is the fallback if you ever lose the passphrase.

Storage layout#

After install, your machine has two distinct Ostler trees:

Path What it is
~/Documents/Ostler/ The visible zone. Markdown for your conversations, AI-assistant chats, summaries, todos, and the wiki. Reaches Spotlight, Time Machine, and iCloud Drive. Open it in Obsidian if you like.
~/.ostler/ The engine zone. Config, encrypted databases, logs, the ostler-* binaries on your PATH, the import watcher's intake folder. Not user-facing.

Inside ~/.ostler/:

Path What it is
~/.ostler/config/.env Your config. Editable.
~/.ostler/data/ Database files (Qdrant + Oxigraph + Redis + SQLCipher).
~/.ostler/logs/ Service logs.
~/.ostler/bin/ The ostler-* commands. Added to your PATH via ~/.zshrc.
~/.ostler/imports/ Auto-exported contacts and FDA-extracted data.
~/.ostler/backups/ A backup vCard of your contacts, taken before any import touches them.
~/.ostler/THIRD_PARTY_NOTICES.md Attribution for every open-source component shipped.

The ostler-uninstall command removes everything cleanly.

What macOS will ask for#

The installer requests permissions in two places:

At Question 1, the macOS Transparency, Consent, and Control (TCC) system shows up to four dialogs in sequence:

  1. Contacts. Reads your name (to pre-fill setup) and exports your contacts to ~/.ostler/imports/icloud-contacts.vcf for the knowledge graph. A backup copy is saved to ~/.ostler/backups/ before anything else touches it.
  2. Desktop folder access. Lets the installer scan ~/Desktop for any platform exports you have already downloaded.
  3. Downloads folder access. Lets the installer scan ~/Downloads for any platform exports.
  4. Documents folder access. Lets the installer scan ~/Documents for any platform exports.

If the Q1 dialogs do not appear, see troubleshooting.

Full Disk Access (FDA) for Safari history, iMessage, Apple Notes, Calendar, Photos events, Reminders, and Apple Mail is requested later in Phase 3 if you opted into any of those sources at Q13. Granting FDA requires you to drag Terminal (or your terminal app of choice) into System Settings > Privacy & Security > Full Disk Access. The installer pauses and walks you through this when it gets there.

You can grant FDA later and re-run the extraction with ostler-fda. The installer also schedules a one-shot re-run twelve hours after install to catch slow iCloud syncs.

Optional environment variables#

These can be set in front of the installer command (e.g. WIKI_OBSIDIAN_DIR=~/Vault open OstlerInstaller.app). All of them have sensible defaults.

Variable Effect
WIKI_OBSIDIAN_DIR Mirror the personal wiki into an Obsidian vault. Empty = disabled.
OLLAMA_HEADLINE_MODEL The model used for short fact headlines in the wiki compiler. Default qwen3:8b.
POWER_POLICY Hub power policy on MacBooks: normal, aggressive, or eco. Lives in ~/.ostler/power.conf after install.
PWG_PIPELINE_REPO Source repo for the import pipeline. Override for forks or pinned versions.
PWG_HUB_POWER_REPO Source repo for the Hub power scripts. Override for forks or pinned versions.

Advanced – internal repo override names

The PWG_* env-var names use the internal pipeline prefix. Stable for v1.0.

The full list of env vars is documented in reference > env vars.

What gets installed where#

The installer touches the following outside ~/.ostler/:

  • /Applications/Ostler.app – the Hub desktop control panel, copied from the installer bundle.
  • Homebrew – if not already installed. /opt/homebrew/.
  • Colima + the Docker CLI – via Homebrew.
  • Ollama – via Homebrew Cask. Auto-starts as a background service.
  • SQLCipher – via Homebrew. Required for encrypted SQLite.
  • Python 3.12 – via Homebrew, only if your system Python is below 3.10.
  • LaunchAgents in ~/Library/LaunchAgents/. Six files in the Ostler namespace. Removed cleanly by ostler-uninstall.
  • A PATH entry in ~/.zshrc (or ~/.bashrc / ~/.config/fish/config.fish depending on your shell).

It does not touch your existing Docker containers, Homebrew formulae, or Python virtual environments.

Re-running the installer#

The installer is re-run safe. If you run it again:

  • It detects your existing config and offers to re-use it.
  • It skips the 15 setup questions.
  • It skips the passphrase setup (your existing keychain is preserved).
  • It still re-checks every dependency and re-applies any defaults that have changed.

This is useful if a step failed mid-install, or if you have just upgraded the installer.

Common questions#

Do I need Docker Desktop?

No. The installer prefers Colima – a headless Docker runtime with no EULA, no account signup, and no system extension dialogs. Docker Desktop is supported as a fallback if Colima fails.

Why a passphrase as well as FileVault?

FileVault protects your data when the disk is at rest – stolen laptop, unattended Mac. A separate passphrase protects your databases when the disk is unlocked but you are not the one using the Mac. Defence in depth. See encryption.

What if I lose my passphrase?

Use your recovery key. If you have lost both, your data is gone. We hold neither. This is by design.

Can I move my install to a new Mac?

Yes, with the caveat that your licence permits up to three Macs per person via hardware fingerprinting. The data lives entirely under ~/.ostler/ and ~/Documents/Ostler/. Copy both directories to the new Mac (with FileVault on at both ends, ideally), run the installer on the new Mac, drop your licence file on the drop zone, and choose to keep the existing config when prompted.

Will this slow my Mac down?

The Docker services use about 4 GB of RAM at idle. The AI model only loads when you actually ask the assistant something. On a 24 GB Mac with normal use, you should not notice it.

I am running Ollama already.

The installer detects it and uses your existing install rather than installing its own. Same goes for Docker and Homebrew.

Can I install on Linux or Windows?

Ostler is macOS-only. The install path leans heavily on macOS-specific bits (Full Disk Access, Apple Mail's local store, Apple Calendar via CalDAV, the Contacts AppleScript bridge, launchd). Linux would need its own engineering effort.

What to do next#