Models and keys

The model catalog

Metroon works with two different kinds of Citizens: cloud models, reached through a provider’s API, and local models, which run entirely on your Mac’s own hardware without the request ever leaving the device. The full model catalog, generated directly from the app itself rather than maintained separately here, lives at /models. That page describes the catalog inside one specific build, identified there by registry version and digest: which local models it curates, which cloud model families it recognizes, and their approximate sizes and context limits. Your installed version may be on a different build, and the app can adopt a newer signed registry after that page was generated, so treat the app itself as the check for what is actually available to you. Treat that page as the source of truth for that build’s catalog, and treat anything about the catalog you read anywhere else, including this page, as background.

Not every model on that list will run on every Mac, and not every provider account will be able to reach every cloud model listed. A local model has to actually fit in memory and load correctly on your specific hardware, and a cloud model needs an active key from that provider with access to that particular model. The list is a catalog of what Metroon recognizes, not a promise that a given installation can use all of it.

Changing models without losing your history

The knowledge base Metroon builds belongs to the app and lives on your Mac, rather than belonging to any one Citizen or provider. Claims, citations, and the insights you save accumulate there across every session, whichever models produced them. When Metroon assembles context for a new session, it draws on that accumulated history and puts the relevant prior work in front of whichever Citizens are taking part, so a Citizen can cite what was established before it ever joined.

The practical effect is that swapping a Citizen for a different model, adding a provider, or dropping one you no longer pay for leaves the accumulated work in place. What earlier sessions established stays in your knowledge base and remains available for later Citizens to draw on. How it works covers what that context is made of and how it gets selected.

What your Mac’s memory actually supports

Local models are the part of Metroon that lives entirely on your machine, and they’re also the part most directly limited by it. The honest baseline: a Mac with 16 GB of memory can comfortably run cloud Citizens all day, since those don’t consume your Mac’s memory for the model itself, but it realistically supports at most one small local model running at a time alongside everything else you have open. If local models matter to you and your Mac is at or near that baseline, lean on cloud Citizens for the models you want to compare, and treat a local model as one voice among several rather than the whole roster.

There isn’t a single number that tells you what a larger Mac supports, since it depends on which specific models you pick, how many you try to run at once, and what else is competing for memory at the time. The most reliable way to find out what your Mac can actually do is to try adding a local Citizen and see whether it loads.

Adding a provider API key

To use a cloud Citizen, you need an API key from that provider, added from Metroon’s settings. Each provider’s key comes from that provider’s own developer or platform console, not from their consumer product. Paste the key in, and any cloud model that provider offers, and your key has access to, becomes available to add as a Citizen.

Keys are stored on your Mac and used only to authenticate the requests Metroon makes on your behalf when a cloud Citizen you added takes part in a session. Metroon doesn’t see or store your provider account credentials, only the key you generate and paste in yourself.

An API key is not a subscription

This is the single most common reason a cloud Citizen fails to work, so it’s worth stating plainly: a consumer subscription to a chat product, the kind you pay for monthly to use that provider’s own app or website, is not an API key and will not work in Metroon. A subscription authenticates you to that provider’s own product. An API key is a separate credential, generated from that provider’s developer platform, that authenticates programmatic requests from a third-party app like Metroon, and it’s typically billed separately, per token used, rather than as a flat monthly fee.

If you already pay for a subscription with a provider and want to use their models in Metroon, you’ll still need to visit that provider’s developer or API console, create a key there, and in most cases set up separate billing for API usage. It genuinely is a different product from the subscription, run by the same company, and the two accounts don’t share access to each other.

If a cloud Citizen won’t respond, refuses a request, or shows an authentication error, the most common causes are pasting a subscription login instead of a key, a key that’s been revoked or expired, or a key that doesn’t have billing set up on the provider’s side. Checking the key on the provider’s own console is the fastest way to rule those out.

Keeping a key funded

For paid API use, configure whatever billing method your provider requires. Some providers also offer limited free-tier access, so an unfunded key is not always a dead key, but once you are past a free allowance a key with nothing behind it stops working. This matters more in Metroon than in a chat app, because a full deliberation makes several calls per cloud Citizen as it moves through the phases, so a balance that looks comfortable for occasional use can empty partway through a session.

Two things are worth setting up on the provider’s side before you lean on cloud Citizens:

• Set up billing on the account behind the key. This is separate from any consumer subscription you already pay that provider, and having one does nothing for the other.
• Turn on automatic top-up if your provider offers it on a prepaid account. It is usually described as auto-reload or auto-recharge, with a threshold and a refill amount you choose, and it reduces the chance of a session stopping mid-deliberation. It can still stop at whatever monthly ceiling you set.

Usage breakdowns and spending controls vary by provider, and some report at the project or account level rather than per key. Your provider’s own console is the authoritative record of what you have actually spent and the only place to set spending limits and alerts. Metroon runs on the key you gave it and cannot raise or cap your provider spending on your behalf.