the five-minute setup · eli5 · for everybody

Set up qUltraKotoro & SOTA.app

No terminal wizardry. Ten taps and one paste. Everything runs on your device — on macOS it drives Osaurus, on iPhone it leans on Apple Intelligence, and you can drop in any model from HuggingFace. Let's go.

On your Mac

Osaurus is the local engine. The app finds it automatically — you just have to start it once.

1

Install Osaurus (first-class)

The app speaks Osaurus natively — nothing to configure after this.

brew install --cask osaurus
osaurus serve --supervise
first-class supportOsaurus serves an OpenAI-style API on http://127.0.0.1:1337. qUltraKotoro and SOTA.app point there out of the box — loopback needs no key.
2

Drop in a custom model from HuggingFace

Paste a repo id (or search in the app). It downloads once, then lives offline.

mlx-community/Qwen2.5-7B-Instruct-4bit
unsloth/Qwen2.5-3B-Instruct-GGUF
custom modelsAnything Osaurus can host — MLX, GGUF, your own quant — appears in the model picker. No account, no cloud.
3

Allow the microphone (once)

System Settings → Privacy & Security → Microphone → switch the app on. That's the only permission dictation needs.

privacyNo network permission is requested at all — the offline gate in CI makes sure the app can't phone home.
4

Add the Shortcut

Open Shortcuts → New → Dictate → Kotoro → Transcribe. Name it “Kotoro”, bind ⌃⌥K. Done — a global hotkey that types for you.

5

Turn on the emotional QuantTern code

SOTA.app → Settings → Emotion code = on. Every take now carries a qt: tag you can search by mood.

On your iPhone or iPad

Apple Intelligence does the local heavy lifting; the app adds the emotional code and the offline engine.

1

Turn on Apple Intelligence

Settings → Apple Intelligence & Siri → toggle Apple Intelligence on. (iPhone 15 Pro / 16+, or any M-series iPad.)

first-class apple intelligenceOn supported devices the app uses the on-device model for language understanding — no add-on, no key.
2

Let it hear you

Settings → Privacy & Security → Microphone (and Speech Recognition) → turn the app on.

3

Add the one-tap Shortcut

Shortcuts → ＋ → Kotoro → Start Recording. Add it to your Home Screen or the Action Button. One tap, talk, it's transcribed.

4

Flip on Offline Mode

App → Settings → Offline = on. Airplane mode? Still works. That's the whole point.

offline-first, e2eEvery feature is exercised with the network off in the test suite. If it needs the internet, it isn't shipped.

Connect it to the rest

Optional, and each one keeps the offline guarantee intact.

·

Portail gateway

Want a shared fleet model too? Point the app at your Portail endpoint — it stays a local-first fallback.

·

iCloud sync

Your history syncs as ciphertext via your own iCloud. No account on our side — ever.

·

HuggingFace in-app

Search the Hub, pick a model, download it. Custom models are first-class.

If something's stuck

Osaurus isn't answering

Run osaurus version. If it's missing, link it: ln -sf "/Applications/Osaurus.app/Contents/MacOS/osaurus" "$(brew --prefix)/bin/osaurus". Then osaurus serve --supervise again.

The mic never gets a level

Settings → Privacy → Microphone. Toggle the app off and on again, then relaunch. macOS sometimes hides the prompt after a first “no”.

Apple Intelligence is greyed out

It needs a supported device (iPhone 15 Pro+, M-series iPad) and it downloads its model once on Wi-Fi. Wait for “Ready”, then reopen the app.

I don't want a model download at all

Use the built-in tiny engine. Free tier caps a take at one minute — plenty for a note or a shopping list.