Tater Assistant

Portal role

What this portal is for

Desktop endpoint

Highlights

Behavior in the current codebase

Mounts /macos/... routes under the main Tater WebUI/API port for the Tater Menu app.
Maintains scoped session history with configurable limits and TTL so desktop context stays stable but bounded.
Supports long-poll notifications plus tool_wait status handling for menu-app feedback loops.
Includes asset upload and download endpoints for screen captures, clipboard artifacts, and returned files.
Supports optional API key protection through the X-Tater-Token header.

Related Verbas

Direct portal support

67 current Verbas advertise direct support for this portal.

Aladdin Connect Automatic1111 Image Broadcast ComfyUI Animate Image ComfyUI Audio Ace ComfyUI Image

Settings

Configuration schema

Require API Key select
Require X-Tater-Token on macOS portal API requests.
Key: API_AUTH_ENABLED Default: false Options: true, false
API Key password
Shared API key expected in the X-Tater-Token header when auth is enabled.
Key: API_AUTH_KEY
Legacy Auth Token (optional) password
Backward-compatible fallback token if API Key is empty.
Key: AUTH_TOKEN
Session TTL select
How long to keep a Mac conversation history alive.
Key: SESSION_TTL_SECONDS Default: 2h Options: 5m, 30m, 1h, 2h, 6h, 24h
Legacy Bind Port number
Deprecated. macOS now uses Tater's main API path: /api/portals/macos_portal/api/macos
Key: bind_port Default: 8791

Client app

macOS app that connects to these Tater routes.

The menu-bar app is the main user-facing client for this portal and handles quick actions, chat UI, and attachment flows.

Status bar appMain Tater portQuick actions

Tater Menu (macOS app)

Lightweight menu-bar app that connects to Tater's built-in macOS routes for chat, quick actions, clipboard workflows, screen captures, and attachment handling.

Install with python3.11 -m pip install -e . inside the Tater-MacOS repo, then run python3.11 tater_menu.py.
It can also run in the background with python3.11 tater_menu.py --background and stays as a menu-bar-only app.
Set Server URL to the main Tater URL, for example http://127.0.0.1:8501, plus optional API key/Auth Token and Quick Action Plugin from the app Settings menu.
The app uses /macos/... routes mounted inside Tater instead of a separate desktop bridge port.
The local config is stored at ~/Library/Application Support/TaterMenu/config.json.

Tater-MacOS Repo

App setup

How to run and connect the Tater Menu app.

These notes are based on the current Tater-MacOS app README and the active macOS routes.

Server URLAuth tokenBootstrap

First connection

Point the app at the main Tater URL and verify bootstrap and polling are healthy.

Default Tater URL is http://127.0.0.1:8501, but the app can target any reachable Tater host.
If API auth is enabled in macOS portal settings, the app must send the same API key in X-Tater-Token.
The app bootstraps assistant identity and recent history from /macos/bootstrap before normal chat usage.

/macos/plugin/macos/chatPlugin fallback

Quick actions

Clipboard and screen presets call the plugin endpoint first, then fall back to chat when needed.

Quick actions are sent to /macos/plugin with a configured plugin name, defaulting to macos_quick_action.
If plugin handling fails or is unavailable, the app can fall back to /macos/chat for normal assistant handling.
This keeps menu actions fast while still allowing broader Hydra-driven behavior when needed.

Screen RecordingAccessibilityApple Events

Permissions

Screen and rewrite flows depend on standard macOS privacy permissions.

Screen capture tools require macOS Screen Recording permission for the Python process or packaged app.
Rewrite selected text relies on Accessibility permission because it drives keystrokes with AppleScript.
Frontmost-app context and rewrite flows can also require Apple Events access depending on target apps.

/macos/notifications/nextAssetsDownloads

Notifications and attachments

The app long-polls notifications and can download or auto-open returned attachments.

The client polls /macos/notifications/next for queued notices, including tool_wait status updates.
Returned artifacts are exposed through /macos/asset/{asset_id} download URLs scoped to the active device or session.
Image attachments from direct actions can be opened automatically, while other files are saved in app-support downloads.

Built-in APIs

HTTP endpoints exposed by this portal.

API auth

When API auth is enabled, requests must include X-Tater-Token with the configured portal API key.

GET /macos/health

Health check for the desktop portal.

Returns ok, platform=macos, and version 1.0 so clients can confirm the route is alive.

GET /macos/bootstrap

Bootstrap assistant identity and recent history.

Returns assistant identity plus recent scoped history so the menu app can initialize quickly.

GET /macos/notifications/next

Long-poll next queued notification item.

Polls scoped notification queues with optional wait_seconds and returns the next pending notification payload.

POST /macos/chat

Main macOS chat endpoint.

Accepts user_text, clipboard context, optional assets, and scope/device context, then runs a Hydra turn.

POST /macos/plugin

Direct plugin call path for quick actions.

Executes a named plugin with args for deterministic quick-action flows, then returns narrated text plus attachments/actions.

POST /macos/asset

Upload one client asset into scoped artifact storage.

Stores an incoming asset payload and returns an attachment-ready artifact reference for later use.

GET /macos/asset/{asset_id}

Download a scoped artifact by asset_id.

Returns raw file bytes for stored artifacts so the app can save or open returned attachments.

GET /macos/history

Fetch scoped conversation history.

Returns client-safe history entries for a scope or device with server-side cap enforcement.

GET /macos/assistant

Fetch assistant identity metadata.

Returns assistant display-name identity data for app UI labels and chat headers.

Back to portals Verbas Portals ESPHome Cores Home