Gateway

Your code names a model as a bare id. Which provider answers is operator configuration: the gateway is the OpenAI-compatible endpoint the box sends model calls 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, but every model id your code names must exist on the new provider.

A box can also hold several model providers at once, such as OpenAI next to a local Ollama. This page covers the first one. OpenAI and Ollama in the same box adds a second one and shows how each call finds its provider.

The left column lists the provider presets not yet in use. Once you save one, its preset leaves the list and the provider shows above it as a row under Active. On the right are the form of the provider you open and the models the box's providers advertise, so you can copy the exact id into your code.

Who calls the gateway

Your own code is one caller among several. These all go through the box's model providers:

Who calls Which model it asks for
Your deep agent The model picked for it in Studio, or the model in its index.ts, or the Default model. 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 model on the Guardrail classifier card, asked when a rule needs judgement instead of a fixed pattern.
Evals The model on the Eval judge card, which grades rubric criteria, and the one on the Persona simulator card, which plays the end user.
Studio copilot The model picked on its catalog entry, or the Default model.
Built-in workflows The Default model, or the model on the Auto-map card for the field-mapping workflow.

The Default model is a Studio setting on Settings › Workspace. The models of the guardrail classifier, the eval judge, the persona simulator and Auto-map are picked on Settings › Model defaults, and the copilot's on its catalog entry, as covered below. The tool and retrieval models come from your own code. An agent's model starts in your code too, and an operator can pick another one for it on the agent's Models block, without a redeploy. See stackbone.models for the full order.

Configure the provider

Open Settings › Model provider and pick a named provider in the list on the left. For any other OpenAI-compatible endpoint, click + Add a custom provider under the list. Its form opens on the right.

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. + Add a custom provider leaves it 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.

Remove the provider

Remove provider deletes the base URL, key and preset you saved here, after you confirm. The running box stops using them at once. Providers you added beside it stay. If there are none, agents and workflows that call a model stop answering until you set another provider. The button shows only when a provider is saved on this screen.

A value the box exports as MODEL_PROVIDER_BASE_URL or MODEL_PROVIDER_API_KEY stays in force, and the screen names it after the removal. With both exported, the button is disabled: remove the variables from the box instead. Removing does not replay the first-run steps.

Guided setup at the bottom of the screen 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, the box uses that endpoint and Studio makes the endpoint field read only. If it exports MODEL_PROVIDER_API_KEY, the box uses that key and Studio makes the key field read only. Studio identifies the locked field as the endpoint or key without showing the variable name. When the box exports both values, the whole form is read only and Save is hidden. Unset the corresponding variable on the box and restart it to configure that field from Studio instead. The older OPENROUTER_BASE_URL and OPENROUTER_API_KEY names still work.

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

See what the provider resolves

The model list under the form shows what the effective endpoint advertises. This list comes from your provider, so it changes whenever their catalogue does. With several providers, it lists the models of every one, each with the name of the provider that serves it.

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 › Workspace to pick the Default model. It is the chat model the built-in workflows ask for, the model the Studio copilot falls back to, and the last fallback for an agent or a model key that names none. Changes on this screen apply when you press Save.

The Default model. The card links to the Model defaults screen for the other platform models.

Every other platform model sits on Settings › Model defaults, one card per caller, beside the prompt that caller runs on. Each 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.

Card on Model defaults What its model drives With nothing picked
Auto-map The field-mapping workflow. The Default model
Guardrail classifier The check a guardrail makes when a rule needs judgement. It runs on every turn, and twice on a turn checked both ways, so keep it cheap. openai/gpt-4o-mini
Eval judge 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. openai/gpt-4o-mini
Persona simulator Plays the end user when an eval case stops to ask a question. Keep it different from the judge. openai/gpt-4o-mini

A pick on Settings › Model defaults saves at once. The pickers on both screens offer chat models only. An image or an embedding model cannot answer a chat call, so Studio leaves them out. System prompts and models covers the cards, and the prompts beside them.

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 screen's model list 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. Each box handles that differently.

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 screen lists no models until a provider is set.

Read more

  • Which models can I use?: what a provider resolves, and the creator/model-name id form.
  • How do I choose a model?: where each id is set, and how to measure a swap instead of guessing.
  • stackbone.ai: chat, embeddings, images, the catalogue call, and every ai_* error code.
  • stackbone.models: how an operator picks the model an agent, a subagent or one of your model keys runs on.
  • Guardrails: which checks ask a model and which never do.
  • Evaluation: what the judging and simulator models do during a suite.
  • Getting started: the first run stops until a provider is configured.
BUILT WITH ❤️ FROM CANADA AND SPAIN