Tater is a local-first AI platform that can run local models through llama.cpp, Hugging Face Transformers, and MLX, or connect to OpenAI-compatible APIs. It supports voice satellites like VoicePE, Sat1, S3Box, and ReSpeaker XVF3800, plus portals for Discord, Home Assistant, HomeKit, IRC, macOS, Matrix, Meshtastic, Telegram, and XBMC4Xbox.

---

Little Spud Companion App

Little Spud connects to your Tater Spud Hub for chat, TTS, STT, and notifications from your iOS or Android device.

---

Tater Bench

Tater Bench compares local models using repeatable Tater-style accuracy and performance tests across engines, speculative decoding modes, and hardware.

---

🧩 Tater Architecture

Tater is built around a modular system:

• Cores → core systems that extend Tater's capabilities
• Portals → integrations with platforms like Discord, Home Assistant, and more
• Verbas → AI-driven tools and actions Tater can perform
• Integrations → modular provider packages for devices, services, search providers, and external APIs

Tater Shop

Tater Shop manages the catalogs, versions, metadata, and updates for Tater Cores, Portals, and Verbas.

Tater Integrations

Tater Integrations provides modular packages for devices, services, search providers, and external APIs.

---

Supporting Apps

Some Portals are paired with companion repos/apps that complete the end-user integration:

HA Add-ons

Home Assistant add-on repository for running Tater directly inside HAOS/Supervised setups.

HomeKit Shortcuts

Shortcut guide for Siri, the HomeKit bridge, and Tater workflows.

Meshtastic Bridge

Host-side BLE bridge service for connecting Tater to Meshtastic radios over a simple local API.

Tater Native Firmware

Native firmware for Tater voice satellites and related hardware.

Tater Linux Satellite

Native Tater voice and persistent-music satellite runtime for Linux computers, Raspberry Pi, and robots.

ThirdReality S420 Firmware

Tater-native firmware, provisioning, signed OTA, and recovery images for the ThirdReality Voice & Music Assistant.

Tater Wake Words

Wake-word catalog for Tater Native satellites, including issue-based mww: requests for generating new wake words.

WakeWord Trainer for macOS

Apple Silicon trainer app for creating custom wake words, reviewing satellite capture clips, and flashing Tater Native firmware.

WakeWord Trainer for NVIDIA Docker

CUDA/Docker trainer for NVIDIA systems with wake-word training, capture review, and Tater Native firmware flashing.

Little Spud WebUI

Lightweight browser client for chatting with a paired Tater Spud Hub, including media, TTS/STT, and local device notifications.

Little Spud App

Native Little Spud companion apps for connecting iOS and Android devices to a paired Tater Spud Hub. Both mobile apps are maintained in the same repository.

Reachy Tater Satellite

Native Tater voice satellite for Reachy Mini with local wake words, user tracking, expressive motion, reliable audio, and optional vision snapshots.

XBMC4Xbox Skin

OG Xbox/XBMC4Xbox skin and script integration for on-console Tater access.

---

Installation

Note:

• Tater can run any compatible local or OpenAI-compatible model. If you use a thinking model, disable thinking for best Hydra/tool behavior. Tater's built-in local providers try to suppress thinking automatically where supported.

macOS App Installation

1. Download the latest macOS installer

   Download the latest Tater for macOS

2. Install Tater

   Open the DMG, then drag Tater.app into Applications.

3. Launch Tater

   Open Tater from Applications. On first launch, the app prepares its private runtime under:

   ~/.taterassistant/
   

   The app stores its managed Python runtime, virtual environment, runtime settings, logs, updates, and agent_lab data there. It does not use this source checkout's .venv, .runtime, or agent_lab folders.

4. Finish setup in TaterOS

   The app starts Tater on 127.0.0.1:8501 and opens the WebUI in the native window. If Python 3.11 is not already available, the launcher downloads a standalone CPython 3.11 runtime into ~/.taterassistant/python/ and uses it to build the private venv.

Closing the window keeps Tater running in the menu bar. Use the menu bar item to reopen Tater, open it in a browser, stop, restart, show logs, check for updates, install available updates, or quit.

Once the WebUI is up, continue to Post-Install Setup below.

Unraid Installation

Tater is available in the Unraid Community Apps store.

You can install Tater directly from the Unraid App Store with a one-click template.

Unraid note:

