Bring your own key
Run Perch on your own model key or your own endpoint, on any plan including the free one. Setup for Web, Desktop, and CLI, plus how it interacts with your included usage.
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 computer. A model on your own computer works in Perch Desktop and the CLI, 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.
- Go to Settings → Models.
- Pick your provider from the list and paste your API key.
- Press Test. This runs one real, tiny request against your key and reports whether it worked and whether the model can call tools.
- Press Save.
- 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 button in the composer reads Your key, followed by the model, and Settings tells you chat is running on your key and is not metered.
You can name more than one model on a key. The first is the default, and you pick between them in the composer.
To go back to Perch-hosted models, turn Use for chat off. Your key stays saved.
The key is shared across your account. Perch on the web and Perch Desktop also save your model choice to your account, your own key included, so it follows you between them. The CLI keeps its own choice: turning a key on in the app does not turn it on in a terminal, 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:
| Field | Example |
|---|---|
| Base URL | https://api.example.com/v1 |
| API key | your key |
| Model id | exactly as your provider names it |
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, includinglocalhost. Your own machine is not reachable from our servers, so use a local model 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.
Your key's models are also listed in the model picker, under Your access, so you can pick one for a chat directly. In Perch Desktop each chat keeps the model you pick in it, your own key included. See Model and effort per chat.
Perch Desktop can also run a model on your own computer. 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 modelsInside 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 keyThe 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 use # find local models that are running and pick one
perch byolm set <baseUrl> <modelId> [--key <key>]
perch byolm status
perch byolm test
perch byolm off # back to Perch-hosted models; the model stays saved
perch byolm on
perch byolm clearFor 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 computer, so it is set up in Perch Desktop or the CLI, never on the web. Our servers cannot reach localhost on your computer, and a browser tab cannot either. Perch Desktop and the CLI make the model call from your own machine, which is the only place a local endpoint can be reached from. Keeping it there also means the address and any key never leave your machine.
In Perch Desktop, open Settings → Models and look under Local models. Perch finds Ollama and LM Studio when they are running, and you can enter the address of any other OpenAI-compatible server, such as llama.cpp's server. In the CLI, use perch byolm.
Local models are open to every plan. Turns on one are not metered and never fall back to a hosted model. See Local models for setup, the connection test, and the settings.
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. Set it up in Perch Desktop under Settings → Models, or with 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.
- Local models covers running Perch on a model on your own computer.
- CLI covers the rest of the command line.