Pi Agent supplies the workshop, not the engine

Pi Agent uses BYOK — bring your own key. The add-on does not choose an AI service for you and does not pay for one: you open an account, create a key, and paste it in. Three consequences follow.

• You pick the model, and can change it later without reinstalling anything.
• You pay the provider directly; the add-on charges nothing.
• The key stays on your hardware, sent only to the provider you configured.

OpenRouter goes first here for three practical reasons: one key reaches model families from several vendors through an OpenAI-compatible gateway; sign-up takes an email address or a supported sign-in provider, with whatever verification its current page asks for; and it is built for API access from many regions, though model and payment availability still vary by country.

It is a gateway, not a model developer: one key reaches a catalog that changes over time, where a direct provider gives you its own catalog only, and data handling follows OpenRouter's terms plus the selected model provider and your privacy settings. No provider is best at every task, and many people keep two or three — that is Part 6. For now, one working key is the whole job.

A short string of text that spends money

An OpenRouter key is a secret string that normally begins with sk-or-v1-. Pi Agent sends it with every request; OpenRouter checks it, charges the usage to your account, and routes the request to the model you chose.

Since Pi Agent v0.13.0, provider keys are stored locally in /data/pi-agent/models.json on your Home Assistant host, in the add-on's persistent data. WoowTech does not receive the key, but anyone with sufficient access to the host or that data can read the file.

