Start with: 
eyra status
eyra doctor
eyra setup
status gives the short answer. doctor shows what is ready and what needs attention. setup repairs local settings and provider selection. Inside a live session, /status, /capabilities, and /context show runtime state, enabled control surfaces, privacy boundary, recent jobs, and recent local changes. If you want visible controls: 
eyra menu
eyra open
eyra logs --open
Check menu bar availability without launching it: 
eyra menu --json --check

​
Backend does not start

Symptom: Eyra stops during preflight with a backend or model message. Run: 
eyra setup
Choose Ollama for the private local default, or choose another provider if that is what you want. If Ollama has no model yet, Eyra offers to download the recommended local model. Check the provider: 
curl http://localhost:11434/v1/models
curl http://localhost:11434/api/tags
Then check model names: 
ollama list
ollama show gemma4:e4b
If you use a remote provider, confirm API_BASE_URL, API_KEY, and MODEL point at a chat-completions-compatible model.

​
Local model rejects tools

Some local models answer normally but do not support native tool calling. Eyra warns during preflight and falls back to plain streaming when possible. Use deterministic controller actions for time, screen, PDF, task commands, context, capabilities, and common file work when native tools are unavailable. Use a tool-capable model for open-ended tool loops.

​
Voice is unavailable

From the shell: 
eyra doctor
Inside Eyra: 
/voice-diagnose
It checks input devices, all-zero audio, VAD speech detection, Local Whisper ASR, generated WAV transcription, and the Local Whisper socket path. If Local Whisper is missing: 
brew tap gabrimatic/local-whisper
brew install local-whisper
If the wrong microphone is selected, set: 
VOICE_INPUT_DEVICE=<index-or-name>

​
Web UI cannot connect

Start or restart the local control service: 
eyra start
eyra restart
eyra open
Check health: 
curl http://127.0.0.1:8765/api/health
If non-health endpoints return unauthorized, use the tokenized URL printed at startup or set a known high-entropy WEB_UI_TOKEN. Do not set WEB_UI_REQUIRE_TOKEN=false for 0.0.0.0; Eyra forces auth for non-localhost binds.

​
Memory needs setup

Check the real memory path: 
eyra memory status
eyra doctor
doctor checks command availability and asks the memory MCP server for a small compact context. If the command is missing: 
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
If the status says memory file error, the local JSON file may be corrupt or unreadable. The path is shown by eyra memory status. Move the file aside if you want Eyra to start a fresh memory file. If you want every automatic memory write to require an explicit request, set: 
MEMORY_WRITE_REQUIRE_CONFIRMATION=true
With that setting, remember commands still save, but ordinary auto-save candidates are skipped. Check the menu bar state: 
eyra menu --json --check
If mode is app-bundle, eyra menu opens the installed Eyra.app. If mode is source-swiftpm or package-resource, the menu bar is using the developer path and needs Swift/Xcode command-line tools. If mode is unavailable, use: 
eyra open
From a source checkout, rebuild the local app bundle: 
scripts/build_menu_bar_app.sh

​
File access is denied

Eyra resolves paths before checking the sandbox. 
FILESYSTEM_ALLOWED_PATHS=~/Documents,~/Desktop,~/Downloads,/tmp
FILESYSTEM_DEFAULT_PATH=~/Documents
Add only the roots needed for the workflow. Existing files are protected from overwrite unless you explicitly approve or confirm the exact overwrite.

​
Installer refuses the target directory

install.sh allows only managed install roots: 
~/.local/share/eyra/*
~/Applications/*
/opt/*
It refuses /, $HOME, and ~/.local to avoid moving or replacing broad user directories. Set EYRA_INSTALL_DIR to a subdirectory under one of the allowed roots.

​
Wrong .env is being read

Installed Eyra reads ~/.config/eyra/.env. A repo-local .env wins only when you run from an Eyra source checkout. If another project has a .env in your current directory, Eyra ignores it. Run eyra paths --json and eyra doctor --json to confirm the active config and support paths.

​
Shell PATH lines are duplicated

Run setup again: 
eyra setup
Setup removes older shell lines ending in # eyra before adding the current PATH line. Uninstall also cleans Eyra-created shell lines from ~/.zshrc and ~/.bashrc.

​
Network tools are unavailable

Default behavior: network tools are off. 
NETWORK_TOOLS_ENABLED=true
Weather requires an explicit location and does not use remote IP geolocation. Browser download and upload actions require approval and stay under the filesystem sandbox.

​
Tests fail after docs or config changes

Run the project gate: 
uv run pytest -q
uv run ruff check src tests
uv lock --check
bash -n setup.sh install.sh
If a failure depends on physical microphone hardware, keep that gate separate from code-path certification and state the environment that was actually tested.