---
title: Model providers
description: The upstream a published agent version runs against — Subako's own models, or your account with an upstream of your own.
sidebar:
  order: 6
---

A **model provider** is the upstream an agent version is published against. A workspace sees two kinds, and `model-provider list` tells them apart in its `type` column:

| `type` | Whose account the call runs on | Who registers it |
| --- | --- | --- |
| `platform` | Subako's, drawn from your credit balance | The deployment's operator |
| `workspace` | Yours, billed by your upstream | You |

```bash
subako model-provider list
```

Both are published against the same way, by passing the provider's id to `--model-provider`.

## Platform providers

Subako Cloud ships one, `Subako`, and every workspace can publish against it without registering anything or holding an upstream key. It speaks `openai_responses` and serves three models:

| Model | Best for |
| --- | --- |
| `sparrow` | Simple, high-volume agent tasks — the lightweight one |
| `crow` | Everyday tasks, balancing capability against cost |
| `hawk` | Complex reasoning and coding — the largest one |

Name one of them in the version config's `model`, and the provider's id in `--model-provider`:

```json agent.json
{
  "system_prompt": "You are a helpful assistant.",
  "model": {
    "format": "openai_responses",
    "model": "hawk",
    "max_tokens": 8192,
    "context_window": 128000
  }
}
```

These calls draw on the organization's credit balance, per token and at a rate that differs by model — [Plans and billing](/concepts/plans-and-billing) carries the rates. A platform provider belongs to the deployment rather than to your workspace, so updating or deleting one is refused with a 403, and it does not count against the plan's model-provider limit.

:::note
A self-hosted deployment offers whatever platform providers its operator declared, which may be none. `model-provider list` is the authority on what a workspace can publish against, and on which model ids each provider accepts.
:::

## Bringing your own

Register an upstream account of your own to run against it directly. Subako does not bill these calls — you pay your upstream.

```bash
subako model-provider create \
  --format anthropic \
  --display-name "Anthropic production" \
  --base-url https://api.anthropic.com < key.txt
```

The API key is read from stdin, never a flag. `--description` takes a longer note; it is empty when absent.

## Formats

A format is the protocol the upstream speaks, not a brand. `subako model-provider formats` lists what this server accepts:

| Format | Base URL it expects |
| --- | --- |
| `anthropic` | The Anthropic Messages API, e.g. `https://api.anthropic.com` |
| `openai_responses` | An OpenAI Responses-compatible endpoint |

Any upstream speaking one of these protocols works — the hosted service, a gateway you run, a compatible provider — because the base URL is yours to choose.

## Format has to match

An agent version may only publish against a provider whose format matches the one its model configuration speaks. Publishing an `anthropic` config against an `openai_responses` provider is refused at publish time.

```json agent.json
{
  "system_prompt": "You are a helpful assistant.",
  "model": {
    "format": "openai_responses",
    "model": "your-model-id",
    "max_tokens": 8192,
    "context_window": 128000
  }
}
```

## The key never leaves the proxy

When a run is claimed, the engine is handed a **model proxy binding**: a URL and a run token minted fresh for that claim. Model calls go through the proxy, which holds your provider key and attaches it.

The engine never has the key. A stale attempt's token stops working the moment the run is re-claimed, so a run that was retried cannot keep spending against your account from its old attempt.

## Deleting

```bash
subako model-provider delete <model-provider-id>
```

This permanently deletes the provider, taking its stored API key with it. Sessions already running remain, but further calls made through it are refused. Rotate by creating a new provider and publishing a new agent version against it.

Only a provider your workspace registered can be deleted; a platform one is refused with a 403.