Part II · Instance setup

Providers¶

A provider config is a named connection to a model backend: which API to speak, where to reach it, and how to authenticate. Every model an agent uses in Foundry resolves through one of these configs.

How the list is organised¶

Configs are shown as pairs, not as a flat list. A vendor you can reach two ways — an API key and a subscription — is one card with two halves, because they are two doors onto the same backend rather than two unrelated connections; the card tells you which halves exist and lets you add the missing one in place.

A config with no partner is a straggler, and stragglers are shown rather than hidden. That is deliberate: a connection that does not fit the pairing model is exactly the one you need to see, and a list that quietly dropped it would be lying by omission.

What a provider config consists of¶

Three things, each with a distinct job:

• API schema — the wire format Foundry speaks to this backend: openai, openai-compatible, anthropic, google, or google-vertex-anthropic. The schema decides which request shape, endpoints, and auth methods are even possible.
• Catalog binding — "the provider this config talks to": the models.dev catalog entry behind the connection. The binding — not the free-text name — is what drives the model list, pricing, and which subscription mechanism (if any) is available for this config.
• Credentials — the auth method and secret, encrypted at rest. Which auth methods are offered depends on the schema: API key, API key (Bearer), Service account (e.g. a Google Cloud SA JSON for Vertex), Application default credentials, No auth, or one of the three subscription methods — Subscription (plan key), Subscription (sign-in), and Subscription (Claude Pro/Max). The three subscriptions are not variants of one thing; see Billing mode below.

Catalog binding — why it matters¶

Edit provider · Catalog picker

You can name a config anything ("Anthropic prod", "z.ai coding plan"). The catalog binding tells Foundry which vendor is actually behind it, and three things resolve through it:

1. Models — which models the Models tab lists and prices for this config.
2. Pricing — per-million-token costs are read from the models.dev catalog for the bound vendor.
3. Subscription capability — whether a subscription may be used instead of API-key billing, and which mechanism that vendor uses. This is catalog data about the vendor, not a per-config toggle — and it is read from the binding, not from the config's name, so a config called openai-api still offers what OpenAI offers.

An unbound config still works for plain API calls, but loses catalog pricing and subscription support — bind every config you create.

Billing mode: API key vs Subscription¶

Edit provider · Billing mode

Where the bound vendor supports both, the config offers a billing-mode choice:

• API key — the instance pays per token through the key stored here. "Pay per token with your own provider key." This is the shared default every user falls back to.
• Subscription — usage draws on a plan instead of per-token billing.

"Subscription" is not one thing. The catalog entry decides which of three mechanisms the vendor uses, and they differ in the one respect that matters to you as an admin: whether there is anything to enter here at all, and whose account pays.

Sign-in (OAuth) — per-user only¶

This is the mechanism the "per-user by design" rule was written for, and it still holds for this mechanism. Foundry deliberately refuses to let you select it at instance tier, because one instance-wide OAuth session would pool every user's traffic through one person's login. The drawer says so where the key field would be: "Subscription sign-in happens per-user from My Account — nothing to configure here." See Your account.

Plan key — an instance-level credential¶

A coding-plan key is a credential, and it is entered here like any other. The drawer shows the plan's badge and the endpoint the key is pinned to — the key is sent only to the plan's own endpoint, never to the vendor's general API, because the two are billed differently. The field is labelled Subscription key, with the helper "A flat-fee plan key — draws on \<plan name>, not per-token API billing."

Note the consequence: this is a shared instance asset paid for by one subscription. That is exactly what the Terms step below asks you to acknowledge.

Session — Anthropic Claude Pro/Max, keyless¶

Anthropic subscriptions run through a container-local session, and this is the one credential Foundry stores nothing for. The status card is status, not a form:

• It is titled Subscription (Claude Pro/Max) and carries a no key badge.
• There is no secret field, and there must not be one — the credential is a Claude Code CLI login on the container's filesystem, reached over a loopback proxy. A key box here would collect an Anthropic API key this provider never sends anywhere.

• To establish or re-establish it, an operator runs the login inside the backend container:

  docker compose exec -it backend claude auth login
  

• One container holds one session, so one instance runs on one person's subscription. There is no per-config or per-user variant of this mechanism.

The Terms acknowledgement¶

Selecting Subscription at instance level adds a §3 · Terms section to the drawer, before Connection, hinted "Read this before connecting a personal subscription to a shared instance." It appears for every instance-level subscription — plan-key vendors included, not only the keyless ones.

The disclosure copy is signed and binding; it is reproduced here verbatim rather than summarised.

Subscription accounts are personal.

Most AI vendors license consumer subscriptions to a single human user. Connecting a subscription at instance level makes one personal account serve every user and every automated run on this instance — usage most vendors' terms do not permit, and which can lead to rate-limiting, suspension, or termination of that account by the vendor.

Whether this use is acceptable under your agreement with the vendor is the operator's decision — Foundry surfaces the choice; it does not make it. The safer defaults remain available: each user connecting their own subscription under My Account, or an API key, which is licensed for programmatic multi-user use.

A per-vendor addendum follows for OpenAI, z.ai, and Anthropic, and then an acknowledgement checkbox:

I understand this subscription is licensed to one person, and I choose to use it as this instance's default.

Until you tick it, Save does nothing and the reason sits beside the button rather than behind a rejected save: "Tick the acknowledgement to continue." The acknowledgement is not stored — it is asked again every time you save such a config, including on edit. That is deliberate: it is a decision, not a setting.

Test, Edit, Delete¶

Every config row has Test, Edit, and Delete.

Test proves the credential, endpoint, and schema actually work — not a ping, not a syntax check. A failed test shows the provider's error verbatim, because the upstream message ("invalid x-api-key", a 403 from Vertex IAM) is exactly what you need to fix the problem — Foundry does not paraphrase it away.

What "Test" does depends on what there is to test, and the three cases are deliberately different:

• A config with a stored key — a real one-token completion against the backend, capped at five seconds. This is the case above.
• A Claude Pro/Max session config — there is no key to probe with, so Foundry probes the thing that can actually fail: the container's Claude Code session. A green result names the account and plan; a lapsed session reports that "every turn on this provider will fail" and gives you the re-login command. If Foundry cannot establish either answer — the CLI is missing, the probe times out, the output is unreadable — that is reported as a failure, never as a pass.
• A config that stores no key at all (an unbound or credential-less row, including Vertex ADC) — the test does not invent a probe. It answers: "This config has no stored key to test — use 'Test this subscription' instead." Note that the action this message names is not on the screen yet; read it as "there is nothing here to test", and use Save & Test on a bound subscription config instead.