Network boundary

BotConnector talks to three different surfaces depending on where the model runs. Mixing them up is the usual reason a request hangs or lands on the wrong service.

Cloud

Cloud requests leave your machine over HTTPS to one host:

https://api.botconnector.id/v1

That is the base URL for every hosted route in this section — models, chat completions, Messages, Responses. There is no second host, no alternate port, and no plain-HTTP endpoint. Put it in base_url / baseURL for an OpenAI-compatible SDK and the SDK's own routes line up with it.

Local, through the CLI

The public CLI and TUI discover an Ollama runtime on the loopback interface:

http://localhost:11434
http://127.0.0.1:11434

If a local model call fails while the hosted API works, check that address first: an Ollama process that is not running, or one bound to a different port, looks identical from the client side.

Local, through BotConnector Core

The desktop application runs its own runtime — BotConnector Core — and serves an OpenAI-compatible API on a different loopback port:

http://127.0.0.1:11435/v1

This is the surface the botconnector runtime and the preview Python and TypeScript clients talk to; Core owns model loading and serving. It is a preview surface rather than part of the public npm CLI contract, so the CLI does not use it: bccli goes to Ollama on 11434 or to the hosted API.

Two loopback ports, two different processes. If you are following the Python or TypeScript pages, you are on 11435 and Core must be running. If you are following the CLI pages, you are on 11434 or the cloud.

Choosing

Use the cloud base URL when you want the catalogue's hosted models and per-token billing. Use Core on 11435 when you are working with the desktop runtime and its preview SDKs. Use Ollama on 11434 when the model must stay on the machine and you are driving it from the CLI. They are separate base URLs, not modes inside one API.