Bring your own key

Perch can run on your own model credentials instead of ours. Usage on your own key is not counted against your included Perch Tokens, so your monthly allowance sits untouched while you use it.

This is available on every plan, including the free one. It is a feature, not a tier, so there is nothing to upgrade or switch to.

There are two kinds:

• Your own cloud key. A key from a model provider, saved once to your account and usable from Web, Desktop, and CLI.
• Your own endpoint. Anything that speaks the OpenAI-compatible API, including a model running on your own machine. A model on your own machine is CLI only, for the reason in Local endpoints.

Your own cloud key

Set this up once on the web and it follows your account everywhere, because the key is stored server-side against your account rather than on one device. It is encrypted at rest and never sent back to the browser after you save it.

1. Go to Settings → Models & Keys.
2. Pick your provider from the list and paste your API key.
3. Press Test. This runs one real, tiny request against your key and reports whether it worked and whether the model can call tools.
4. Press Save.
5. Press Use for chat on the saved key.

Step 5 is the one people miss. Saving a key stores it; Use for chat is what actually routes your turns through it. When it is on, the model picker in the composer is replaced by Your key · <provider>, and Settings tells you chat is running on your key and is not metered.

To go back to Perch-hosted models, turn Use for chat off. Your key stays saved.

The key is shared across your account, but the choice to use it is per device. Turning it on in the browser does not turn it on in the CLI, and the other way round. That is deliberate: it lets you run one terminal on your own key while the rest of your session stays on Perch.

Any provider, any model

If your provider is not in the list, pick Custom (OpenAI-compatible) and give Perch three things:

The model id is passed through untouched, so a model Perch has never heard of works as long as your endpoint serves it. Copy the id exactly from your provider's documentation, including any prefix.

Two requirements the form will enforce:

• The base URL must be https, and it must be a public address. Anything on a private or internal network is rejected, including localhost. Your own machine is not reachable from our servers, so use the CLI route below for that.
• The model must support tool calling. Perch works by reading files, running commands, and calling tools; a model that cannot do that fails partway through real work rather than at the start. Where the model is in the public model catalog and that catalog says it cannot call tools, saving is refused with a message saying so. Models the catalog does not know are allowed through, since most newer and private models are not listed yet.

Where the catalog does know your model, Perch also picks up its real context window, so a long-context model gets its full window rather than a conservative default.

Desktop

Desktop signs in to the same account, so a key saved on the web is already there. The same panel lives in the app under Settings → Models & Keys, and it behaves identically.

The one thing that does not carry over is the Use for chat choice, which is per device. Turn it on once in the app.

A model running on your own machine is CLI only today. See Local endpoints.

CLI

The CLI signs in to the same account, so any key you saved on the web is already available to it. Selecting one is a separate step, because the choice is per device:

perch byok list                  # keys saved on your account
perch byok use openai            # run this terminal's turns on that key
perch byok status                # what turns are running on right now
perch byok off                   # back to Perch-hosted models

Inside a session, /byok does the same thing: /byok alone reports what you are running on, /byok <provider> switches, and /byok off goes back. perch status and /status both carry a byok row.

You can also manage the keys themselves without leaving the terminal:

perch byok set openai --key sk-...                     # save a key to your account
perch byok set custom --key sk-... \
  --url https://api.example.com/v1 --model acme/model-x  # your own endpoint
perch byok test [provider]                             # probe it with one real request
perch byok remove openai                               # delete the saved key

The key is sent to your account and encrypted there, exactly as the web panel does it. Nothing but your choice of provider is written to the machine you typed it on.

A model on your own machine

That is a different command, because the endpoint stays on your device:

perch byolm set <baseUrl> <modelId> [--key <key>]
perch byolm status
perch byolm test
perch byolm clear

For example, against Ollama:

perch byolm set http://localhost:11434/v1 llama3.1
perch byolm test

--key is optional; most local runtimes do not need one, and Perch will omit the authorization header entirely rather than send a placeholder.

perch byolm test sends one small request and reports whether the endpoint answered and whether the model called a tool. Run it before real work: a local model that cannot call tools will otherwise appear to work and then stall on the first file read.

Local endpoints

A local endpoint lives on your machine, so it is configured from the CLI only, never from the web or the desktop app. This is not a limitation we chose for convenience: both of those run their model calls through our servers, and our servers cannot reach localhost on your computer. The CLI runs the call in its own process on your machine, which is the only place a local endpoint can actually be reached from. Keeping it there also means the address and any key never leave your machine.

Anything OpenAI-compatible works, including Ollama, LM Studio, llama.cpp's server, and vLLM.

Desktop support for local models is not shipped yet. Until it is, use the CLI, or use a cloud key in the app.

What changes when you use your own key

• Metering. Turns on your key are not counted against your included Perch Tokens, and no Perch Token charge appears for them.
• Model routing. Perch routes only to your provider. It will never quietly fall back to a Perch-hosted model, because that would send your prompt somewhere you did not choose and bill you for it. If your endpoint is down, the turn fails and says so.
• Model picking. The Roost tier picker does not apply, since Perch is no longer choosing a model for you.
• Everything else. The workspace, memory, retrieval, citation checking, and the rest of the harness work exactly as they do on hosted models.

Troubleshooting

"Your key was accepted, but no model this workspace can run is available." The key is valid, but nothing on that provider can currently be routed for your account. This is the honest version of a failed test, and it means real turns would fail too. Try another provider, or use Custom and name a model explicitly.

The Test button passes but real turns fail. Report it. A passing test is meant to route exactly where a real turn routes, so this specific mismatch is a bug on our side rather than something to work around.

"...does not support tool calling." The public catalog lists that model as unable to call tools, so Perch declined to save it rather than let it fail mid-task. Pick a model that supports tool or function calling; most current instruct and coding models do.

A local endpoint will not save on the web. That is expected. Use perch byolm set on the CLI.

Turns are still using Perch models. Check that the key is selected on the device you are working from. Saving a key does not route turns: in the app that is Use for chat, and in the terminal it is perch byok use <provider>. perch byok status and /status both say which one you are on.

Related

• Models covers what is in the hosted pools and what each plan includes.
• Perch Roost explains hosted routing, which is what your key replaces.
• CLI covers the rest of the command line.