omm README

Quick start

After installing omm, run these commands in order:

Use that name with omm verify <name> to check local load and generation, then omm run <name> to use it. If setup or a runner is not working, start with omm doctor and omm log --lines 5. A recommendation estimates fit; verification checks the selected model on your machine.

Table of contents

• What omm does
• Quick start
• Install
  • Windows
  • macOS
  • Linux
  • Any OS via PyPI or pipx
  • npm
  • Troubleshooting
  • Windows portable and Winget status
  • Supported platforms
  • Local AI runners
  • Storage location
• Usage
  • Setup & discovery
  • Install & manage models
  • Verify & benchmark
  • Update & configuration
  • Local logs and automatic import
  • Scripting
• Self-hosted benchmark data
• Signed recommendation data
• Development
• Contributing
• Security
• License

Install

Pick your OS and follow one path from top to bottom:

• Windows — PowerShell one-liner (verified Git-source installer)
• macOS — Terminal one-liner, or the Homebrew Tap
• Linux — shell one-liner
• Any OS via PyPI or pipx — pip / pipx, no signature verification
• npm — standalone native command distributed through npm
• Troubleshooting — what you see, why, and how to fix it

Windows

1. Open this app. Open PowerShell — either Windows PowerShell 5.1 (Start menu → "Windows PowerShell") or PowerShell 7 (pwsh). Windows Terminal is fine as long as the active tab is a PowerShell tab. Do not use Command Prompt (cmd.exe), and do not paste the one-liner into Git Bash or WSL; those are Unix shells and need the Linux path instead.

2. Requirements. Python 3.10+. Windows 10 22H2/11 is the supported baseline. The installer bootstraps Python and git via winget if they are missing (winget is built into Windows 10 2004+ and Windows 11 — on older Windows, install Python 3.10+ and git manually first), then installs omm through that exact validated Python interpreter. The optional NVIDIA detector is installed only when nvidia-smi indicates an NVIDIA driver.

3. Run the installer. Both lines are one command; paste them together.

4. After install. Open a new PowerShell window so your PATH picks up omm, then run:

5. Windows notes. Model exposure tries an unprivileged same-volume hard link first, then a symbolic link (Developer Mode or Administrator), then an owned copy. Before copying, omm checks destination free space and reports that the model now consumes additional bytes. File junctions do not apply because model targets are files, not directories.

Set OMM_HOME before installation and on later runs to put the model hub on another volume. Runners omm installs itself (KoboldCpp, text-generation-webui, AnythingLLM, Msty) go to OMM_HOME\apps and installer downloads to OMM_HOME\tmp, so nothing large lands on the system drive. (AnythingLLM still keeps its bundled Ollama and starter model, ~5 GB, under %APPDATA% - its installer offers no way to move that.)

Install native shell completion once, then restart the shell:

Remove a Git-source installation while preserving downloaded models and settings:

Download that script and run it with -Purge to remove the model hub and settings too.

Runner note: AnythingLLM and Msty currently require manual installation on Windows; the checklist prints guidance instead of guessing an installer or package ID.

Detailed walkthrough: https://omm.run/install/windows

macOS

1. Open this app. Open Terminal (Applications → Utilities → Terminal), or any terminal emulator you already use. The command runs under sh/zsh/bash.

2. Requirements. Python 3.10+ and git. The installer uses Homebrew when either is missing: if Homebrew itself is not installed, it bootstraps Homebrew with Homebrew's official installer first (Homebrew requires a supported macOS and Apple's Xcode Command Line Tools). To require a pre-existing Homebrew installation instead of letting the installer bootstrap it, export OMM_AUTO_INSTALL_HOMEBREW=0 before running the command. pipx is bootstrapped with pip if missing (Homebrew and other PEP-668 "externally-managed" Pythons are handled with --break-system-packages), and omm is then installed as an isolated CLI via pipx. The installer also persists pipx's executable directory in ~/.zprofile, so a newly opened zsh finds omm automatically. The optional NVIDIA detector is installed only when nvidia-smi indicates an NVIDIA driver.

3. Run the installer.

4. After install. Open a new shell afterward so your PATH picks up omm, then run:

5. Homebrew Tap (alternative).

Upgrade or remove the formula with Homebrew. Removing the formula preserves downloaded models and settings under OMM_HOME:

