Roost Support

Roost is a menu bar app for macOS that routes AI requests between Apple Intelligence on your Mac and an external provider. This page covers setup, everyday use and the errors you may see. If it does not answer your question, write to us through the contact form.

Requirements

• macOS 27 or later on a Mac with Apple Silicon.
• Apple Intelligence enabled: System Settings > Apple Intelligence & Siri. The on-device model downloads in the background after you enable it; Roost shows “model not ready” until it has.
• For Smart, Private and Full modes: access to at least one provider, either a cloud account with an API key or a server on your network that speaks the OpenAI API.

Install and first launch

1. Install Roost from the Mac App Store.
2. Open Roost. It appears in the menu bar; there is no Dock icon and no main window.
3. Click the menu bar icon. The status card shows “Running” and the address http://127.0.0.1:11535. If it shows “Stopped”, use the switch on the right to start.
4. The mode is On-device: every request is answered by Apple Intelligence on your Mac. Nothing leaves your Mac in this mode.

Connect an app

Roost works with any app that lets you set an OpenAI-compatible base URL. In that app:

• Base URL / API host: http://127.0.0.1:11535/v1
• API key: anything, for example roost. Roost ignores it.
• Model: auto to let Roost decide, apple to always answer on your Mac, external to always use your default provider, or the id of a provider (for example deepseek).

Some apps append /v1 themselves; if you get 404 errors, try http://127.0.0.1:11535 without the suffix.

From the command line:

curl http://127.0.0.1:11535/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "auto", "messages": [{"role": "user", "content": "Hello!"}]}'

With the OpenAI Python SDK:

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:11535/v1", api_key="roost")
reply = client.chat.completions.create(model="auto",
    messages=[{"role": "user", "content": "Hello!"}])
print(reply.choices[0].message.content)

Add a provider

1. Open Settings from the panel and go to Providers.
2. Click Add and choose a preset: llama.cpp, Ollama, DeepSeek, OpenAI, Gemini or Claude. Any other OpenAI-compatible server works with the OpenAI-compatible type and its base URL.
3. Fill in the base URL (for local servers, the address and port of your server ending with /v1), the model name and, for cloud services, the API key. Keys are stored in the macOS Keychain.
4. Click Test connection. Roost calls the provider’s models endpoint and reports success or the error it received.
5. Go to Routing and choose this provider as the default external provider. Smart, Private and Full become available.

The first provider you add becomes the default automatically.

Choose a mode

Switch modes from the panel or in Settings > Routing. The change applies to the next request.

Read the decision feed

Every request appears in the panel with the destination (Apple Intelligence or your provider), the reason and the time it took. A private badge means the on-device model found private data. Click a row to see the three assessment flags and the model’s reasoning. Settings > Log keeps the last 200 decisions and can append them to a file on your Mac; Reveal in Finder shows its location.

The same information is in the response headers X-Roost-Target, X-Roost-Reason, X-Roost-Sensitive and X-Roost-Model.

Use Roost from other devices on your network

By default Roost listens only on your Mac. In Settings > General you can choose “All interfaces” or a specific address; the server is then reachable from other devices on the same network at http://<your Mac's address>:11535/v1. Roost has no authentication, so anyone on that network can send requests through your providers and keys. Use this only on networks you trust.

Troubleshooting

The menu bar icon is dimmed and the status says Stopped. Start the server with the switch in the status card. If it stops again, another program is using port 11535: change the port in Settings > General and update your apps.

“Apple Intelligence is not enabled.” Turn it on in System Settings > Apple Intelligence & Siri, then wait for the model download to finish. Roost checks again automatically.

“The on-device model is not ready yet.” The system is still downloading the model. Keep the Mac connected to power and Wi-Fi and try again later.

Smart, Private and Full are disabled. No default external provider is set. Add one in Settings > Providers and select it in Settings > Routing.

The provider card says unavailable. Roost could not reach the provider’s models endpoint. Check the base URL (including /v1 for most servers), the key, and that a local server is actually running. Use Test connection in Settings > Providers to see the exact error. While a provider is down, Roost answers on your Mac.

My app gets HTTP 403 “not allowed in On-device mode”. The app asked for an external model while Roost is in On-device mode. Switch to another mode or set the app’s model to auto or apple.

HTTP 413 “Request exceeds the model context window”. The conversation is too long for the on-device model. Shorten the history, or use Private or Full mode so long requests go to your provider.

HTTP 422 “Model guardrails blocked this request” or “The model refused to answer”. Apple’s on-device model declined the request. Rephrase it, or use Full mode to send it to your provider without on-device assessment.

HTTP 400 “The model does not support this language.” The on-device model cannot process the language of the request. Switch to Full mode to route such requests to your provider.

HTTP 429. Either the on-device model or the provider is rate limiting. Wait a moment and retry.

HTTP 502 “Upstream …”. The provider returned an error; the message includes the provider’s own text (for example an invalid key or a model name that no longer exists). Fix the provider settings and use Test connection.

HTTP 503. The chosen backend is unavailable: Apple Intelligence is off or not ready, or the provider is not configured. The message says which.

Answers from Apple Intelligence are short or weaker than expected. That is the nature of the small on-device model. In Smart mode it handles simple requests; if you want your provider to answer everything that is not private, use Private mode.

A request I consider private went to the provider. The privacy assessment is made by a language model and can miss cases. Check the row in the decision feed to see the flags. For sensitive work use On-device mode, or add explicit hints to the assessment instructions in Settings > Routing (keep changes small).

Streaming stops early or the app shows a JSON error. Look at the decision feed and the X-Roost-Reason header. Errors inside a stream are sent as an error event before [DONE]; the message names the cause.

Reset

• Settings are stored in the app’s preferences under the identifier com.afceda.roost.
• API keys are stored in the macOS Keychain under the service com.afceda.roost.providers. Deleting a provider in Settings removes its key.
• The optional decision log file can be cleared from Settings > Log, which also shows where it is.

Frequently asked questions

What does Roost actually do? It runs a small local server on your Mac with the same API your AI apps already use, and for every request decides whether Apple Intelligence on your Mac answers it or your chosen cloud provider does. You set the policy once with a mode; Roost applies it to every request and shows you each decision.

Does my data leave my Mac? In On-device mode, never. In Smart and Private modes, only requests that the on-device model judged free of private data are sent to your provider, and you can see exactly which ones in the decision feed. In Full mode everything goes to your provider. Roost itself sends nothing anywhere else: no accounts, no analytics, no telemetry.

Which apps work with Roost? Any app that lets you set an OpenAI-compatible base URL and API key: chat clients, editor plugins, agents, scripts. Point them at http://127.0.0.1:11535/v1 with any key.

Which providers can I use? Any server that implements the OpenAI Chat Completions API, including llama.cpp, Ollama, DeepSeek, OpenAI and Gemini’s OpenAI endpoint, plus Anthropic’s Claude through its own API. Presets are included; other services take a base URL and a key.

Do I need a paid API? No. Roost is free, and On-device mode needs nothing but Apple Intelligence. If you run llama.cpp or Ollama on your own machine, the external provider is free too. Cloud providers bill you directly according to their own pricing; Roost does not add anything.

What are the requirements? macOS 27 or later, a Mac with Apple Silicon, and Apple Intelligence turned on in System Settings.

How does Roost know what is private? Apple’s on-device model reads the whole conversation with instructions that describe private data: passwords, API keys, tokens, card and account numbers, names with contact details or ID numbers, medical and financial details, confidential company information. It sets a flag, and Roost applies the mode’s rule. You can read and adjust the instructions in Settings > Routing.

Is the privacy check reliable? It is a language model’s judgment, tuned for the obvious cases, and it errs on the side of keeping things on your Mac: when the assessment fails or times out, the request stays local. It is not a certified data loss prevention tool. For work that must never leave the Mac, use On-device mode.

Does the check slow things down? For requests that stay on your Mac, no: the same generation that assesses the request also writes the answer. For requests that go to the provider, Roost waits for the three flags first, usually well under the default three-second timeout on a modern Mac, then forwards the original request.

What is the difference between Smart and Private? Both keep private data on your Mac. Smart also keeps simple requests on your Mac and sends only hard or time-sensitive ones to the provider. Private sends everything that is not private to the provider, so you get cloud-quality answers for everything else.

Can I force a destination for one request? Yes. Set the model field to apple (your Mac), external (default provider) or a provider’s id. auto follows the mode. In On-device mode external destinations are refused with 403.

Does Roost change my requests? For OpenAI-compatible providers it forwards the request body exactly as your app sent it, replacing only the model name and the stream flag. Tools, JSON mode and other fields pass through, and the provider’s response comes back unchanged. For Claude, Roost converts between OpenAI’s and Anthropic’s formats, text only. For Apple Intelligence, the conversation is turned into the model’s transcript format.

Does it work offline? On-device mode does. The other modes need a reachable provider; if the provider is down, Roost answers on your Mac and says why.

Which languages are supported? The interface is in English and Russian. Apple Intelligence answers in the language of your message, within the languages it supports on your Mac. Cloud providers follow their own rules.

Where are my API keys stored? In the macOS Keychain, under Roost’s own service. They are never written to settings files, logs or responses.

Can other devices on my network use Roost? Yes, if you switch the interface in Settings > General from localhost to your network address. There is no authentication, so do this only on a trusted network.

Does Roost keep a log of my conversations? It keeps a decision log: time, destination, reason, duration and a short preview of the last message, in memory (200 entries) and, if you enable it, in a file on your Mac (Settings > Log > Reveal in Finder shows where). Answers are not logged.

Why is Apple Intelligence’s answer short or a bit off? It is a small model that runs entirely on your Mac. It is good at quick tasks and weaker at long or specialized ones, especially outside English. Use Private mode to send everything non-private to a larger model.

Can I run several providers? You can configure as many as you like and reach each one by its id in the model field. Only one is the default external provider that the modes use; change it in Settings > Routing.

Is Roost open source? No. Roost is proprietary software; see the Licenses page for the third-party components it includes.

How much does Roost cost? Roost is free on the Mac App Store today. If pricing changes in a future version, this page will say so.

Contact

Use the contact form. Include your macOS version, the mode you were in, the provider type and, if possible, paste the X-Roost-* headers as text or describe the row in the decision feed. The form accepts text only, so files and screenshots cannot be attached. Do not send API keys.