Omi's one-line macOS install points at a cloud backend, and the local stack is a separate setup

The --yolo flag is the whole story of the quick start

One command puts a running macOS app on your desk, and what it connects to is the part worth reading twice:

git clone https://github.com/BasedHardware/omi.git && cd omi/desktop/macos && ./run.sh --yolo

That flag is the entire difference between this and a local build. The line builds the macOS app, connects to the cloud backend and launches, with no env files, no credentials and no local backend. The fastest route into Omi is therefore also the route where your screen captures and transcribed conversations leave the machine, handled by infrastructure this repository does not contain. Requirements are macOS 14+, Xcode (which brings Swift and code signing) and Node.js. Since code signing sits inside that requirement, a fresh clone signs with whatever identity the machine already carries, and no developer team or provisioning profile is named for a first install. Budget for that step rather than assuming a clean clone builds and signs unattended.

Copying backend/.env.example is what turns the client into a local stack

Everything the one-liner skips is in the full installation, starting with the two prerequisites you would otherwise inherit from Xcode:

xcode-select --install
uv --version

The backend config gets created by copying an example file into place, and that is the moment this stops being a cloud client:

git clone https://github.com/BasedHardware/omi.git
cd omi/desktop/macos
cp ../../backend/.env.example ../../backend/.env

Then the build runs without the flag:

./run.sh

Read the path closely. The env file belongs to backend/, not to the desktop app, which tells you the desktop process is a client to something you have to stand up. Environment variables and credential setup are then delegated to desktop/macos/README.md rather than spelled out at the root, so the self-hosted path takes you out of the main file and into two others before a backend answers. The practical consequence: these are not the same product behind different launchers. One is a client against infrastructure you did not build, the other is a local Python, FastAPI and Firebase stack you must configure and keep running yourself.

Windows runs from source on a published example config

The Windows path has no counterpart to --yolo, and it reads differently in a way that shows which side of the fork you land on:

git clone https://github.com/BasedHardware/omi.git
cd omi\desktop\windows
npm install
copy .env.example .env
npm run dev

This is a Node build running from source, and the stated behavior is that it starts using the public config in .env.example. Copying an example file into .env is the documented way to get a run on Windows, and the values in a published example file are published values, so treat the endpoints it names as something to verify rather than a default. Node.js is the only listed requirement here, against three on the macOS side. Nothing here documents a Windows path to the full local backend stack, and the release tags do not fill the gap: every recent release in this repository is a macOS desktop build. If you need Omi on Windows against your own backend, that answer has to come from docs.omi.me rather than the root file.

make setup installs hooks and a pinned venv, not a runnable environment

`make setup` is described as the baseline for development worktrees, and the description is narrower than the name implies. It installs the Git hooks and syncs the pinned backend Python environment used by selected pre-push checks, while the mobile and desktop runtime environments remain opt-in:

make setup

When it finishes you have hooks and a Python environment. You do not have a runnable mobile app or a runnable desktop environment, which is the gap that catches people who read setup as equivalent to the full installation. The Makefile is unusually defensive about where it runs, and two comments in it describe breakage that already happened. Under Windows_NT it derives its shell from git --exec-path so it can locate bash.exe. For the interpreter it discards the PYTHON value GNU Make supplies by default and resolves one through scripts/dev-harness/_resolve_python.sh, because in a linked worktree git rev-parse --show-toplevel exits 128 and previously expanded to an empty prefix, breaking every target with /scripts/dev-harness/_resolve_python.sh: No such file. That resolution is kept inside Bash on purpose, so a non-ASCII checkout path is never exported through Make's legacy code page. Two hostile checkout conditions, both accounted for in the file you are about to trust.

Ledger tests refuse to run until you hand them a 32-byte secret

The memory layer is tested against the Firestore emulator rather than a live project, and the package.json scripts show what that costs a contributor:

npm run test:memory-firestore-rules:emulator
npm run test:memory-firestore-transactions:emulator
npm run test:memory-knowledge-ledger-migration:emulator

