WatchMuse
Download
WatchMuse help center

Help with WatchMuse.

Set up chat on Mac, iPhone, iPad and Apple Watch, connect to Mac local AI, or use a compatible custom server.

Released app · App StoreMac beta
APPLE WATCH / HRV

HRV on Apple Watch, explained.

Understand the measurement, your personal baseline and the rules behind the stress estimate. Try the calculation with fictional values.

Explore HRV
Quick start

From setup to first answer.

Cloud AI needs internet; some providers require your API key. A downloaded, supported local model can run on its host device without cloud AI. Mac local AI still needs a working connection to your Mac. Model downloads need internet.

Core chat on Mac, iPhone and iPad does not require an Apple Watch. Mac does not include Mood or weather.

Set up Mac local AI

Send images with Base64 ↓

01 / Provider

Choose a service

On Mac, open Settings → undefined for your own provider, or Local AI for downloaded models. On iPhone/iPad, use Settings → undefined, Local AI Beta or Local AI on Mac.

02 / Setup

Finish setup

Enter only what the chosen service requires. Mac Custom Server uses a compatible HTTPS address without a key or model field. Built-in Qwen is a separate online service with usage limits.

03 / Chat

Send a short question

Choose the service in chat and send a brief text message first. Images require a compatible provider and model; the Mac device connection currently accepts text only.

Choose where your answer comes from.

Built-in Qwen
An online service operated for WatchMuse, with its own access and usage limits. Separate from downloadable Qwen models.
On-device AI
A supported, downloaded model runs on the current device. Downloading needs internet; local inference does not call a cloud AI service.
Local AI on Mac
Your device sends the request to your paired Mac. A reachable network connection is still required.
Your own API
Use your configured provider and model. Requests go to that service; its key, billing and usage rules apply.
Custom Server
Use a compatible HTTPS endpoint. On Mac, no API key or model selection is required in this option; your server chooses the model. This is separate from Mac device access.
MAC / LOCAL AI

Use your Mac’s local AI from another device.

Mac feature preview · checked against current source on October 4, 2026. This is not confirmation that a Mac build is available in TestFlight.

The model is downloaded to and runs on your Mac. Your iPhone or iPad sends the current request and the context included by your chat settings. Mac returns the answer; it does not transfer model files to your other devices.

  1. iPhone / iPad
  2. Encrypted connection · TCP/TLS
  3. Local model on Mac
  4. Answer returned
  1. Apple Watch
  2. Paired iPhone
  3. Encrypted connection · TCP/TLS
  4. Local model on Mac
  5. Answer returned

Pair your devices

  1. On Mac, open Settings → Local AI. Download a supported model, wait for verification to finish, then choose Use This Model. Selecting a model in the catalogue is not the same as activating it.
  2. Open Settings → Your Devices and enable Allow Device Access. Wait for Ready for your devices, then choose Copy Pairing Code. An enabled switch alone does not mean the service is ready.
  3. On iPhone/iPad, open Settings → Local AI on Mac (the page is titled Mac Connection). Paste the code and choose Pair Mac. You can also reach it from Local AI Beta → Use Local AI on Mac.
  4. Enable Use Mac for Local AI, select Local AI in chat, and send a short question. Refresh Model reads the model selected on Mac; change that model on the Mac itself.

Apple Watch goes through iPhone

  1. Pair the Mac on the Watch’s paired iPhone first. In iPhone Settings → Local AI Beta, enable Allow Apple Watch to Use Local AI. Keep iPhone nearby and connected to Mac.
  2. On Watch, choose Local AI in the AI provider settings. In its model/device choices, select Local AI on Mac; if it is missing, use Refresh Model. Alternatively, choose Follow iPhone while iPhone has Use Mac for Local AI enabled.
  3. The model is selected on Mac, not downloaded to Watch. If a request is interrupted, open WatchMuse on iPhone and retry a short question. iOS and watchOS can limit background work; forwarding cannot continue indefinitely.

A private connection, not a public AI API

Use the same local network, or a private VPN you have already configured to reach the Mac. WatchMuse does not set up a public relay. The device connection uses authenticated TCP/TLS, not HTTP.

The pairing code includes the address, port and authentication secret. Treat it like a password and share it only with your own devices. Normal pairing does not require entering a port manually.

To change the port, turn device access off on Mac, save a port from 1024 to 65535, then turn access on again. Copy the new code and pair each device again.

Do not forward the port to the public internet. Keep authentication and encryption enabled. If a .local name is not reachable over your private VPN, Mac Connection offers an advanced address setting for a reachable private Mac address.

Using the same Apple ID does not establish this connection. iCloud chat sync and Mac AI pairing are separate.

Keep the Mac available

Mac must be powered on, awake and running WatchMuse. Closing its window keeps device access running in the menu bar. Quitting the App stops the service.

WatchMuse remembers the access switch and tries to restore the service when you reopen the App. There is no independent service running after you quit. Check the ready status after every restart or failure.

This connection currently handles text only, including any text context prepared by your chat settings. Local image support on Mac does not mean images can be sent through this connection. There is no automatic cloud AI fallback.

Only one local generation runs at a time. A download, verification or another local answer can make the Mac busy; requests may be rejected rather than queued. Long requests can time out.

Speed depends on hardware, model size, available memory and other work on the Mac. Memory guidance is not a performance guarantee. Start with a smaller supported model if resources are limited.

Chat sync is separate

Mac Settings → General → Sync conversations with iCloud is optional. It uses the shared chat archive; enable chat backups on the other devices too. A signed build with the iCloud capability and a working iCloud account is required.

The chat archive includes saved messages and attachments, quotes or extracted document text stored with them. It does not sync model files, API keys or Mac pairing secrets. Configure these on each device.

Turning sync off stops future sync; it does not automatically erase existing cloud data. Chat sync is not guaranteed to be immediate, and does not replace a working network connection to Mac.

Mac connection help

01There is no pairing code

Accept the App’s terms, enable device access, and read the service status. The code appears only when the listener is ready. If startup fails, check local-network permission, port conflicts and Keychain access. A signing or application-identity change can affect access to saved credentials; use the intended signed build.

02It paired, but cannot connect

Pairing saves the connection details; it is not a connectivity test. Confirm Mac is awake, WatchMuse is running, the service is ready, and both devices can reach each other on the LAN or private VPN. Check App-specific local-network and firewall permissions, without disabling the firewall. Recheck the address and port; use a new code if they changed.

03It stopped after Mac slept or I quit

Wake the Mac and reopen WatchMuse. Wait for the device service to be ready, then retry. Closing the window is different from quitting the App.

04Changing the port broke the connection

Stop device access, save the new port, restart access, then pair each client with the new code. The old code still contains the old port.

05A downloaded model cannot be selected

Wait for downloads, verification and generation to finish. Confirm all required files are present in the current LocalAI folder and any model terms have been accepted, then choose Use This Model. Check the displayed error; downloading does not automatically make a model active.

06Models or settings disappeared after an update

Check that you opened the intended signed App and application identity. A different identifier can use a different container, preferences and Keychain access. In Mac Settings → General, the current build offers “Recover Previous Data”, “Import Downloaded Models…” and “Import Previous Settings…”. These labels may still be in English. Choose the old LocalAI folder or preferences file; model files are verified and copied, not moved. Passwords and permissions are not imported. Restart after importing settings. Do not delete the old data first.

07Mac is answering another request

Wait for the current local answer, download or verification to finish. Avoid repeated retries from multiple devices. If the request times out, try a shorter question or smaller model.

08Watch cannot use Mac AI

First test a text question from the paired iPhone. Check its Mac pairing and Apple Watch access switch. On Watch, refresh model information and choose Mac, or follow iPhone’s Mac route. Keep iPhone nearby and reopen WatchMuse on it if background forwarding was interrupted. No model download to Watch is needed.

Providers & models

Set up your AI provider.

Configure a cloud provider below, or use the local AI guide above. Keys apply only to providers that require them. Model availability differs by platform and version; check the list in your App.

ProviderSetupApp default / model choice
Qwen AI 千问 AIAn online service operated for WatchMuse, with its own access and usage limits. Separate from downloadable Qwen models.Determined by the WatchMuse server.
OpenAICreate an API key following OpenAI’s official guide, then enter it in the app.OpenAI key guide See the model choices in your App; defaults may differ between Mac and mobile.
GeminiCreate an API key in Google AI Studio, then enter it in the app.Gemini key guide See the model choices in your App; defaults may differ between Mac and mobile.
DeepSeekApply for an API key on the DeepSeek platform, then enter it in the app.DeepSeek key guide See the model choices in your App; defaults may differ between Mac and mobile.
ClaudeCreate an API key in Claude Console, then enter it in the app.Claude key guide See the model choices in your App; defaults may differ between Mac and mobile.
Perplexity SonarCreate an API key in Perplexity API Console, then enter it in the app.Sonar key guide See the model choices in your App; defaults may differ between Mac and mobile.
OpenRouterCreate one OpenRouter API key, then choose a model from the app’s model list. You do not need a separate key for every other platform.OpenRouter key guide See the model choices in your App; defaults may differ between Mac and mobile.
Custom ServerEnter your complete HTTPS endpoint URL. It must accept the app’s request and return the expected response—not just display a web page.View the endpoint format Determined by your own server.

Model availability, image support, limits, and charges depend on the selected service, model, and account. Check the app’s model list and the provider’s current documentation. Enter keys only in the app—this website never asks you to submit an API key.

APPLE WATCH

Troubleshooting

Common questions.

Choose a question to see what to check.

01The AI request fails or returns no answer
  • Confirm the Apple Watch has Wi-Fi or a working connection through its paired iPhone.
  • Check the selected provider, API key, model name, and account quota.
  • For a custom server, confirm the endpoint uses HTTPS, accepts POST requests, and returns the expected JSON.
  • Try a short text-only message to separate connection problems from image or context limits.
02The answer disappears after leaving the app

Keep Reply Notifications enabled in Settings → AI & Chat. watchOS decides how long networking and background work can continue, so a suspended or terminated app cannot guarantee every long request will finish. Reopen the conversation to check its saved state.

03Weather words cannot use the current location

Enable Location Services for WatchMuse and try Update Current Location again. If Apple Weather is temporarily unavailable, WatchMuse can use Open-Meteo when that fallback is enabled. You can also enter a city manually.

04HRV does not update

Allow Health read access and confirm Apple Watch has a recent HRV sample. WatchMuse reads the latest measurement already saved by Apple Watch; it cannot force a new HRV measurement. The wellness stage is informational and is not a medical diagnosis.

Why your HRV measurement time matters ↗

05A complication is blank or out of date

Open WatchMuse once after installing or updating it, confirm the relevant Mood, Stress, or Weather feature is enabled, and wait for watchOS to refresh the timeline. If needed, remove the complication from the watch face and add it again.

06Notifications do not arrive

Check notification permission in watchOS Settings and confirm the corresponding alert is enabled inside WatchMuse. Sleep protection may intentionally pause mood alerts, and watchOS may delay background schedules to preserve battery.

For custom servers

Connect your own server.

WatchMuse can use Ollama, a self-hosted model, or any cloud model through one compatible HTTPS endpoint. Your server translates WatchMuse's simple request into the format expected by your model.

Use a compatible HTTPS endpoint. On Mac, no API key or model selection is required in this option; your server chooses the model. This is separate from Mac device access.

Enter the endpoint URL itself, not an Ollama dashboard or model page. WatchMuse sends an HTTP POST request with UTF-8 JSON and the question in message. Without an attachment, your server should accept image fields that are either null or omitted.

Your endpoint must return a successful 2xx response, Content-Type: application/json, and a non-empty reply string before the request times out.

  • MethodPOST
  • TransportHTTPS
  • Request typeapplication/json
  • Response typeapplication/json
  • Required responsereply: string
  • Recommended response timeUnder 60 seconds
RequestJSON
{
  "message": "Hello",
  "imageBase64": null,
  "mimeType": null
}
ResponseJSON
{
  "reply": "Hello from your model."
}

Send images with Base64

In a chat interface that supports attachments, choose an image and enter your question; the app handles the encoding. Do not paste a Base64 string into the regular chat field. The instructions below are for building or testing a custom-server endpoint.

Base64 turns the bytes of an image file into text that can be included in JSON. It is not an image URL or a file path.

  1. Encode the image file itself and put the full result in imageBase64. Omit any prefix such as data:image/jpeg;base64, and do not insert line breaks or ellipses.
  2. Set mimeType to the actual format: image/jpeg for JPEG, or image/png for PNG. Changing the file extension or MIME label does not convert the image.
  3. Put the question in message and send the fields as application/json to your HTTPS endpoint. Your server then adapts the request to the selected model’s API.
Image request exampleJSON
{
  "message": "What is in this image?",
  "imageBase64": "REPLACE_WITH_FULL_BASE64",
  "mimeType": "image/jpeg"
}

REPLACE_WITH_FULL_BASE64 is a placeholder. Replace it with the image’s complete Base64 data before sending; do not send the placeholder itself.

Generate Base64 on your computer

These commands read a local image and print its encoding; they do not upload the file. Replace the path with your image’s path, then put the output in imageBase64.

macOS
base64 -i "/path/to/photo.jpg" | tr -d '\r\n'
Windows PowerShell
[Convert]::ToBase64String([System.IO.File]::ReadAllBytes("C:\path\to\photo.jpg"))

Text works, but images do not?

  • Check that both the server and the model accept images. Base64 is a transport format; it does not give a text-only model vision capabilities.
  • Check for incomplete data, an unwanted data: prefix or a mismatched mimeType. The server should validate the actual file content, not just trust its MIME label.
  • Base64 increases the request size. For a 413 response or an image-too-large error, resize or compress the image and check the gateway, server and model limits. The 20 MB setting in the gateway example below is not a universal WatchMuse upload limit.

The Ollama gateway below uses qwen2.5 as a text-model example. To test images, select an installed model that supports image input. Ollama image input documentation ↗

Base64 is not encryption. Use HTTPS, and encode private images locally instead of uploading them to an untrusted conversion website.

In the app

Add the endpoint.

  1. On Mac: Settings → undefined → Custom Server. On iPhone/iPad: Settings → undefined. On Apple Watch: Settings → AI Provider → Custom Server. Enter the full compatible HTTPS URL, including its path. This is not the Mac pairing page.
Request fields

What your server receives.

  • message — required string containing the user's prompt and, when enabled, prepared conversation context.
  • imageBase64 — Complete Base64 image data without a data-URL prefix; null or omitted when no image is attached.
  • mimeType — The actual image format, such as image/jpeg or image/png; null or omitted when no image is attached.
  • Unknown future fields should be ignored so your endpoint remains compatible.
Response

Send a complete response.

  • Use an HTTP status from 200 through 299 for success.
  • Return valid JSON with one non-empty string named reply.
  • Do not stream partial JSON. Collect the model output, then send one complete response.
  • For failures, return an appropriate 4xx or 5xx status and log the internal reason on your server.
Network

Make it reachable from Apple Watch.

  • Use a valid HTTPS certificate trusted by Apple devices.
  • The endpoint must be reachable outside your home network unless the Watch is on the same accessible network.
  • Do not expose Ollama's native port directly to the internet. Put a small HTTPS gateway in front of it.
  • CORS headers are not required because WatchMuse is a native app, not a browser page.
Compatibility testcurl
curl -X POST "https://your-domain.example/watch-ai" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "message": "Reply with the word ready.",
    "imageBase64": null,
    "mimeType": null
  }'
Expected bodyJSON
{ "reply": "ready" }
Ollama gatewayNode.js / Express
import express from "express";

const app = express();
app.use(express.json({ limit: "20mb" }));

app.post("/watch-ai", async (request, response) => {
  const { message, imageBase64, mimeType } = request.body ?? {};

  if (typeof message !== "string" || !message.trim()) {
    return response.status(400).json({ error: "message is required" });
  }

  const userMessage = { role: "user", content: message };
  if (imageBase64 && mimeType?.startsWith("image/")) {
    userMessage.images = [imageBase64];
  }

  try {
    const ollamaResponse = await fetch("http://127.0.0.1:11434/api/chat", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        model: "qwen2.5",
        messages: [userMessage],
        stream: false
      })
    });

    if (!ollamaResponse.ok) {
      return response.status(502).json({ error: "Model request failed" });
    }

    const result = await ollamaResponse.json();
    const reply = result?.message?.content?.trim();
    if (!reply) {
      return response.status(502).json({ error: "Model returned no answer" });
    }

    return response.json({ reply });
  } catch {
    return response.status(503).json({ error: "Model is unavailable" });
  }
});

app.listen(3000, "127.0.0.1");
Security: WatchMuse currently sends the three JSON fields shown above and does not add a custom Authorization header. Protect the public gateway with rate limits, request-size limits, server-side secrets, abuse monitoring, and an unguessable endpoint when appropriate. Never place an Ollama port, model credentials, or an unrestricted proxy directly on the public internet. Anyone who controls a custom endpoint can receive the prompts and images sent to it.
Safety

AI can be wrong.

Verify important information with reliable sources. WatchMuse and its connected providers do not replace professional medical, legal, financial, or emergency services. Never include passwords, API keys, payment details, or medical records in a support email.

Read the Privacy Policy
Contact

Tell us what happened.

Include the App version, device, operating system, selected AI route and exact error message. For Mac connections, include whether the service says it is ready. Do not send pairing codes, credentials or private chat content.

[email protected]