Skip to content

Installation Guide

Choose the best installation method for your platform and performance needs.

Quick Platform Guide

Platform Recommended Method GPU Support Performance
macOS Native Setup ✅ Metal GPU Best
Linux Native Setup ✅ NVIDIA GPU Best
NixOS System Integration ✅ NVIDIA GPU Best
Any Platform Docker Setup ⚠️ Limited* Good

Warning

Docker on macOS does not support GPU acceleration. For best performance on Mac, use the native setup.

Installation Methods

Best performance with Metal GPU acceleration

  • Full GPU acceleration for Ollama
  • Optimized for Apple Silicon
  • Native macOS integrations

👉 Follow macOS Setup Guide

Best performance with NVIDIA GPU acceleration

  • NVIDIA GPU support
  • Full system integration
  • Optimal resource usage

👉 Follow Linux Setup Guide

❄️ NixOS System Integration

Declarative system configuration with GPU support

  • System-level service integration
  • Declarative configuration
  • Automatic service management

👉 Follow NixOS Setup Guide

🐳 Docker (Cross-platform)

Universal solution, some limitations

  • Works on any platform
  • Consistent environment
  • ⚠️ No GPU acceleration on macOS
  • ⚠️ Limited GPU support on other platforms

👉 Follow Docker Setup Guide

What Gets Installed

All installation methods set up these services:

  • 🧠 Ollama - LLM server (gemma3:4b model)
  • 🎤 Wyoming Whisper - Speech-to-text (faster-whisper on Linux/Intel, MLX Whisper on Apple Silicon)
  • 🗣️ Wyoming Piper - Text-to-speech
  • 👂 Wyoming OpenWakeWord - Wake word detection

Service Ports

All methods use the same ports:

  • Ollama (LLM): 11434
  • Whisper (ASR): 10300
  • Piper (TTS): 10200
  • OpenWakeWord: 10400

After Installation

Once services are running, install the agent-cli package:

# Using uv (recommended)
uv tool install agent-cli -p 3.13

# Using pip
pip install agent-cli

Note

The -p 3.13 flag is required because some dependencies don't support Python 3.14 yet. See uv issue #8206 for details.

Then test with:

agent-cli autocorrect --help

Need Help?

  • Check the troubleshooting section in your chosen installation guide
  • Open an issue on GitHub