Runtime: macOS on Apple Silicon. The easiest path is the guided installer. It installs Eyra, checks local AI and voice, and leaves you with plain next steps if one piece still needs attention.

​
Guided install

curl -fsSL https://gabrimatic.github.io/eyra/install.sh | bash
The installer:
  • Checks this Mac.
  • Installs uv when missing.
  • Offers to install Ollama when Homebrew is available.
  • Offers to install Local Whisper for speech and microphone support.
  • Installs mcp-prose-memory for compact local memory when npm is available.
  • Starts local services when it can.
  • Runs first-run setup.
  • Verifies the app commands.
  • Runs eyra doctor and eyra certify as readiness checks.
If doctor or certification needs attention, the install is still available. Run: 
eyra status
eyra doctor
eyra setup
eyra examples
That gives the next repair step without making you reinstall.

​
After install

Open the menu bar controls: 
eyra menu
Start a terminal session: 
eyra
Open the local Web control UI: 
eyra open
The guided installer places Eyra.app under ~/.local/share/eyra/ when the bundle is available. If the menu bar app is unavailable, eyra open remains the fallback control surface.

​
Source checkout

Advanced path: use this when you want to change Eyra itself. 
git clone https://github.com/gabrimatic/eyra.git
cd eyra
chmod +x setup.sh && ./setup.sh
setup.sh creates local settings, installs dependencies, offers to install or start local AI and voice helpers when safe, checks the backend and model, checks Local Whisper when voice is enabled, and registers the eyra command. It preserves an existing .env, removes older shell lines ending in # eyra, then adds one current ~/.local/bin PATH line. Run from source: 
uv run python src/main.py
Build and run the menu bar app from source: 
scripts/build_menu_bar_app.sh
eyra menu
After your shell sees ~/.local/bin, run: 
eyra

​
Installer safety

  • Requires macOS on Apple Silicon.
  • Requires Python 3.11+; installs python@3.11 through Homebrew when possible.
  • Installs uv when missing.
  • Allows install directories only under ~/.local/share/eyra/, ~/Applications/, or /opt/.
  • Refuses /, $HOME, and ~/.local as install targets.
  • Preserves existing installs by moving them to a timestamped backup.
  • Rolls back the install directory if app command setup fails.
  • Keeps the install when optional runtime checks need attention, so eyra doctor can guide repair.
Supported overrides: 
EYRA_VERSION=v4.3.5 EYRA_INSTALL_DIR="$HOME/.local/share/eyra/app" ./install.sh
The installer reads GitHub release JSON, prefers release assets with checksum files, and refuses unverified tag-archive fallback unless you explicitly set EYRA_ALLOW_UNVERIFIED_TAG_ARCHIVE=true. For testing from a checked-out tree, use EYRA_SOURCE_PATH=/path/to/eyra ./install.sh; the installed app still writes user config to ~/.config/eyra/.env, not into the app directory. Disable installer prompts with: 
EYRA_INSTALL_NO_PROMPT=true ./install.sh
Strict installer verification is available when you want install-time certification to fail the whole install: 
EYRA_INSTALL_STRICT_VERIFY=true ./install.sh
eyra doctor --json reports installer-managed app copies as managed-install.

​
Homebrew tap

Current formula status: public tap formula. 
brew tap gabrimatic/tap
brew install eyra
The formula installs the latest tagged GitHub release asset with a pinned checksum. Formula behavior:
  • Runs uv sync --frozen --no-dev at install time.
  • Command shims execute the installed virtual environment’s console scripts.
  • Provides eyra, eyra-web, eyra-doctor, eyra-certify, eyra-setup, eyra-connectors, and eyra-menu.
  • Runs eyra version, eyra paths --json, and eyra doctor --json in the formula test. The formula test uses mock, typed-only mode so a clean Homebrew test does not require a running model backend.

​
Local provider

Default provider: Ollama. 
API_BASE_URL=http://localhost:11434/v1
API_KEY=ollama
MODEL=gemma4:e4b
Eyra checks /v1/models, falls back to Ollama /api/tags, verifies every configured model, and auto-pulls missing Ollama models when AUTO_PULL_MODELS=true.

​
Voice dependency

Eyra uses Local Whisper for both transcription and speech output. 
brew tap gabrimatic/local-whisper
brew install local-whisper

​
Memory dependency

Eyra uses mcp-prose-memory for compact local memory. 
npm install -g mcp-prose-memory || npm install -g https://github.com/gabrimatic/mcp-prose-memory/releases/download/v3.1.0/mcp-prose-memory-3.1.0.tgz
eyra memory status
The guided installer and setup.sh try the npm package first, then fall back to the GitHub release tarball if npm authentication or registry access is unavailable. If Node.js is missing, install it from Homebrew or from nodejs.org, then rerun eyra doctor. Preflight resolves the wh binary from PATH, LaunchAgent plists, and common Homebrew paths. If voice is disabled, the Local Whisper check is skipped.

​
Mock mode

Use mock mode when you want to smoke-test Eyra without a running model backend. 
USE_MOCK_CLIENT=true LIVE_LISTENING_ENABLED=false LIVE_SPEECH_ENABLED=false uv run python src/main.py
Mock mode intentionally bypasses backend and model preflight. It still exercises the terminal session, command handling, local routing, and basic streaming path.

​
Web UI

Standalone Web runtime: 
WEB_UI_ENABLED=true uv run python -m web.server
Shared terminal and Web runtime: 
WEB_UI_ENABLED=true eyra
Default host: 127.0.0.1. Set WEB_UI_HOST=0.0.0.0 only when you intentionally want another device on the network to connect.

​
Verification

Run the standard local checks: 
uv run pytest -q
uv run ruff check src tests
uv lock --check
bash -n setup.sh install.sh
Run certification when validating voice-to-computer behavior: 
uv run python scripts/certify_voice_to_computer.py