Kilo Code Setup Guide: Custom Endpoints and Profiles

Kilo Code is a VS Code coding agent in the same lineage as the other open extensions in that space, which means two useful things if you have configured one of those before: the provider fields will feel familiar, and the parts that trip people up are the same parts.

Connecting it to your own endpoint takes three values — base URL, key, model identifier. Getting good behaviour out of it takes a few minutes more, spent on the model metadata block and on which model runs in which mode.

Connecting to a custom endpoint

Open the extension panel and find its settings, usually behind a gear icon in the panel header rather than in the main VS Code settings tree. Look for the provider selector and choose the generic OpenAI-compatible option rather than a named vendor, because that is the choice that reveals a base URL field.

The base URL should end at the version segment of your provider path — the whole root of the OpenAI-compatible surface, with no operation path appended. This is the single most common mistake, and it fails as a 404 that reads like an authentication problem. The boundaries of that compatibility are worth knowing, and the compatibility explainer covers where it stops holding.

The key goes in as a bearer token. The model identifier is sent upstream verbatim, so it must match exactly what your provider publishes; a name that does not exist errors rather than falling back to something similar. If there is a test or verify control, use it before touching anything else — it proves all three values agree with each other, which a saved form does not.

The metadata block is not decoration

Underneath the credentials there will be fields describing the model: a context window size, a maximum output size, capability toggles for images and for tool or function calling, and often input and output prices.

These exist because the extension ships metadata only for providers it knows. For an arbitrary endpoint it has to be told. Three of them change behaviour rather than just display.

The context window governs when the extension compacts or truncates conversation history. Set it below the real window and long sessions get summarised aggressively, throwing away detail the agent needed; set it above and requests fail partway through a task. The maximum output size caps a single response, and setting it too low truncates a large file write halfway — which surfaces as a mangled edit rather than an error, so it is easy to misdiagnose as a bad model. The tool-calling toggle is what turns the thing from a chatbot into an agent; with it off for a capable model you get descriptions of changes instead of changes.

The price fields usually only feed the in-panel cost readout. Fill them in if you are on per-token billing and want that number to mean something; ignore them otherwise.

Modes and profiles

Kilo Code separates work into modes — planning and architecture, writing code, answering questions, debugging, orchestrating subtasks. Each mode has a different job, and the extension lets you bind a saved provider profile to a mode so the model changes with it.

The configuration worth reaching for is a strong reasoning model on the planning and debugging modes and a faster, cheaper one on the code mode. Planning mistakes are cheap to catch and expensive to inherit; code-mode work is largely mechanical editing once the plan is agreed. Debugging is the exception to the cheap-model instinct, because it is the task where a weak model wastes the most of your time — what actually makes a model good at debugging is a different property from raw coding score.

Create the profiles first, name them for the endpoint and model rather than for the mode, then bind them. Profiles named after their purpose become confusing the moment you reuse one.

Approvals, and the command you did not read

The extension can auto-approve reads, edits and terminal commands independently. The temptation after a good session is to approve everything, which is precisely when it runs something destructive.

A defensible baseline: auto-approve file reads, because they are constant and harmless. Review edits until you trust the model on this codebase. Do not auto-approve arbitrary terminal commands on a machine that holds credentials, and if you relax that, do it inside a container or VM rather than on your host — the reasoning is laid out in agent sandboxing.

Work on a branch and commit often. Git is the only undo that reliably survives a multi-file agent session, and it is a great deal faster than reading a diff you did not expect.

Rules and MCP servers

Rule files in the repository apply to every request, and they do more for output quality than the model choice does. Put the concrete things in: package manager, test command, generated directories that must not be hand-edited, the error-handling convention, and an explicit instruction to make the smallest change that satisfies the request and ask before refactoring adjacent code.

The extension also supports MCP servers, which add tools such as database access, issue trackers or documentation search to the agent loop. Add them one at a time. Every server you connect enlarges the tool list in every request, which costs tokens and dilutes the model attention across more options — see what MCP actually is before wiring up five of them.

Verifying and troubleshooting

Test smallest first: a one-sentence answer proves the three connection values agree; asking it to read a named file and quote a line proves tool calling and workspace access; only then hand it a real task.

When it fails, a 401 is a key from a different provider or whitespace from a paste. A 404 on the endpoint is a duplicated version segment. A 404 naming the model is an identifier your provider does not serve. Constant history compaction means the declared context window is too small. Truncated file writes mean the output cap is too low. An agent that narrates instead of editing means tool calling is off or unsupported.

The takeaway

Set base URL, key and exact model name, then spend the next ten minutes on the metadata block and on per-mode profiles — that is where the difference between a useful agent and an expensive one is decided. If you are comparing extensions in this family, the same three facts configure Cline and Roo Code, so trying another costs a base URL and a model name rather than a migration.