Each expands to `firebase emulators:exec --only firestore` against a demo project rather than production, so the memory rules and their transactions get exercised without touching live data. Two requirements sit underneath. The Python cases invoke `backend/.venv/bin/python`, the pinned backend environment that make setup syncs, so an unconfigured checkout fails before the emulator starts. The knowledge ledger scripts prepend ENCRYPTION_SECRET with sample values whose names end in _32_bytes, and `omi_ledger_migration_emulator_test_key_32_bytes` shows the secret length the ledger expects without any prose stating it. MEMORY_ENABLED=on gates several of the scripts, so a variable with no visible default decides whether that code path runs at all, and two of them target different demo projects, demo-memory and demo-daily-memory-sweep, which keeps the daily sweep isolated from the memory rules. The cost for a contributor: contract_tests/ and contracts/ sit at the top level, but reproducing their intent needs the emulator, the pinned venv and, for the ledger cases, a secret you supply yourself.

Every recent release tag is a macOS candidate, three of them on one day

The three most recent releases are v0.12.433, v0.12.434 and v0.12.435, all published on 2026-10-02, all labelled candidate, all carrying a -macos suffix. Read together, that says the release stream tracks one desktop app on one platform. There is no iOS tag, no Android tag and no Windows tag in view, even though the tree holds a Flutter app for both mobile platforms, a Windows desktop app under desktop/, and a codemagic.yaml that exists for mobile builds. The Flutter app reaches people through the App Store and Play Store listings linked in the README, a distribution path with its own mechanics. For a team pinning a version the consequence is immediate: a tag pins a macOS candidate build, and if your target is a wearable paired to a phone, the tag says nothing about what shipped on the device or in either app store. The last push on this repository was on 2026-10-01, so the branch moves faster than that release list can describe.

Two firmware targets on two SoC families, and no flashing command to copy

Two firmware targets live here on different silicon. The wearable firmware in omi/ is nRF with Zephyr and C; the Omi Glass firmware in omiGlass/ is ESP32-S3 with C, offered as a dev kit with a camera and audio. Pair a wearable with the mobile app and the project claims 24h+ continuous capture, which means a microphone running for a day plus a set of decisions about what survives. On the wire, the SDKs share BLE UUIDs and packet framing across TypeScript, Go, Rust, C++ and Dart, while the Python device SDK is the one described as full BLE plus Opus plus Deepgram, which places both the audio codec and the transcription vendor inside that path. The README prints no flashing command. Building the device, flashing firmware, the buying guide and the DevKit2 hardware specs are links out to docs.omi.me. The hardware half of Omi is documentation-driven rather than repository-driven, so plan on reading four external pages before a device is in your hand.

Agent configs in five directories, and retention nobody documents

The top level carries agent configuration in five places: .agents/, .amp/, .cursor/, .gemini/ and .windsurf/, sitting next to AGENTS.md, CLAUDE.md and .impeccable.md. Around them are CONTRIBUTING.md, PRODUCT.md, SECURITY.md, ISSUE_TRIAGE_GUIDE.MD, a .pre-commit-config.yaml, a .secrets.baseline and a .cursorignore. CONTRIBUTING.md remains the documented route for contributing, so treat the rest as tooling rather than as instructions you must reconcile before your first patch. The same top level answers part of the question the product invites: firestore.rules and firestore.indexes.json are committed, firebase.json is committed, and the emulator scripts exist because those rules are treated as code worth breaking on purpose. What the README does not state is a retention period for recordings, a default for what leaves the device, or any deployment documentation for the backend you build yourself. The only adoption figure offered is the line Trusted by 300,000+ professionals, and nothing in the repository substantiates it. Fine for a personal tool. Not fine as the basis for a workplace answer.

Editorial conclusion

Omi fits a developer who wants a searchable memory of their own screen and conversations and is willing to run the local backend to keep the processing on their own machine. It does not fit a team expecting the documentation to answer retention questions, because the README states no retention period and no default for what leaves the device. Verify the install path you actually intend before you grant screen and microphone permissions: running ./run.sh --yolo points both at a cloud backend, and the local stack only exists after you copy backend/.env.example to backend/.env and read desktop/macos/README.md for the credentials it expects.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes