Merrimo User Guide › AI generation and art

Set up AI in Merrimo on Mac

Merrimo can draw pictures and help with your writing through an AI service you connect: OpenRouter, your own API key from Anthropic, OpenAI or Google, or a model server you run yourself, such as LM Studio or Ollama. AI is entirely optional. Connect a service when you first open Merrimo, or any time in Settings > Providers.

Add a provider

Choose Merrimo > Settings (⌘,), click Providers, then click + next to Your Providers (or Add Provider… when you have none). The sheet opens on Choose an AI service. Pick one of three and click Continue:

• Pay as you go with OpenRouter: pictures and writing help from hundreds of models, billed by OpenRouter as you use them, usually a few cents a page.
• Use your own API key: writing help from Anthropic, OpenAI or Google, billed by them per use. A ChatGPT or Claude subscription doesn't cover it: you need an API key from the provider.
• Use a model server: models you run yourself in LM Studio, Ollama, Bionic or any OpenAI-compatible server. Free, and private when the server runs on this Mac.

Only OpenRouter makes pictures; an API key or a model server gives you writing help. When you ask for a picture or a suggestion, that part of your story is sent to the service you choose.

On each later step, Back returns to the step before and Cancel closes the sheet without adding anything. Click Add Provider on the last step to add it to Your Providers. Your first provider becomes the Active one and turns on Use AI; to use a later one everywhere, click Make Active on its row.

Connect OpenRouter

1. Click Sign in with OpenRouter…. Your browser opens: sign in to OpenRouter, or create an account there, and approve Merrimo.
2. Merrimo picks up the connection by itself and says Connected to OpenRouter. To stop waiting for the browser, click Cancel.
3. Click Add Provider.

If you already have an OpenRouter API key, click Use an OpenRouter API key instead and paste it. Merrimo checks the key as soon as you stop typing.

Use your own API key

1. Under Provider, choose Anthropic, OpenAI or Google.
2. Paste your key in API key. If you don't have one yet, click the Get a key at… link to open the provider's key page.
3. Merrimo checks the key as soon as you stop typing, by reading the provider's list of models with it. Key works, with the number of models, means it's ready; That key didn't work means the provider refused it.
4. Model shows the model Merrimo picked from that list. To choose another, click it: Choose a model opens with the provider's own list. Search or filter it, select a model and click Use This Model, or click Back to keep the one you had.
5. Click Add Provider.

Prices and context sizes in the list come from OpenRouter's public catalog, so a model OpenRouter doesn't list shows no price. Your key is kept in iCloud Keychain and sent only to the provider you picked. See Your providers and keys on your other devices.

Use a model server

A model server runs models you choose on your own Mac or network. Merrimo doesn't pick the model; your server offers the ones it has.

• Found on this Mac: when the step opens, Merrimo looks for LM Studio (at localhost:1234) and Ollama (at localhost:11434) on this Mac and shows each as Running, with how many models it has, or Not running. A running server with models is picked for you. If yours isn't running, open it, then click Look again.
• Another address: a server on your network or online, or one on another port. Enter its Base URL, such as http://studio.local:1234/v1, and an API key if the server needs one, then click Check. Connected, with the number of models, means Merrimo reached it. The App Store version reaches a server by http:// only at localhost, an IP address or a .local name; for any other address, use https://.

Then choose the Model from the server's list (click it to open Choose a model) and click Add Provider.

Requests go only to the server you pick, so a server on this Mac keeps your story on this Mac. The first time Merrimo connects to a server on your local network, macOS asks whether Merrimo may find and connect to devices on your local network: click Allow. If you didn't, turn on Merrimo in System Settings > Privacy & Security > Local Network.

Change a provider's model or key

In Settings > Providers, each row says how the provider connects and which model it uses, such as “API key · claude-sonnet-5-5”. Click a provider to open its page. The top row says who runs it, such as “Your own API key · billed by Anthropic per use”, with Make Active if it isn't the Active provider.

• Default Model: click it to choose the model Merrimo uses with this provider. For an API key, the list is the provider's own, read with your key; for a model server, it's the models the server has now.
• API Key: shows Saved or No key, and whether the key is in iCloud Keychain or only in this Mac's keychain. Click Replace… (or Add Key…), paste the key and click Save Key.
• Thinking: for a model that can reason before it answers, choose how much it thinks, or Default to leave it to the model. See Change Merrimo settings on Mac.
• Connection: for a model server, Test checks that Merrimo can reach it and lists its models. Remove… removes the provider, on your other devices too, and deletes its API key from iCloud Keychain. If it was the Active provider, Merrimo asks which of the others should write now, or None for Now.

Your providers and keys on your other devices

When you're signed in, your providers follow your Merrimo account: a provider you add on one Mac shows up in Settings > Providers on your other Macs, with the same model, and making one Active, changing its model or removing it changes it everywhere. A provider added on another device says where it came from, such as “From your MacBook Air”.

If you set up the same provider on several devices (OpenRouter with the same model, the same API key provider and model, or the same model server and model), Settings > Providers lists it once. A model server counts as the same when it's at the same address: localhost on two different Macs is two servers, but a Mac's localhost server and the same server added on another device by that Mac's network name are one. Removing it removes every copy.

Merrimo keeps each provider's API key in iCloud Keychain. With iCloud Keychain turned on (System Settings > your name > iCloud > Passwords & Keychain), your other Macs and your iPhone signed in to the same Apple Account get the key too, and replacing or removing it on one changes it on all of them. Merrimo's own servers never see your keys.

Keys you saved with an earlier version of Merrimo move to iCloud Keychain the next time Merrimo opens. A copy of Merrimo that can't use iCloud Keychain keeps its keys in this Mac's keychain instead: the provider's page then says Saved in this Mac's Keychain only.

If a provider arrives without its key (iCloud Keychain is off on this device, or the provider was set up by a copy of Merrimo that keeps keys on its own Mac), its row says Key not on this Mac with No key. Click it, then Add Key…, and paste the key.

If that provider is your Active one, Merrimo writes on this Mac with another provider whose key is here, preferring one of the same kind, and Settings > Providers marks it In use here until you add the key. A provider you add on a device where the Active one has no key becomes Active on that device only; your other devices keep theirs.

Model servers on your other devices

A model server set to localhost on a Mac means that Mac. When it follows your account to another device, Merrimo reaches it there by the Mac's network name (such as studio.local) or, with Tailscale's MagicDNS, its Tailscale name, whichever answers.

• The server must listen on the network, not just on its own Mac. In LM Studio, turn on Serve on Local Network in the Developer tab; in Ollama, turn on Expose Ollama to the network in its settings. On the server's own Mac, the provider's page says Only this Mac can reach it when it doesn't, after Test.
• On another device, a server it can't reach says Can't reach: set to localhost on that Mac, with Not reachable. Test on its page tries again and says what to change.
• If your Active provider is a server this device can't reach, Settings > Providers offers Use Another Here: the provider you choose is Active on this device only, and your other devices keep theirs. Use … Here Too goes back to the one your other devices use, and Make Active makes a provider Active everywhere.

Choose the model a project uses

Each project can use its own model, and give a job its own. In the project's sidebar, under Project, click Settings.

• Model shows the model the project writes, chats and reads with. While it says App default, the project uses the Active provider's model from Settings > Providers. Click the card to choose another: the list holds every model of every provider you've added. The first column lists your providers; click OpenRouter to see its brands in the next column. The top row, App default, goes back to the app's model.
• Jobs lets a job use a model of its own. Chat is the chat and ⌘K replies; it needs a model that can use tools to change your story. Reading the Story finds the cast, places and props as you write; it needs a model that returns structured replies. Each starts as Same as the project's model. When choosing for Chat, the Tools filter starts on.
• If a job's model can't do the job, its row says so, such as “… can't use tools: the chat can answer, but can't change your story.” Click Choose a model for Chat. to pick another. A model server doesn't say what its models can do, so its models get no warning.
• Use App Settings, under the Model card, shows while the project or one of its jobs has a model of its own. Click it to clear them all: the project then follows Settings > Providers again.
• Usage shows what the project has cost you this month, by model. Providers that report a price show dollars; the others show tokens. Click See All Usage for Settings > Usage.

The choice is saved with the project for you, so it follows you to your other Macs; people you share the project with keep their own. Each Mac uses whichever of its providers offers the model, the provider you picked it from first, then OpenRouter. If none does, that Mac uses its own app default, and the page says the model isn't set up on this Mac, with Add Provider….

While a project's chat uses a model of its own, the Agent window says so above the conversation, such as “This story uses its own model: Claude Opus 4.8”. Changing Settings > Providers doesn't change it. Click the note to open the project's Settings page, then click Use App Settings.

If nothing answers at a model server's address, the chat says which address it tried, such as “Nothing is answering at localhost:1235. Is the model server running on that port?” Start the server on that port, or choose a model that works on the project's Settings page.

With no provider added yet, the page offers Add Provider…, which opens the same sheet as Settings.

Set up AI when you first open Merrimo

After you sign in, or choose to use Merrimo without an account, Merrimo asks Do you want AI?. Click No AI — just write to skip it; you can add a provider later in Settings.

Click Set up AI, then, on Choose what to add, tick what you want:

• Draw pictures: Everyday Pictures, on this Mac (free, downloaded to your Mac) or Online with OpenRouter, or both.
• Help me write: Online with OpenRouter, or My own API key or model server.

Click Continue. If you ticked only OpenRouter rows, Connect OpenRouter comes next. If you ticked My own API key or model server, Choose an AI service comes next, with the same three choices and steps as in Settings, and OpenRouter still on offer. Use an online account instead also opens Choose an AI service. If you ticked nothing to connect, the button says Start Writing or Download & Start Writing instead. If Choose what to add doesn't appear, Set up AI goes straight to Choose an AI service.

Click Set up AI: Choose an AI service opens, with the same three choices and steps as in Settings.

On the last step, click Start Writing; Back returns to the screen before. If you connect an API key or a model server, pictures online aren't set up: add OpenRouter later in Settings > Providers.

Everyday Pictures downloads while you connect.