flowchart LR
  A["Your browser"] --> B["pi-web on your HA host"]
  B --> C["/data/pi-agent/models.json
where the key is stored"]
  B --> D["https://openrouter.ai/api/v1
the endpoint you configure"]
  D --> E["The upstream model
that writes the answer"]

Treat it like a payment credential. Three places are safe: Pi Agent's Models panel; a password manager such as 1Password, Bitwarden, Apple Passwords or KeePass, with a strong master password and multi-factor authentication; and an encrypted offline backup whose restore you have tested. Keep it out of these:

• Public repositories. Scanners find exposed keys fast, and deleting the latest commit is not enough if the value stays in the Git history.
• Chat and community groups. Other participants and the service may keep the message.
• Shared documents. Link-sharing settings are easy to misconfigure, and they change later.
• Ordinary email. Do not send an API key as email.
• Screenshots and recordings. Text too small to read is still readable by OCR.
• Support posts. Use an obviously fake example and redact the whole secret, not just its tail: sk-or-v1-REDACTED.

Appendix B says credentials are redacted in logs at debug level as ***. Read a log yourself before sharing it anyway.

Creating the key, on a phone or a computer

Dashboard labels change. Where the wording differs from what is below, follow the site.

1. Step 1

   Open the official site

   Go to https://openrouter.ai/settings/keys. Check the address bar reads openrouter.ai, not a look-alike such as openrouter.example.

2. Step 2

   Sign in, or create an account

   Use a sign-in method OpenRouter currently offers, email or a supported identity provider, and complete any verification it shows. Do not reuse your Home Assistant password.

3. Step 3

   Read the privacy and data settings

   Do it before adding credit or sending anything private: requests may be handled by the selected model provider, so pick settings and models that suit what you send.

4. Step 4

   Open the API Keys page

   From the dashboard, open API Keys in Settings. If the labels have changed, follow the current link from the official settings page.

5. Step 5

   Select Create Key

   OpenRouter may offer an optional credit limit for the key. Set one only if it suits your own budget.

6. Step 6

   Give it a name you will recognize later

   Name it after the installation it belongs to: pi-agent-home, pi-agent-office, test-2026-08. Separate keys make rotation and usage review far easier.

7. Step 7

   Create it, then use the Copy button

   Use Copy rather than selecting text by hand, so you do not lose a character. This is the only time the full value is shown; a masked preview such as sk-or-v1-… cannot recover it.

8. Step 8

   Put it in your password manager

   Save it properly now. A temporary local note is fine — delete it once the setup below is done.

Tokens, credit, and what the account asks of you

OpenRouter measures usage in tokens, and counts vary by language and by model, so do not work out a bill from a word count. Pi Agent sends your prompt and the relevant conversation context with each request, and the answer costs tokens too.

Rates and availability change. Read them in the OpenRouter catalog and your own dashboard, not from a figure printed in any guide, including this one.

Watch real usage rather than inventing a monthly estimate. Cost follows prompt and response length, context length, model choice and, in video workflows, the number of generation steps. Use a per-key limit if the dashboard offers one, and review each workflow's own usage rather than assuming a fixed cost.

A registry of routes, not a list of models

Three small buttons sit at the bottom-left of the workspace sidebar: Models, Skills, Settings. Models opens the settings dialog on its Models tab — a service directory, where each card is one company or gateway you have an arrangement with, holding one endpoint, one credential and its own model entries.

• Add Provider creates another card — once now, again in Part 6 for a second route.
• Test is the control that matters: green means the settings can complete a real request, not just that the form saved.
• Save writes to /data/pi-agent/models.json, which the documented Home Assistant backup path includes.

Add Provider opens a catalog rather than an empty form, grouped by how a provider connects rather than by brand.

The catalogTop of the list: one custom entry, six subscriptions that sign in by OAuth, then the API-key providers with their model counts.

• CUSTOM holds one card — “OpenAI / Anthropic compatible”, subtitled Custom endpoint format. That is the card this walkthrough uses, because it is the one that asks you for an endpoint and a key by hand.
• SUBSCRIPTIONS are all marked OAuth. You sign in to a plan you already pay for instead of pasting a secret — note that OpenRouter appears here too, as OpenRouter OAuth, which is not the route this article takes.
• API KEY cards carry a model count: Amazon Bedrock 121 models, Anthropic 14 models. The number is how many models that one entry can reach.

Breadth in one entryOpenRouter reaches 366 models and Vercel AI Gateway 237, where most single-vendor entries list a handful.

• OpenRouter, 366 models, sits in this list by name. One account and one key, and the count is the reason this article picked it.
• Single-vendor entries are much smaller — xAI 3, Z.AI 7, Together 21. Each of those needs its own account.
• Radius shows 0 models, so being listed here does not mean there is something to select yet.

Two ways in, then. The OpenRouter card fills the endpoint in for you; this article types it out on the custom card, and the three settings are the same either way.

The key alone does not tell Pi Agent anything

A value beginning sk-or-v1- is only a credential: Pi Agent cannot work out the endpoint, the API mode or the model ID from it. This is a one-time setup; you return to Models only to rotate a key, add a provider, or change the models on offer.

All three must agree. The model ID above is the one verified in the repository for this walkthrough; catalogs change, so confirm it is still listed, and otherwise copy an available model's exact ID.

1. Step 1

   Open Models, then take the custom entry

   Select Models, then Add Provider, and choose the card under CUSTOM labeled OpenAI / Anthropic compatible. The form has Name, API mode, baseUrl and apiKey, then the Models list.

2. Step 2

   Type a Name you will read later

   OpenRouter is enough. Pi Agent tells cards apart by Name, not by endpoint, so a second key on the same endpoint needs its own name, such as OpenRouter-office.

3. Step 3

   Set API mode to openai-completions

   The four options are openai-completions, openai-responses, anthropic-messages and google-generative-ai. This base URL exposes an OpenAI-compatible Chat Completions interface, so choose openai-completions; a mismatched mode returns a 400 or 404 rather than a helpful message. A documented direct Anthropic setup uses anthropic-messages, the Google equivalent google-generative-ai, and a documented OpenAI Responses endpoint openai-responses. Appendix B is the provider reference.

4. Step 4

   Enter the base URL exactly

   Copy https://openrouter.ai/api/v1 with nothing added. Use HTTPS. Do not append /chat/completions, do not leave a trailing slash, and do not paste a dashboard route such as /settings/keys.

5. Step 5

   Paste the key into apiKey

   Paste from your password manager. The field masks the value; the eye control reveals it briefly. Check both ends for a stray space and remove it with Backspace or Delete — whitespace is the most common paste failure here. To read the whole value, use a local text field, never a shared document or anything you might screenshot.

6. Step 6

   Add the model, then Test and Save

   Select Add Model, enter anthropic/claude-sonnet-4 as the name, and take the contextWindow figure from that model's own details page — never from a different model. Then Test: a green check mark means it worked, so Save and close the panel. No restart is needed; the next request uses the new configuration.

Where it shows upThe picker on a machine configured with a different route. Yours lists the models you entered, not these.

• The button under the message box carries the current model name — here GPT-5.6 Sol. Selecting it opens this list.
• The tick marks the model this conversation will send to. Make sure it is the one you tested.
• The list shows model names only, with no provider prefix, so give each model an ID you can recognize on sight.

Changing a card later, and deleting one

Every provider card has a three-dot menu (⋮) with two actions, not equally reversible.

A second key on the same provider earns its own card in three situations: telling home and office usage apart, with cards named OpenRouter-home and OpenRouter-office; carrying separate per-key limits where the dashboard offers them, though that is no substitute for restricting Home Assistant administrator access; and reducing disruption while you rotate the other key. Follow your organization's rules for business credentials and billing. Add it with Add Provider, a different Name, the same baseUrl, the other apiKey, and anthropic/claude-sonnet-4 only if it is still in the live catalog.

Read the error before you change anything

A failed Test is specific. Match the code to a row rather than editing fields at random.

Some failures show up in the interface rather than as a status code.

And some go wrong before Pi Agent ever sees the key.

Where to go from here