• Add container path mappings for /app/agent_lab and /app/.runtime to persistent shares, for example /mnt/user/appdata/tater/agent_lab and /mnt/user/appdata/tater/runtime.
• Also set TZ and map /etc/localtime plus /etc/timezone if you want local time inside the container.

Once the Unraid containers are installed and running, continue to Post-Install Setup below.

Home Assistant Installation

A dedicated Home Assistant add-on repository is available here:

https://github.com/TaterTotterson/hassio-addons-tater

Click the button below to add the repository to Home Assistant:

Once added, the Tater AI Assistant add-on will appear in the Home Assistant Add-on Store.

Install order:

1. Install Tater AI Assistant.
2. Configure your LLM settings in the Tater add-on.
3. Start Tater.

Once the add-ons are running, continue to Post-Install Setup below.

Reachy Mini Installation

The Reachy Tater Satellite app turns Reachy Mini Wireless into a native voice satellite for an existing Tater server. Microphone, speaker, local wake-word detection, user tracking, expressive motion, and optional vision snapshots remain on Reachy, while the robot connects to Tater through its authenticated native satellite connection.

Install path:

1. Install Reachy Tater Satellite from the Reachy Mini app store and start it.
2. Open the app settings from Reachy's web interface and enter the address of your running Tater server.
3. Create a satellite pairing code in Tater, enter it once in the Reachy settings, and save the connection.
4. Optionally enable Allow vision snapshots for the Reachy Vision Verba, then say Hey Reachy.

Local Installation

Prerequisites

• Python 3.11
• A local OpenAI-compatible LLM runtime (such as Ollama, LocalAI, LM Studio, or Lemonade) or Tater's built-in Hugging Face Transformers, llama.cpp GGUF, or MLX LM providers
• Docker is optional.

Set Up Tater

1. Clone the Repository

git clone https://github.com/TaterTotterson/Tater.git

2. Navigate to the Project Directory

cd Tater

3. Run Tater Setup

Use the interactive setup menu to choose the right local runtime profile:

sh setup_tater.sh

The setup menu creates .venv, installs Tater's Python dependencies, and writes the selected runtime profile to .runtime/tater_profile.env.

Available local profiles:

• CPU: safe default for most local Linux installs and generic ARM hosts.
• macOS Apple Silicon: native Mac setup with Apple Metal/MPS for PyTorch-backed SpeechBrain and Kokoro when available, plus MLX Whisper for local STT.
• NVIDIA desktop/server: native amd64 CUDA setup for RTX/GTX machines.
• AMD ROCm / Strix Halo: native Linux setup for ROCm-capable Radeon and Ryzen AI Max / Strix Halo systems.
• Jetson: native ARM64 setup that uses JetPack/system AI packages and CUDA when compatible Python runtimes are installed.
• Jetson Thor: native ARM64 setup for Thor / JetPack 7 systems and CUDA 13-compatible JetPack runtimes.

Non-interactive setup is also available:

sh setup_tater.sh cpu
sh setup_tater.sh macos
sh setup_tater.sh nvidia
sh setup_tater.sh rocm
sh setup_tater.sh jetson
sh setup_tater.sh thor

Local Voice Acceleration Notes

The setup profile only prepares the runtime. Actual voice model choices are managed in TaterOS under Settings -> Models and Settings -> Voice Pipeline.

macOS Apple Silicon:

• The macOS profile writes PYTORCH_ENABLE_MPS_FALLBACK=1 so PyTorch can fall back to CPU for unsupported MPS operations.
• It attempts to install mlx-whisper and the official PyTorch kokoro package.
• It builds Tater's native llama.cpp engine (llama-server) with Metal when available; MLX LM remains the preferred Apple-native local LLM provider.
• Select Settings -> Models -> STT Backend -> MLX Whisper for Apple-native Whisper STT.
• MLX Whisper defaults to mlx-community/whisper-base.en-mlx; set TATER_MLX_WHISPER_MODEL to use another MLX Whisper model.
• Kokoro automatically uses the PyTorch engine on Apple Metal/MPS when available. Set TATER_KOKORO_ENGINE=onnx to force the existing ONNX path or TATER_KOKORO_ENGINE=torch to force PyTorch.

If native macOS dependency builds fail, install these Homebrew packages and rerun setup:

brew install ffmpeg cmake

