Tater
Docker app from grtgbln's Repository
A Local AI LLM Assistant With Tools and Integrations for Home Assistant, HomeKit, XBMC, Discord, Matrix, IRC, and Automations
Requirements
Requires a separate OpenAI-compatible LLM instance and Redis instance.
Overview
Readme
View on GitHubTater is a local-first AI platform that can run local models through llama.cpp, or connect to remote OpenAI-compatible and llama.cpp 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.
New in 3.0.8: Satellite diagnostics refresh live network and wake status, including USB Ethernet with Tater Native Firmware 0.7.0 on all four ESP32 satellite targets. The tested powered adapter also works with supported Echo satellites; see Ethernet and PoE adapters. Read the release notes.
Little Spud Companion App
Little Spud connects to your Tater Spud Hub for chat, TTS, STT, and notifications from your iOS or Android device.
Download Little Spud on the App Store
Download Little Spud on Google Play
Tater Voice Satellites
Bring Tater into every room with a dedicated voice satellite. Choose the firmware for your hardware, then pair and manage it in Voice & devices → Satellites.
| Your hardware | Firmware or runtime |
|---|---|
| Voice PE, Satellite1, ReSpeaker XVF3800 or ESP32-S3-BOX-3 | Tater Native Firmware |
| Supported, unlocked Amazon Echo, Dot, Show or Spot | Tater Echo Firmware |
| Linux computer or Raspberry Pi with a microphone and speaker | Tater Linux Satellite |
| ThirdReality Voice & Music Assistant (S420) | Tater ThirdReality Voice Firmware |
Ethernet and PoE adapters
Both Tater Echo Firmware and Tater Native Firmware support USB Ethernet on compatible hardware. The tested powered adapter is the UCTRONICS B0B9ZLVGJ4 (U6113). It carries Ethernet data over USB and can supply 5 V device power from a compatible PoE switch/injector. A power-only PoE splitter does not provide USB Ethernet data. For the native USB-C boards, add a data-capable Micro-USB female → USB-C male converter.
| Satellite | Connection and support |
|---|---|
| SAT1, Voice PE, ReSpeaker XVF3800, and ESP32-S3-BOX-3 | Use Native Firmware 0.7.0+ and a data-capable Micro-USB female → USB-C male converter. Connect to the ESP32 USB port (the XIAO port on ReSpeaker, not a separate XMOS USB audio port), then cold boot through the powered adapter. |
| Supported Echo satellites | The same adapter was tested on Biscuit, Checkers, Cronos, Crown, Athena, and Rook. Biscuit can receive power through it; the other listed models retain their normal power supplies. Follow the Echo adapter and per-device instructions. |
Native firmware currently accepts only RTL8152 adapters exposing USB
0bda:8152 with CDC-ECM configuration 2. Similar powered adapters may work
but are untested; other chipsets are not enabled. Echo uses its own Linux
drivers and per-device requirements, so compatibility on Echo does not establish
compatibility on ESP32. A USB-C plug, higher wattage, or a chipset name alone
is not enough to establish compatibility.
On all four native targets, Ethernet takes priority after DHCP while saved Wi-Fi remains available as fallback. Tater 3.0.8+ shows Connected by USB Ethernet in satellite diagnostics on its normal refresh. The same USB port preserves serial when booted directly on a computer; reboot through the adapter for Ethernet. The tested adapter supplies 5 V, so allow for the board's speaker power requirements; it does not enable SAT1's higher-voltage amplifier modes. See the Native Ethernet setup and recovery guide for details and remaining hardware test limits.
Using Home Assistant? The Home Assistant bridge supports HA Assist and optional Mini-Tater without needing the main Tater app.
Installation
Choose the installation that matches your system:
- macOS app, Unraid, and Home Assistant provide guided installation options.
- Docker is the easiest choice for most other Linux servers.
- Local installation is best when you want direct access to the hardware and Python environment.
Model note: Tater is designed around local models and local OpenAI-compatible servers such as Ollama, LM Studio, LocalAI, and Lemonade.
macOS App Installation
Download the latest macOS installer
Install Tater
Open the DMG, then drag Tater.app into Applications.
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_labdata there. It does not use this source checkout's.venv,.runtime, oragent_labfolders. The app also includes the pinned AirPlay sender and receiver, and its startup environment check repairs any missing Python-side AirPlay support automatically.Finish setup in TaterOS
The app listens on
0.0.0.0:8501and opens127.0.0.1:8501in 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_laband/app/.runtimeto persistent, preferably cache-backed storage. - Also set
TZand map/etc/localtimeplus/etc/timezoneif 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:
Add Repository to Home Assistant
Once added, the Tater AI Assistant add-on will appear in the Home Assistant Add-on Store.
Install order:
- Install Tater AI Assistant.
- Configure your LLM settings in the Tater add-on.
- Start Tater.
Once the add-ons are running, continue to Post-Install Setup below.
Reachy Mini Installation
Install Reachy Tater Satellite
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:
- Install Reachy Tater Satellite from the Reachy Mini app store and start it.
- Open the app settings from Reachy's web interface and enter the address of your running Tater server.
- Create a satellite pairing code in Tater, enter it once in the Reachy settings, and save the connection.
- Optionally enable Allow vision snapshots for the Reachy Vision Verba, then say Hey Reachy.
Docker Installation
Use this method on a Linux server with Docker installed.
1. Create persistent storage
Run these commands from the directory where you want to keep Tater's data:
mkdir -p tater-data/agent_lab tater-data/runtime
agent_labstores models, documents, logs, and Tater's internal Redis data.runtimestores settings and native satellite pairing credentials.
Keep both directories when you update or recreate the container. Fast local storage is recommended; avoid network-mounted or unusually slow storage for agent_lab.
2. Start Tater
docker pull ghcr.io/tatertotterson/tater:latest
docker run -d --name tater_webui \
--restart unless-stopped \
--network host \
--cap-add NET_BIND_SERVICE \
-e TZ=America/Chicago \
-e HTMLUI_PORT=8501 \
-v "$(pwd)/tater-data/agent_lab:/app/agent_lab" \
-v "$(pwd)/tater-data/runtime:/app/.runtime" \
ghcr.io/tatertotterson/tater:latest
Change TZ if needed. Tater uses host networking for WebUI, voice, discovery, and media services.
3. Open TaterOS
Open one of these addresses:
- http://localhost:8501 on the server
http://<server-ip>:8501from another device on the same network
If port 8501 is already in use, change HTMLUI_PORT in the command. Continue to Post-Install Setup after TaterOS opens.
NVIDIA Docker
The NVIDIA image is available for amd64 systems with an NVIDIA driver and NVIDIA Container Toolkit installed:
docker pull ghcr.io/tatertotterson/tater:nvidia
Use the Docker command above, add --gpus all, and replace the final image name with ghcr.io/tatertotterson/tater:nvidia.
Local Installation
Use this method on Linux or macOS when you want Tater to run directly on the host.
1. Download Tater
git clone https://github.com/TaterTotterson/Tater.git
cd Tater
2. Run setup
sh setup_tater.sh
The setup menu asks which runtime fits your system, creates .venv, installs dependencies, and saves the selected profile. Tater supports Python 3.11 through 3.13; on supported Linux systems, setup can install a private Python runtime when the system version is unsuitable.
| Profile | Choose it for |
|---|---|
| CPU | Most Linux PCs and generic ARM systems |
| macOS | Apple Silicon Macs |
| NVIDIA | Linux PCs and servers with NVIDIA GPUs |
| AMD ROCm | Supported Linux systems with AMD GPUs or Ryzen AI |
| Jetson | NVIDIA Jetson systems |
| Thor | Jetson Thor systems |
| Edge | Pi-class or remote-only systems that connect to a Spud Hub |
To skip the menu, pass the profile name directly—for example:
sh setup_tater.sh cpu
The Edge profile requires the operating system's redis-server package. If macOS setup reports missing build tools, install ffmpeg and cmake with Homebrew and rerun setup.
3. Start Tater
sh run_ui.sh
Tater listens on 0.0.0.0:8501 by default. Open http://localhost:8501, or use http://<computer-ip>:8501 from another device. To use a different port:
HTMLUI_PORT=8601 sh run_ui.sh
Continue to Post-Install Setup after TaterOS opens. Model downloads and voice acceleration are configured inside TaterOS under Settings -> Models and Settings -> Voice Pipeline.
Post-Install Setup
After Tater is running, open TaterOS and finish the first-run setup:
- Configure your base model in Settings -> Models -> LLM / Vision:
- choose
OpenAI-Compatible APIfor a local server such as Ollama, LM Studio, LocalAI, Lemonade, or vLLM - choose
llama.cpp GGUFto load a GGUF model through Tater's native llama.cpp engine - for built-in local models, download llama.cpp GGUF models from the Models tab first, then select a downloaded model in the LLM tab
- for OpenAI-compatible providers, set the endpoint host/port and model name
- choose
- Optional:
- add more Base servers for round-robin regular AI calls
- enable
Beast Modeand set per-head model settings for Astraeus/Hermes
Hydra model settings are saved by TaterOS and used at runtime. Base, Terminal, Beast Mode routing, and Vision can each use llama.cpp or a configured remote provider.
Local Models
- Use the Models tab to download llama.cpp GGUF files from Hugging Face. The LLM tab lists downloaded models only.
- Model caches live under
agent_lab/models/llm/by default:llama-cppfor GGUF models and matchingmmproj*.ggufvision projectors
- 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-serverengine built by setup. It uses GPU offload by default when the installed build supports it. SetTATER_LLAMA_CPP_N_GPU_LAYERS=0for CPU-only orTATER_LLAMA_CPP_SERVER_BINto point at a custom llama-server binary.
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.
Satellite Displays
Updated Echo GPU screens expose Conversation Text under each satellite's Display → Appearance & Photos settings: Smooth (default) or Matrix symbol cycling for recognized speech and replies. This is a per-satellite choice, including changes made on its touchscreen, not a shared voice default. The selector appears only when the satellite advertises support for it.
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.shstarts Uvicorn with--no-access-logto 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. SetHTMLUI_GRACEFUL_SHUTDOWN_TIMEOUT_SECONDSto override that connection-drain deadline.
Development layout
Python implementations are grouped by feature under tater/, alongside the
existing Hydra, voice, notification, and Spudex packages. Small root forwarding
modules preserve the import names used by installed Cores, Portals, and Verbas.
See Python application layout for the package map,
compatibility rules, and validation commands.
License and trademarks
This project is licensed under the GNU Affero General Public License v3.0.
The Tater name and logo are governed by the Tater Trademark Policy.
Categories
Related apps
Explore more like this
Explore allLinks
Details
ghcr.io/tatertotterson/tater:latestRuntime arguments
- Web UI
http://[IP]:[PORT:8501]/- Network
host- Shell
sh- Privileged
- false
Template configuration
Path to the Agent Lab config data
- Target
- /app/agent_lab
- Default
- /mnt/user/appdata/tater/agent_lab
- Value
- /mnt/user/appdata/tater/agent_lab
Path to the runtime data
- Target
- /app/.runtime
- Default
- /mnt/user/appdata/tater/runtime
- Value
- /mnt/user/appdata/tater/runtime