Tater Assistant logo Tater Assistant Source-backed docs
Portal profile

macOS

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

Desktop endpoint v1.0.2 5 settings 65 Verbas
Runtime role

What this surface is for

Desktop endpoint

Highlights

Behavior in the current codebase

  • Runs a FastAPI bridge on port 8791 by default 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

  • 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
  • Bind Port number

    TCP port for the Tater macOS bridge.

    Key: bind_port Default: 8791
Client app

macOS app that connects to this bridge.

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

Status bar appPort 8791Quick actions

Tater Menu (macOS app)

Lightweight menu-bar app that connects to the Tater macOS bridge 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, optional API key/Auth Token, and Quick Action Plugin from the app Settings menu.
  • 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 bridge endpoints.

Server URLAuth tokenBootstrap

First connection

Point the app at the macOS bridge and verify bootstrap and polling are healthy.

  • Default bridge URL is http://127.0.0.1:8791, 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 bridge.

Returns ok, platform=macos, and version 1.0 so clients can confirm the bridge 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 Cores Home