Gateway

Your code names a model as a bare id. Which provider answers is operator configuration: the gateway is the single OpenAI-compatible endpoint the box sends every model call to, and an operator sets it once on the Model provider screen in Studio. Point it at OpenRouter, at a gateway on your own machine (Ollama, LM Studio, LiteLLM, vLLM), or at any endpoint that speaks the OpenAI wire format. Swapping the provider does not change your code.

The screen has two tabs: Configuration holds the endpoint and its key, and Models lists what that endpoint advertises, so you can copy the exact id into your code.

Who calls the gateway

Your own code is one caller among several. These all resolve through the same endpoint:

Who calls Which model it asks for
Your deep agent The model you pass to defineDeepAgent(...) in its index.ts. It drives the agent's main loop.
A tool or a workflow step The model you pass to stackbone.ai for a one-off completion, embedding or image.
Retrieval The embedding model behind stackbone.rag: the model you pass on an ingest or a retrieve call, or openai/text-embedding-3-small when you pass none.
Guardrails The Guardrail checking model, asked when a rule needs judgement instead of a fixed pattern.
Evals The Judging model that grades rubric criteria and the Simulator model that plays the end user.
Built-in workflows The Default model, plus the Auto-map model override for the field-mapping workflow.

The guardrail, judging, simulator and default models are Studio settings, and you pick them in Settings › General, covered below. The agent, tool and retrieval models come from your own code.

Configure the provider

Open Settings › Model provider and stay on the Configuration tab.

A saved provider. The strip at the top shows what is in effect: the badge, the base URL, and the stored key as a mask.

Field What it does
Preset Prefills the base URL below. OpenRouter, Ollama and LM Studio fill in their usual address; Custom leaves the field free for your own gateway.
Base URL The OpenAI-compatible endpoint. This is the whole contract: if it answers GET /models and POST /chat/completions, it works.
API key Optional. A local gateway usually needs none. The box keeps the key on the server and never sends it back to the browser, so the field shows a mask.
Test connection Probes the endpoint in the form without saving anything. Use it before you commit a change.
Save Persists the endpoint and applies it to the running box. Saving with an empty key clears the stored one.

A green Connected with a model count means the endpoint answered. An amber note under it means the endpoint listed its models without asking for credentials, so Studio could not check the key. A wrong key then surfaces on your first real model call.

Guided setup at the bottom of the tab replays the first-run steps. It leaves your saved provider alone, so use it when you want to walk a colleague through the setup.

When the box's environment overrides the screen

If the box exports MODEL_PROVIDER_BASE_URL or MODEL_PROVIDER_API_KEY, the box uses those values and ignores anything saved here. Studio turns the form read only, names the variable in effect, and hides Save, because saving would change nothing. Unset the variable on the box and restart it to configure the provider from Studio instead. The older OPENROUTER_BASE_URL and OPENROUTER_API_KEY names still work, and the screen tells you when it sees one.

Test connection stays available in this state. It probes the live endpoint and writes nothing.

See what the provider resolves

The Models tab lists what the effective endpoint advertises. This list comes from your provider, so it changes whenever their catalogue does.

Copy the id from any row and paste it into your code. The badge under the name is the copy control.

Column What it tells you
Model The display name, with the creator/model-name id under it. Click the id to copy it.
Type Chat, Image, Embeddings or Other. An endpoint that declares no type lands in Other.
Context The context window the provider reports, in thousands of tokens.
Input / 1M, Output / 1M USD per million tokens. Free means the provider priced it at zero. A dash means it reported no price for that direction.

Filter by type or search by name, and sort by input price. The counter on the right reads "shown of total", so you know how much the filter cut.

Searching for an embedding model. Retrieval needs a model of this type, and a chat id here would fail.

Point the base URL at a gateway on your own machine and those price and context columns often fill with dashes. Nothing is broken: that provider reports less about each model. For what a provider resolves, see Which models can I use?.

Pick the model each platform tool uses

Open Settings › General. Each knob is a separate model because these tools run at different times. A guardrail asks on every turn; a judge asks only while an eval suite runs.

The Default model is what the built-in workflows ask for. Auto-map inherits it until you override it.

Knob What it drives
Default model The chat model the built-in workflows ask for. It does not change your agents: those name their own model in their own code.
Auto-map model Overrides the default for the field-mapping workflow only. Leave it empty to inherit.
Guardrail checking model The model a guardrail asks when a rule needs judgement. It runs on every turn, and twice on a turn checked both ways, so keep it cheap.
Judging model Grades an eval suite's rubric criteria. You spend nothing until a suite runs, so a stronger model here costs nothing the rest of the time.
Simulator model Plays the end user when an eval case stops to ask a question. Keep it different from the judging model.

Judge and simulator are separate on purpose. A model that plays the student and then grades the answer is partly agreeing with itself.

The pickers offer chat models only. An image or an embedding model cannot answer a chat call, so Studio leaves them out. Your changes on this screen apply when you press Save.

From your code

Inside a tool or a workflow step you name a model and call the gateway. The runtime injected the credential when the box booted, so the ambient stackbone handle already has it.

import { stackbone } from '@stackbone/sdk';

async function summarise(text: string) {
  'use step';
  const result = await stackbone.ai.chat.completions.create({
    model: 'google/gemini-3.7-flash',
    messages: [{ role: 'user', content: `Summarise:\n\n${text}` }],
  });

  if (result.error) throw new Error(result.error.code);
  return result.data.choices[0]?.message.content ?? '';
}

To read the catalogue from code instead of from the screen, call stackbone.ai.models.list(). It returns the same rows the Models tab renders.

Before you configure a provider

A model named as a bare id needs a provider to resolve it, so a box with none cannot build an agent's graph. What each box does about it differs.

stackbone dev holds your workflows and your deep agents back at boot and keeps Studio and the Model provider screen up, so the first thing you read is the setting to fix rather than a wall of errors about your code. Save a provider (or finish the guided setup) and the held work starts in place, with no restart.

A deployed box starts and serves. An agent whose model cannot resolve registers degraded, and a chat call to it answers 503 naming the reason. Save a provider and the box retries every degraded agent, again with no restart.

On either box, a call your own code makes before that point comes back with openrouter_key_missing rather than a network error, and the Models tab stays disabled until an endpoint resolves.

Read more

BUILT WITH ❤️ FROM CANADA AND SPAIN