After a tagged PyPI release passes its public install checks, GitHub notifies the Homebrew Tap. Homebrew intentionally applies its upstream release cooldown before opening an automated Formula update PR, so the Tap can temporarily lag behind PyPI. Use brew info omm-hippo/omm/omm to see the version currently provided by the Tap. omm update does not modify a Homebrew installation and instead prints the matching brew upgrade command.

6. macOS notes. Set OMM_HOME before installation and on later runs to put the model hub elsewhere:

Install native shell completion once, then restart the shell:

Remove a Git-source installation while preserving downloaded models and settings:

Download that script and run it with --purge to remove the model hub and settings too.

Detailed walkthrough: https://omm.run/install/macos

Linux

1. Open this app. Any terminal emulator. The command runs under sh/bash.

2. Requirements. Python 3.10+. The installer bootstraps python3, python3-venv/equivalent, and git via whichever supported package manager is present — apt-get, dnf, yum, pacman, or apk — when the current user can install system packages; on an unsupported distribution, install Python 3.10+ and git yourself first or the installer exits with Python 3.10+ not found or git not found. Install git first. pipx is bootstrapped with pip if missing (PEP-668 "externally-managed" Pythons are handled with --break-system-packages), and omm is then installed as an isolated CLI via pipx. The optional NVIDIA detector is installed only when nvidia-smi indicates an NVIDIA driver.

3. Run the installer.

4. After install. Open a new shell afterward so your PATH picks up omm, then run:

5. Linux notes. Set OMM_HOME before installation and on later runs to put the model hub on another volume:

Install native shell completion once, then restart the shell:

Remove a Git-source installation while preserving downloaded models and settings:

Download that script and run it with --purge to remove the model hub and settings too.

Runner note: omm installs Jan on Linux through Flatpak, so flatpak must be present for that entry in the runner checklist.

Detailed walkthrough: https://omm.run/install/linux

Any OS via PyPI or pipx

Works on macOS, Linux, and Windows:

This does not go through the signed-commit verification described below; it relies on PyPI's own account security and TLS, the same trust model as installing any other PyPI package. It is a package-manager path, not a zero-prerequisite installer: install Python and pip first on a clean computer.

For an isolated command-line installation, pipx is recommended:

On Windows, use py -m pip, py -m pipx, and py -m pipx ensurepath instead. If the operating system marks Python as externally managed, install pipx from the operating system package manager or use the Git-source installer above.

The distribution name is omm-model; the installed command and Python import remain omm. Upgrade and remove it with the same tool that installed it:

Both commands preserve downloaded models and settings under OMM_HOME.

npm

The public npm launcher installs a platform-specific standalone omm binary, so Python is not required for this path. It requires Node.js 22.14 or newer:

Published npm binaries cover macOS on Apple Silicon and Intel, glibc-based Linux on ARM64 and x86_64, and Windows x64. Other operating-system, architecture, and libc combinations should use the Python-based installer or PyPI path instead.

Upgrade or remove the npm installation with:

The npm launcher verifies the selected native package name, version, platform metadata, and binary containment before executing it. Release CI separately checks package integrity and registry signatures. Removal preserves models and settings under OMM_HOME.

Troubleshooting

Match the message you see, not the step you think you are on.

Windows portable and Winget status

The Windows x64 portable ZIP and checksum are published as CI-verified GitHub Release assets. The community Winget submission is not yet merged, so there is no supported winget install command to document at this time.

Supported platforms

omm is tested in CI on Windows, macOS, and Linux. Python-based installation paths require Python 3.10 or newer; the npm path requires Node.js 22.14 or newer and one of the published native targets listed above. Windows 10 22H2/11 is the supported Windows baseline because that matches Ollama's native Windows requirements. Hardware scan, install, linking, benchmark, update, and contribution flows are cross-platform. Benchmarking selects an available local Ollama or LM Studio runtime; runner- and model-specific capabilities can still differ.

Updates and verification

Both installers clone to a versioned staging directory, verify the signed commit against a bootstrap trust anchor, and only then switch pipx to it. Do not replace this with an unverified git clone plus pipx install if commit authenticity matters.

omm update updates only a canonical OMM Git-source installation. For a package-managed installation, it leaves files unchanged and prints the matching package-manager upgrade command. The Git-only beta channel is likewise unavailable to package-managed installations. Git-source updates parse the new release's declared dependencies, honor python_version markers, and refresh the pipx environment when an applicable dependency is missing or older than the declared minimum.

Package-channel verification

Additional package-manager commands are added here only after their public registry path has been installed and verified.

Local AI runners

