Tater Assistant Docs
Portal profile

macOS

Native desktop portal used by the Tater Menu status-bar app for chat, quick actions, notification polling, and attachment workflows.

Desktop endpoint Version unknown No settings form 41 Verbas
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.
Settings

Configuration schema

This portal does not expose a standalone PORTAL_SETTINGS form in the current source snapshot.

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 Tater Voice Cores Home