What is Remote Relay
Many users run their own API services on their PC: a local reverse proxy, an aggregator panel like one-api / new-api, or local models in Ollama or LM Studio. These services live at addresses like http://127.0.0.1:3000/v1 — reachable only from that PC.
On the PC, you just paste that address into KOA's API page and it works. On your phone, it doesn't: the KOA mobile app is an HTTPS web app, and browser security forbids it from calling http:// local addresses — and even setting that aside, your phone can't reach your PC at all when they're on different networks.
Remote Relay exists for exactly this. Your PC keeps an encrypted connection to the KOA cloud; your phone hands requests to the cloud, the cloud passes them to your PC, and your PC calls the local API and sends the reply back the same way. At the office, on the subway, in another city — your phone can use the API running on your PC at home.
If you only use KOA on your PC, you don't need Remote Relay — just fill in the local address on the API page. The relay solves the "phone is somewhere else" scenario.
How it works & privacy
A full round trip looks like this:
Phone → KOA cloud → encrypted tunnel → your PC → local API, with the reply returning along the same path.
- The cloud only forwards, never stores — the relay server keeps no conversation content; it forwards and forgets.
- Your local API address never leaves your PC — the phone neither knows nor needs to know it; the PC decides where requests go.
- Identity is verified by your sync account — only phones signed in to the same sync account can use your PC's relay.
- One PC per account — only one PC per account relays at a time; a newly connected PC replaces the previous one.
Before you start
- The PC launcher is signed in to your sync account, and the mobile app is signed in to the same account.
- The API service on your PC works on its own — simplest check: chatting in KOA on the PC with that address works fine.
- While using the relay, keep the PC on and the launcher running (it's your PC doing the work for your phone).
PC setup
-
Find the switch
Open the launcher's API page, find the "Remote Relay" section, and check "Enable Remote Relay".
-
Enter the local API URL
In "Local API URL", enter the address you normally use in KOA on this PC, e.g.
http://127.0.0.1:3000/v1. Copy it exactly as it works on the PC, including any trailing path like/v1. -
Confirm it's connected
After a moment the status below the switch shows "Connected". From then on the launcher reconnects automatically at startup — nothing else to do.
Mobile setup
-
Confirm the PC is online
Open the mobile app's "API" settings page, find the "Via My PC" card, and confirm it shows "PC Online".
-
Enter the API key (if needed)
If the API service on your PC requires a key, enter it in the card's "API Key" field; leave it empty if the service needs no authentication.
-
Pick a model and enable
In "Chat Model" (or "Fast Model"), open the preset dropdown and choose "Via My PC", tap "Fetch" to load the model list, pick a model, and save. Alternatively, fetch a model right on the "Via My PC" card and tap "Enable" to switch the chat model in one tap.
From now on, conversations on your phone go through your PC to the local API — streaming replies and model switching work just like a direct connection.
Troubleshooting
| Symptom | Cause | Fix |
|---|---|---|
| Phone shows "PC Offline" | The PC-side relay isn't connected | Confirm the PC is on, the launcher is running, and the API page shows "Connected"; make sure both ends use the same sync account |
| Fetching models returns 404 | Local API URL is wrong | The "Local API URL" on the PC must match exactly what works for chatting on the PC, including path suffixes like /v1 |
| Fetching models returns 401 / 403 | The local API requires a key | Enter the key in the "Via My PC" card on the phone |
| A previously connected PC dropped | Another PC enabled the relay | Only one PC per account can relay at a time; the newer connection replaces the older one |
| Replies are a bit slower than on PC | Requests take an extra hop through the cloud | Expected; speed also depends on your PC's upload bandwidth |
When the PC shuts down or sleeps, the relay disconnects and the phone temporarily loses this API. For long trips away, set the PC's sleep policy to "Never" — or use a cloud provider's API instead.