Matrix encryption and embedded Redis are enabled by default. The macOS Apple Silicon setup includes bundled native wheels for python-olm and redislite so clean app installs do not need to compile those packages during first launch. Source installs on other macOS architectures may still need native build tools plus libolm and pkg-config.

AMD ROCm / Strix Halo:

• The ROCm setup detects Ryzen AI Max / Strix Halo systems and defaults both the llama.cpp target and speculative draft models to full GPU-layer offload. Other AMD and NVIDIA systems keep automatic placement.
• Set TATER_LLAMA_CPP_N_GPU_LAYERS=auto and TATER_LLAMA_CPP_DRAFT_N_GPU_LAYERS=auto to override the Strix Halo default, or use TATER_LLAMA_CPP_STRIX_HALO_FULL_OFFLOAD=0 when no explicit layer settings are present.

NVIDIA desktop/server:

• The nvidia profile installs CUDA PyTorch wheels, CUDA/cuDNN runtime packages, GPU ONNX Runtime, and builds Tater's native llama.cpp engine with CUDA.
• To customize the llama.cpp build, set TATER_LLAMA_CPP_CMAKE_ARGS before running setup. The NVIDIA profile defaults to -DGGML_CUDA=on.
• In TaterOS, use Settings -> Models -> Voice Acceleration to select Auto, CPU, NVIDIA CUDA, AMD ROCm, or Apple Metal/MPS where supported.
• Faster Whisper compute type defaults to Auto. Auto uses float16 on newer CUDA GPUs and switches to int8 on older CUDA cards such as Pascal / GTX 10-series, where float16 can fail.
• To override Faster Whisper compute type, use Settings -> Voice Pipeline -> Speech Recognition -> Faster Whisper Compute Type or set TATER_FASTER_WHISPER_COMPUTE_TYPE to auto, int8, float32, float16, int8_float32, or int8_float16.
• To restrict which GPUs native Tater can see, start it with CUDA_VISIBLE_DEVICES=0 sh run_ui.sh or use a GPU UUID.

AMD ROCm / Strix Halo:

• The rocm profile installs PyTorch from the ROCm wheel index, then installs Tater dependencies and the official PyTorch Kokoro package.
• Tater keeps the ROCm PyTorch wheel in place when installing dependencies so Hugging Face Transformers can use ROCm through PyTorch when the device is supported.
• AMD ROCm support is Linux-only and depends on the ROCm runtime installed for the GPU/APU.
• Tater uses ROCm for PyTorch-backed models such as Kokoro Torch and SpeechBrain Speaker ID / Emotion ID. PyTorch ROCm exposes devices through the cuda API internally, but Tater labels it separately as AMD ROCm in settings and logs.
• llama.cpp ROCm/HIP is built by setup with -DGGML_HIP=on by default. Override with TATER_LLAMA_CPP_CMAKE_ARGS if your ROCm stack needs a different llama.cpp flag.
• On Ubuntu 26.04 x86_64, setup detects the ROCm 7.2 linker issue involving the removed libxml2.so.2 ABI and places a checksum-verified compatibility library under the ignored .runtime directory for build use only. Set TATER_SETUP_ROCM_LIBXML2_COMPAT=0 to disable this workaround.
• Faster Whisper still falls back to CPU unless its CTranslate2 backend reports CUDA support; ROCm acceleration is not assumed for Faster Whisper.
• Strix Halo may require newer AMD ROCm wheels than the default PyTorch index. Override the PyTorch ROCm wheel source with TATER_ROCM_PYTORCH_INDEX_URL before running setup if needed.

Jetson and Thor:

• The jetson and thor profiles create a venv with --system-site-packages so NVIDIA JetPack-provided Python AI packages can be reused.
• Setup intentionally avoids replacing JetPack PyTorch with generic pip wheels.
• Hugging Face Transformers can use JetPack CUDA when the system PyTorch install exposes CUDA. Setup also attempts a native llama.cpp CUDA build for GGUF offload.

General voice notes:

• Tater warms selected local STT/TTS models at startup and after saving voice model settings. Set TATER_SPEECH_WARMUP_ON_STARTUP=false to disable startup warmup.
• Parakeet ONNX is available as a local multilingual STT backend on Linux, macOS, and Windows-compatible Python installs. Tater downloads the approximately 670 MB INT8 Parakeet TDT 0.6B v3 ONNX model on first selection, stores it under agent_lab/models/stt/parakeet_onnx, and uses the best available ONNX Runtime provider for the selected voice acceleration. The model is derived from NVIDIA Parakeet and is licensed under CC BY 4.0.
• Parakeet supports 25 European languages with automatic language detection, punctuation, and capitalization. Set TATER_PARAKEET_ONNX_QUANTIZATION=fp32 to use the much larger unquantized model instead of the default int8.
• Qwen3-ASR (llama.cpp, Experimental) runs the Qwen3-ASR 0.6B Q8 GGUF model in a dedicated instance of Tater's native llama-server. The model and audio projector download to agent_lab/models/stt/qwen3_asr_llama_cpp on first selection. This keeps STT independent of Tater's active llama.cpp chat model, but consumes additional memory while selected. Override the Hugging Face repository and filenames with TATER_QWEN3_ASR_LLAMA_CPP_REPO, TATER_QWEN3_ASR_LLAMA_CPP_MODEL_FILE, and TATER_QWEN3_ASR_LLAMA_CPP_MMPROJ_FILE.
• When the STT backend or voice acceleration changes, Tater releases obsolete local STT model caches before warming the newly selected engine.
• Kokoro and Pocket TTS output are boosted slightly by default for clearer satellite playback. Tune them in Settings -> Models -> Speech -> TTS, or override local runs with TATER_KOKORO_OUTPUT_GAIN / TATER_POCKET_TTS_OUTPUT_GAIN; both default to 1.5.
• Voice activity detection defaults to Silero VAD. Low-power hosts can switch the Voice Pipeline VAD backend to WebRTC, which uses webrtcvad-wheels.
• If Speaker ID or Emotion ID is enabled, SpeechBrain can use CUDA or MPS when supported, with CPU fallback.

Run the Web UI

Start the TaterOS backend/frontend:

sh run_ui.sh

If .venv exists, run_ui.sh uses it automatically. It also loads .runtime/tater_profile.env when present.

The launcher listens on 0.0.0.0:8501 by default. To change it, set HTMLUI_PORT:

HTMLUI_PORT=8601 sh run_ui.sh

Then open:

http://127.0.0.1:8501

Once the WebUI is up, continue to Post-Install Setup below.

Docker Installation

1. Pull the Image

Pull the prebuilt image with the following command:

docker pull ghcr.io/tatertotterson/tater:latest

2. Run Container

Recommended Docker networking:

• Use --network host so Tater shares the host network directly.
• Add --cap-add NET_BIND_SERVICE so Tater's shared AirPlay PTP clock can bind UDP 319/320 without requiring a privileged container user.
• This avoids managing a growing list of -p mappings for WebUI, voice, and other runtime surfaces.
• With host networking, Tater listens on the host directly, so you do not need to publish Tater ports manually.
• To change the WebUI port, set HTMLUI_PORT, for example -e HTMLUI_PORT=8601.
• If you are not using host networking, publish the same container port, for example -p 8601:8601.

Important for Docker persistence:

• Add a path mapping for /app/agent_lab (container) -> /mnt/user/appdata/tater/agent_lab (host example).
• Without this mapping, data in /agent_lab (logs/downloads/documents/workspace) can be lost on container rebuilds/updates.
• Add a path mapping for /app/.runtime (container) -> /mnt/user/appdata/tater/runtime (host example).
• Without this mapping, local runtime settings and Tater Native satellite pairing credentials can be lost on container rebuilds/updates.
• Both Docker images store native satellite credentials at /app/.runtime/native_satellite_credentials.json.

---

Example: Docker setup

docker run -d --name tater_webui \
  --network host \
  --cap-add NET_BIND_SERVICE \
  -e TZ=America/Chicago \
  -e HTMLUI_PORT=8501 \
  -v /etc/localtime:/etc/localtime:ro \
  -v /etc/timezone:/etc/timezone:ro \
  -v /agent_lab:/app/agent_lab \
  -v /tater_runtime:/app/.runtime \
  ghcr.io/tatertotterson/tater:latest

NVIDIA Docker

The NVIDIA image is amd64-only. Use the default latest image for CPU-first installs and ARM hosts. The NVIDIA image uses CUDA 12.8 PyTorch wheels, CUDA/cuDNN runtime packages, GPU ONNX Runtime, and a native CUDA llama.cpp engine for RTX 30, 40, and 50 series cards. Voice model tuning, Faster Whisper compute type, warmup, VAD, SpeechBrain acceleration, and llama.cpp GGUF offload use the same TaterOS settings described in Local Voice Acceleration Notes.

