KoboldCpp remote API: no model loaded, uncensored builds

Where the remote API option sits in KoboldCpp

KoboldCpp is a single executable that runs GGUF models on your own CPU or GPU and serves the Kobold Lite interface at http://localhost:5001. Its README (read on 28 October 2026, release 1.123.1) also documents the other direction: "KoboldCpp allows connecting the web UI directly with a supported external AI provider instead of using a local model", and names OpenAI Compatible among the supported services. The instruction is one line: "To connect, start with --nomodel or select Allow Launch Without Models in the launcher's Loaded Files tab."

That is the whole trick. The program you already have becomes a local front end for models your machine cannot hold, with your stories, World Info and settings where they were. The API here speaks the OpenAI wire format on one key, so the OpenAI Compatible provider is the one to pick. Local models stay available: close the session, launch again with a GGUF selected, and Lite is back on your GPU.

This guide is for people who run KoboldCpp. If you use Lite in the browser at lite.koboldai.net and have no KoboldCpp at all, the KoboldAI Lite custom API guide covers that page field by field. If a script of yours talks the Kobold Classic shape, the KoboldAI Classic API explainer shows how that differs from what this API answers. To pick a model first, the best uncensored LLM leaderboard ranks every build by job and price.

What you need

• KoboldCpp 1.123.1 or later: koboldcpp.exe, koboldcpp-linux-x64 or koboldcpp-mac-arm64 from the releases page. No model file is needed for this route.
• A key from the console. It starts with sk-ullm- and is shown once. The balance is prepaid from $10; a key with nothing on it is accepted but the first turn answers 402.
• The base URL https://api.uncensoredllm.ai/v1. It ends in /v1, which matters for one tickbox below.
• A model id from the model list, for example cydonia-24b-v4.3. The Fetch button in Lite loads the same list, so you can also pick it there.

Launch KoboldCpp without a model

Two ways, same result: Lite opens in your browser on port 5001 with no model loaded and a No Models Loaded box asking whether to connect to an external API service.

The launcher

1. Open KoboldCpp. The launcher window appears.
2. Go to the Loaded Files tab and tick Allow Launch Without Models. Leave the Text Model field empty.
3. Click Launch. The browser opens at http://localhost:5001.

The command line

The wiki describes --nomodel as the flag that "launches the KoboldAI Lite UI alone without loading a model"; --launch opens the browser once the server is up.

If 5001 is taken by another KoboldCpp or a different program, pick another port. The wiki: "--port [portnumber] Port to listen on. (Defaults to 5001)".

To make the no-model launch a one-click habit, save it. The wiki calls .kcpps files "configuration files that store your KoboldCpp launcher preferences and settings"; --exportconfig writes one from the current arguments and --config remote.kcpps loads it again. Keep one .kcpps for the remote session and one per local model.

GPU flags such as --gpulayers, --contextsize, --usecuda and --usevulkan do nothing on this route. They shape how a local GGUF is loaded; with no model loaded there is nothing for them to shape, and the context limit is the remote model's window.

The KoboldCpp remote API settings

In the Lite page that just opened, answer Yes to the No Models Loaded box. The Select your AI provider popup is the same one the hosted Lite shows; from then on AI in the top bar reopens it. Lite's source, read on 28 October 2026, gives the labels below.

Provider

OpenAI Compatible API

In the Select your AI provider list

OpenAI API URL

https://api.uncensoredllm.ai/v1

Keep Add Ver. Num ticked

API Key (Required)

sk-ullm-live-…

Created in the console, shown once

Model

cydonia-24b-v4.3

From Fetch, or typed with Custom

Mode

Chat-Completions

Not Text-Completions or Responses

Use CORS Proxy

unticked

Non-Standard Fields

unticked

1. Choose OpenAI Compatible API in the provider dropdown.
2. Paste https://api.uncensoredllm.ai/v1 into the OpenAI API URL field and keep Add Ver. Num ticked. Lite's note on that box: "Usually OpenAI Compatible APIs end with /v1. If they do not, uncheck this box." This one does.
3. Paste the key into API Key (Required).
4. Click Fetch and pick an id from the list your key can reach, or click Custom and type it exactly as the model list shows it.
5. Set Mode to Chat-Completions. Every model here answers on /chat/completions; on Text-Completions, Lite calls the older text-completion endpoint.
6. Leave Use CORS Proxy unticked. Lite's panel says "API keys are used with OpenAI API directly, unless CORS proxy is used." Lite served from your own localhost calls the API straight from your browser; the key never passes through a third machine.
7. Leave Non-Standard Fields unticked. Lite's own warning: it would "Send all extra non-standard samplers (e.g Min-P, Top-K, Top-A, TFS). May be rejected by many endpoints."
8. Click Ok. Lite connects and the first turn goes to the API.