The first bare omm run on a fresh install (or omm setup any time after) shows a hardware summary and a checklist of local AI runners. Checking one that omm knows how to install runs its official installer with live progress in the terminal; checking one it doesn't yet automate on your platform prints a link instead. Automation coverage today:

Every currently-installed runner is also listed (marked as already installed, not selectable) rather than hidden, so the checklist always reflects what omm actually detects on the machine.

See engine management for operation previews, package ownership checks, and verification limits.

Storage location

The model hub and omm state default to ~/.omm. Set OMM_HOME before installation and on later runs to put them on another volume (see the snippet in your OS section above). The setup table shows the path separately from decimal GB that is immediately writable on the volume containing it; this is not the size of the .omm folder, and an OS storage screen may additionally count purgeable space.

Ollama's own model location follows OLLAMA_MODELS. LM Studio follows its home pointer; set OMM_LMSTUDIO_MODELS_DIR when LM Studio uses a custom directory that omm cannot discover automatically.

Completion and uninstall

Each OS section above carries the completion and uninstall commands for that shell. For a PyPI installation, use python -m pip uninstall omm-model; for pipx, use pipx uninstall omm-model. Both commands preserve downloaded models and settings under OMM_HOME.

Purge (-Purge on PowerShell, --purge on sh) removes only known omm-owned paths and leaves unrelated files in a custom OMM_HOME untouched. Installers mark custom homes so uninstallers can refuse ambiguous or unsafe locations; shell profiles are never rewritten during uninstall.

Usage

Setup & discovery

omm recommend keeps compatible models visible when they are already present, marks whether OMM or another supported local runner owns them, and never reinstalls a selected installed model. In JSON output, installed, managed_by_omm, installed_engines, and installation_match expose the same state. installation_match distinguishes an exact artifact from the same model-and-parameter-size identity in a manifest-based runner, whose local quantization may differ. With --yes, the highest-ranked model that is not installed is selected; if every displayed recommendation is already present, the command exits without downloading.

Install & manage models

install, uninstall, info, and upgrade accept either a model name/reference or the numeric index shown by the last omm search or omm list run in that terminal. omm info and omm fit both work on a model that is not installed yet, so a search result can be inspected before downloading several GB; omm info describes the model, omm fit answers whether it runs on this machine. search/install mark models predicted not to run on this machine's hardware in red.

Before a normal interactive install, OMM shows a source card with the provider, repository, file, expected size/location, GGUF format, and the HTTPS/size/SHA-256 checks it plans to perform. Afterward it reports the checks actually completed. “SHA-256 matched” means the bytes match the provider or pinned digest; it does not claim the file is non-malicious. --quiet, piped/ non-interactive use, and internal contribution flows keep this extra presentation out of scripted output.

Interrupted installs keep checkpoints under OMM_HOME/install-journal. Re-run the original install command to recheck the file and repair links; omm doctor lists incomplete attempts. See install recovery.

omm install --skip-unfit is a scripting-friendly skip, not a successful installation: it prints Skipped and leaves the model hub unchanged. If an uninstall cannot remove the managed model file, OMM exits with status 1 and keeps the registry and any still-live links so the same command can be retried.

omm upgrade no longer re-downloads a model against its own source. To re-check an installed file and replace it only if the source actually changed, use omm install <name> --force.

Verify & benchmark

omm verify checks more than a link: it asks before starting a stopped local runtime or loading an unloaded model, sends one short deterministic prompt, requires a non-empty answer, and stops or unloads only what OMM started for the check. It never deletes the model or stores the generated answer. Use --yes for unattended confirmation and --keep-loaded to preserve a model OMM loaded for the check. LM Studio API authentication reads LM_API_TOKEN from the process environment and never writes it to config.json. Compatibility status is stored locally in models.json and is shown by omm info.

omm compare resolves two to five exact packages from the signed recommendation catalog and compares predicted speed, estimated memory, install state, declared purpose, and any locally cached signed quality evidence. It never downloads, installs, or runs a model. BEST FOR remains provider-declared metadata; MEASURED is shown separately and missing evidence is Not measured, never a zero score.

omm evaluate currently supports installed Ollama models and the versioned Python coding smoke pack. Model-generated source runs only through Docker or Podman with no network, a read-only workspace, bounded resources, dropped capabilities, and a timeout. Generated source is neither stored nor uploaded; --output contains only task outcomes and exact model/pack identity. This pack is a small reproducibility check, not a leaderboard. OMM never pulls the container image implicitly; if it is absent, the error prints the exact digest-pinned docker pull/podman pull command for the user to run explicitly.