Host requirements:

• Install the NVIDIA driver.
• Install NVIDIA Container Toolkit before starting the compose override.
• The native CUDA llama.cpp engine needs libcuda.so.1, which is supplied by the host driver at container runtime. If diagnostics mention libcuda.so.1, the image built correctly but the container was not started with NVIDIA GPU access.

Optional NVIDIA GPU build for Faster Whisper STT plus Kokoro TTS:

docker compose -f docker-compose.yml -f docker-compose.nvidia.yml up --build

Prebuilt NVIDIA image:

docker pull ghcr.io/tatertotterson/tater:nvidia

To restrict which GPUs Tater can see in the NVIDIA compose setup, set NVIDIA_VISIBLE_DEVICES before launching, for example NVIDIA_VISIBLE_DEVICES=0 or a GPU UUID. Inside the container, CUDA device 0 maps to the first visible GPU.

Build and push the NVIDIA image:

docker buildx build \
  --platform linux/amd64 \
  -f Dockerfile.nvidia \
  -t ghcr.io/tatertotterson/tater:nvidia \
  --push .

3. Access the Web UI

Once the container is running with host networking, open your browser and navigate to:

• http://localhost:8501 from the same machine
• http://<host-ip>:8501 from another device on your network

If you changed HTMLUI_PORT, use that port in the URL.

Once the WebUI is up, continue to Post-Install Setup below.

---

Post-Install Setup

After Tater is running, open TaterOS and finish the first-run setup:

1. Configure your base model in Settings -> Models -> LLM / Vision:
   • choose OpenAI-Compatible API for Ollama, LM Studio, LocalAI, Lemonade, vLLM, or a hosted compatible API
   • choose Hugging Face Transformers to load a local model directly inside Tater
   • choose llama.cpp GGUF to load a GGUF model through Tater's native llama.cpp engine
   • choose MLX LM (Apple Silicon) to load an MLX model directly on an Apple Silicon Mac
   • for built-in local providers, download models from the Hugging Face mini-tab first, then select the downloaded model from the Settings mini-tab
   • for OpenAI-compatible providers, set the endpoint host/port and model name
2. Optional:
   • add more Base servers for round-robin regular AI calls
   • enable Beast Mode and set per-head model settings for Astraeus/Hermes

Hydra model settings are saved by TaterOS and used at runtime. Base, Spudex, Beast Mode routing, and Vision can each use the selected built-in local providers or OpenAI-compatible providers.

Local Models

• Download local Hugging Face Transformers, llama.cpp GGUF, or MLX models from the Hugging Face mini-tab first, then select them from Settings.
• Model caches live under agent_lab/models/llm/ by default:
  • huggingface for Transformers
  • llama-cpp for GGUF models and matching mmproj*.gguf vision projectors
  • mlx for MLX text and vision models
• The Hugging Face browser uses the token saved in Integration Manager -> Hugging Face for private/gated models and better Hub rate limits.
• llama.cpp uses the native llama-server engine built by setup. It uses GPU offload by default when the installed build supports it. Set TATER_LLAMA_CPP_N_GPU_LAYERS=0 for CPU-only or TATER_LLAMA_CPP_SERVER_BIN to point at a custom llama-server binary.
• MLX is intended for Apple Silicon Macs. Use llama.cpp GGUF on Linux, Raspberry Pi, NVIDIA, AMD/ROCm, Jetson, or other non-Apple-Silicon devices.

Vision

• Vision can use an OpenAI-compatible API, the loaded Base model, or a dedicated local vision model.
• If Base is already loaded and vision-capable, Tater reuses it instead of loading the same model twice.
• Dedicated vision models are managed separately from Base.

Advanced Notes

• Local context length is configured in Settings -> Models -> LLM / Vision.
• Thinking suppression is enabled by default for local providers when supported.
• run_ui.sh starts Uvicorn with --no-access-log to suppress per-request log spam. Shutdown waits at most eight seconds for long-lived WebSocket and event-stream connections before cancelling them, so a stale satellite or browser connection cannot block a restart. Set HTMLUI_GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS to override that connection-drain deadline.