One line in that panel is easy to miss: "Reconnecting resets all custom OpenAI URLs." After you switch to a local model and back, the URL and key must go in again, unless you saved them in the popup's Favorites row, which keeps the pair in your browser. Skip Favorites on a shared computer.

Local GGUF or the remote API: which models go where

The honest split is by memory. KoboldCpp's wiki gives system RAM for a Q4_0 GGUF at 2048 context: a 13B needs at least 16 GB, a 30B at least 32 GB, a 65B at least 64 GB, before any context beyond 2K. Offloading to a GPU trades RAM for VRAM, it does not shrink the model. The four builds below all carry the roleplay tag in the catalog; the middle column is the wiki's row for their size class, the prices are read from the live catalog when the page renders.

RAM rows from the KoboldCpp wiki, read on 28 October 2026. Context windows from the live catalog on 2026-11-09. Context Size is the window, capped at 16,384, minus a Max Output of 512.

• mythomax-l2-13b is the build most Kobold users have run locally. Its window is the same here as on your disk; the remote route only saves the download and the 16 GB.
• cydonia-24b-v4.3 is the 24B roleplay tune the SillyTavern and Lite guides on this site start from. Local, it is the first size where an 8 GB card runs out of layers to offload.
• gemma-4-31b-novelist is a story tune with a long window. Local, a 31B at the 32 GB row plus a long context is a workstation, not a gaming PC. Remote, Context Size is the only limit you set. More of the family is on the uncensored Gemma page.
• uncensored-ai-roleplay is this site's own roleplay route. There is no GGUF to download; it exists only behind the API, which is the case where the remote option is the only option.

A rule that holds up: keep 7B to 12B tunes local if they fit your card and you like them, and put everything from 24B up on the API. The model list shows the window and both prices for every id, so the same check works for any build you were about to download.

Presets: Usage Mode, Context Size, Max Output, samplers

Lite's Settings panel has the same controls on the remote provider as on a local model, with one difference the provider panel states: "Only Temperature, Top-P and Repetition Penalty samplers are used." Min-P, Top-K, Top-A, TFS and the sampler order stay in the panel but are not sent unless Non-Standard Fields is on.

These are the same starting values as the SillyTavern guide uses for an abliterated roleplay build, mapped to Lite's names. Memory and World Info in the Context panel ride along on every turn and count against Context Size, so a 500-token Memory costs 500 input tokens per turn. Lite's Autosave session option (the wiki's Persist Autosave Session) brings the story and these values back next launch; the wiki: "This option autosaves your story and settings, which will be restored the next time you start KoboldCpp again."

What an adventure session costs

The worked example: 150 turns in Adventure mode, each reply about 200 tokens. The short column sends about 2,000 tokens of story per turn; the long column sends 8,000, a longer memory and world info.

Computed at render from the catalog prices on 2026-11-09: turns × prompt tokens × input price, plus turns × 200 × output price. "Over the window" means that fill does not fit the model.

Compare that with the local side of the same session: no per-token charge, but the GGUF download, the RAM row above and the card running at full draw for the evening. Every per-token rate is on the pricing page.

Check the key before you launch

This request lists the model ids your key can reach. It is the call Lite's Fetch button makes, it costs nothing, and it separates a key problem from a KoboldCpp problem before you open the launcher.

A 200 with a list of ids means the key is good. A 401 means the key, and the message says which way:

Both bodies as the API returned them on 28 October 2026.

Troubleshooting

The launcher refuses to start without a model

Allow Launch Without Models is not ticked. Tick it on the Loaded Files tab with the Text Model field empty, then Launch. From a terminal, --nomodel does the same.

The browser does not open

Add --launch, or open http://localhost:5001 yourself. If the terminal says the port is in use, another KoboldCpp is still running: close it or pass a different --port.

The URL and key are gone after a restart

Lite's panel warns that "Reconnecting resets all custom OpenAI URLs." Save the pair under Favorites, or keep a text note of the URL and paste a fresh key from the console.

401: the key

"No API key was sent." means the key field is empty. "The API key is not valid." means it is wrong, cut short or revoked. Create a fresh key and paste it whole.

404 model_not_found: the model id

A typo in Custom, or a build that has since left the catalog. Click Fetch again and pick from the list.

404 on every turn with Fetch working

Mode is on Text-Completions, so Lite is calling the text-completion endpoint. Set it to Chat-Completions and reconnect.

402: the balance

The prepaid balance is at zero. Top up in the console; a request refused with 402 is not charged.

The reply stops mid-sentence

Max Output is too low for the mode, or Context Size plus Max Output is over the model's window. Lower Context Size to the table value first.

Samplers seem ignored

Only Temperature, Top-P and Repetition Penalty travel on this provider. Min-P and the rest are local-model settings; leaving Non-Standard Fields off is the right call.

The daily real-model check sends a fixed prompt to every model each day, so the model behind an id is the one on its label. Base URL, key and model id for other clients are on the docs page.

Questions