Update & configuration

Local logs and automatic import

Logs live under OMM_HOME/logs/ and are not uploaded by the data-sharing channels. Review and redact a log before attaching it to an issue.

Automatic import is off by default. Enabling it registers a per-user background service that adopts newly discovered models without a prompt. It requires the optional watch dependencies (watchdog and plyer); for a pip installation, use python -m pip install "omm-model[watch]" in that installation's environment. The status command reports configuration and service registration; it does not prove that a particular file has been imported. Check omm list after the file has finished downloading.

Saved runtime profiles are tied to the exact model file and engine. omm verify and supported omm run paths use them on the next owned load; running models keep their current settings. See runtime profiles for engine capabilities, memory checks, cleanup, and verification limits.

Scripting

All errors, warnings, and confirmation prompts print to stderr. For search, list, info, tune, scan, doctor, recommend, compare, evaluate, and bug-report, --json makes stdout a single structured document that is safe to pipe (for example, omm list --json | jq .). benchmark --json also writes a single JSON report to stdout; --output saves the same evidence as a file. Supported commands emit a structured error document when their command body fails before producing a result, and use exit status 130 with status: "cancelled" when interrupted. Argument-parser errors use a JSON error document when --json was requested, and stderr otherwise, with exit status 2. Successful data shapes remain unchanged.

For commands that document --yes/-y, pass it to skip their confirmation prompts, or use the command-specific flag (install --skip-unfit, install --upload/--no-upload). Benchmark upload consent remains governed by omm setting upload; for non-interactive benchmarks, start the selected local runtime before invoking the command.

These common flags are available on most top-level commands. Where supported, they may be accepted before or after the subcommand name (omm --json search foo and omm search foo --json are equivalent). Use omm COMMAND --help for the exact flags and placement of a specific command:

• --json — structured output, where supported (see above)
• --yes / -y — skip confirmation prompts
• --quiet / -q — suppress progress bars and background status/hint lines (e.g. download progress, "Verifying checksum...", scan's "Run: omm link" nudge); errors, warnings, and the result of what you asked for still print
• --no-color — disable ANSI colors on omm's own console output and its download progress bar; the NO_COLOR environment variable does the same

Unsupported --json combinations return a single unsupported_json error document and exit 2 before command actions or startup prompts run. JSON mode never opens the first-run setup/import dialogs, including on a terminal. omm --json --version returns a version document; explicit --help still shows normal help. The shared flag wrapper warns when --yes has no effect. Exit codes are consistent across commands: 0 success, 1 failure, and 2 usage error (bad flag or argument).

rm, ls, and up are short aliases for uninstall, list, and upgrade.

Set OMM_HOME to store everything (models, config, catalog history) under a different directory instead of ~/.omm — useful when $HOME's filesystem doesn't have room for GGUF models, e.g. OMM_HOME=/mnt/data/omm omm contribute --yes.

omm contribute keeps models and partial downloads already on your computer; it removes only the temporary models created by that session. Choose an optional time, model-data download, or new-model count limit, or combine them as above. The download limit is in GiB and includes retries; metadata and HTTP/TLS overhead are excluded. A time limit requests cancellation and then allows safe cleanup to finish. Without these flags, the loop continues until Esc or candidate exhaustion. The startup notice explains what is sent and whether the configured collector is public. The final summary separates successful measurements, accepted uploads, failed sends saved for retry, and the files kept or removed. The recommendation data contribution guide gives a one-model starting point, cross-computer instructions, and the current quality-data limits.

omm contribute performs a 10 GiB startup free-space preflight. Before each download it separately budgets the central GGUF, a worst-case full runner copy, any required Windows cross-volume copies, and safety headroom. Each model evaluation prints a heartbeat every 30 seconds and is terminated after an absolute 10-minute deadline instead of hanging an unattended session indefinitely.

Localfit does not assume all installed memory belongs to the model. A live scan subtracts memory currently used by other applications, keeps at least 2 GB (or 10% of RAM) for the OS and newly opened apps, and applies total-memory caps. Recommendation fit and omm tune use this safe budget, so rerunning a command adapts after memory-heavy applications are opened or closed.

omm benchmark runs a versioned eight-item bilingual arithmetic smoke pack against models already installed in the selected Ollama or LM Studio runtime. It stores parsed answers, correctness, pinned model metadata, and fixed-length timings under OMM_HOME/evaluations/ (default ~/.omm/evaluations/); it stores no generated text. Opt-in telemetry sends a locally computed CPU chip score (and GPU chip score, when a GPU is present) plus architecture and core counts — never the raw CPU/GPU model name — so speed predictions can distinguish otherwise identical Linux x86_64 machines. Results are uploaded only after explicit opt-in. The pack is intentionally small and is not a leaderboard.

On Windows, Ollama is detected by its HTTP API first, so a freshly installed tray app works even before the current terminal receives the new PATH. When the daemon is stopped, omm also checks Ollama's documented %LOCALAPPDATA%\Programs\Ollama location. It only stops daemon processes it started itself. Before deleting a contribution model, omm requests an Ollama unload, waits for /api/ps to confirm handle release, and uses bounded retries for Windows file locks. Real-time antivirus can still delay a first load; the benchmark uses repeated samples and reports their median. Do not disable your antivirus for omm.

Self-hosted benchmark data

Benchmark results are never uploaded without explicit per-run consent or an always policy. New installations use the hosted proof-of-work gateway as the default destination, while existing local-only configurations stay local. To run the bundled FastAPI + SQLite collector instead:

Explicitly configure the endpoint and opt in before uploading:

Loopback ingestion needs no token. Once LOCALFIT_INGEST_TOKEN is set, every request needs it — including loopback ones, so export the same value for the omm client on that machine. A same-host reverse proxy makes remote requests look like loopback, so peer address alone is not treated as authentication. If the collector listens on a non-loopback interface, set the same LOCALFIT_INGEST_TOKEN on both the server and the omm client; remote ingestion fails closed when it is missing. The client only attaches LOCALFIT_INGEST_TOKEN to an https endpoint, so a loopback (http://127.0.0.1:…) collector never receives it.

Training can consume the authenticated export directly:

Firebase Realtime Database JSON endpoints remain supported. An official *.firebaseio.com or *.firebasedatabase.app .json URL can be read without an admin token; self-hosted raw export requires LOCALFIT_ADMIN_TOKEN. Exact duplicate events are ignored.

Automated retraining is fail-closed. Configure LOCALFIT_TELEMETRY_EXPORT_URL; configure LOCALFIT_ADMIN_TOKEN as well for a self-hosted export (it is optional for an official Firebase JSON URL). The scheduled job otherwise stops without changing the published artifact. It requires at least 100 distinct valid v6/v7 configurations with explicit runtime and CPU metadata (legacy rows do not satisfy this minimum), rejects datasets with more than 25% invalid rows, and reserves a deterministic 20% holdout. A 64-tree v4 candidate replaces the incumbent only when both holdout RMSLE and P90 absolute percentage error stay within the configured regression limits. Selection is evaluated on whole hardware/request contexts, so sibling model variants never leak across training and holdout sets. Publishing requires at least three multi-model selection groups and complete selection metrics. Fit-regression checks are only applied once the minimum known-unfit sample count is met. A passed publication gate therefore does not mean every check was evaluated: per-check evaluation_details and omm setting catalog-status distinguish passed, failed, and insufficient data. See evaluation evidence. The artifact records the candidate/baseline evaluation report.

The same gate can validate an exported local dataset without contacting the collector:

Synthetic bootstrap training remains available for local development, but the scheduled publishing workflow never uses it as a substitute for missing real benchmark data.

Signed recommendation data

omm setting catalog-trust --manifest-url <https-url> --public-key <base64-key> enables Ed25519 verification for future recommendation downloads. Existing artifacts are snapshotted before replacement and omm setting catalog-rollback restores the most recent different snapshot.

Development

Run tests with the disposable home and model-hub setup in CONTRIBUTING.md. That guide also covers platform-specific setup, scoped checks, signed-head requirements, and pull-request conventions.

Contributing

Contributions are welcome. See CONTRIBUTING.md for setup, testing, and PR conventions, and CODE_OF_CONDUCT.md for community expectations. Report security issues per SECURITY.md rather than as a public issue.

Security

Do not open a public issue for a suspected vulnerability. Follow the private reporting instructions and supported-version policy in SECURITY.md.

License

The omm source code is available under the MIT License. Third-party dependency notices are listed in THIRD_PARTY_NOTICES.md. Models and local runner applications installed or linked by omm keep their own upstream licenses and terms; the project MIT license does not replace them.