Cloud Agent Model Providers

Every Cloud Agent creation request selects an organization-managed provider:

{
  "model_provider": {
    "type": "managed",
    "id": "your-provider-id"
  }
}

Provider credentials stay in Runta’s secret management. The agent creation API accepts a provider reference; it does not accept an inline API key. Use the shell environment from the quickstart for the examples below.

Connect and discover providers

Connect a provider in the dashboard’s Secrets area. The provider catalog supports OpenAI API, Anthropic API, Kimi API, and Compatible API configuration. Select an endpoint, model, protocol, and credential appropriate for the provider.

List the providers available to your API key’s organization:

curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  "$RUNTA_API_URL/v2/model-providers" | jq .

The response contains organization_id and a model_providers array:

Field	Meaning
id	Identifier to pass as model_provider.id.
secret_id	Reference to the managed credential, not its value.
display_name	Human-readable label.
protocol	openai_responses, openai_chat, or anthropic_messages.
base_url	Upstream provider endpoint.
default_model	Model configured for new agents; may be null.
header_name	Credential header, such as Authorization or x-api-key.
value_template	Credential projection template, such as Bearer ${secret}.

Use an ID from this response rather than assuming IDs are the catalog names openai or anthropic. The public API exposes provider listing and updating. Initial connection and credential authorization are dashboard workflows.

Update a provider

PATCH /v2/model-providers/{provider_id} requires the full set of configuration fields, including a nullable default_model. It is not a partial-field patch. For example, change an existing custom provider’s display name while retaining its routing:

PROVIDER=$(curl --fail-with-body --silent --show-error \
  -H "Authorization: Bearer $RUNTA_TOKEN" \
  "$RUNTA_API_URL/v2/model-providers" |
  jq -e --arg id "$PROVIDER_ID" '.model_providers[] | select(.id == $id)') || exit 1

printf '%s' "$PROVIDER" |
  jq '{
    display_name: "Research provider",
    protocol, base_url, default_model, header_name, value_template
  }' |
  curl --fail-with-body --silent --show-error -X PATCH \
    -H "Authorization: Bearer $RUNTA_TOKEN" \
    -H "Content-Type: application/json" \
    --data-binary @- "$RUNTA_API_URL/v2/model-providers/$PROVIDER_ID"

This updates the provider definition, not the credential value. Existing runtimes keep their configured routing; create a fresh runtime to select a different provider or model configuration. The endpoint updates stored custom providers, not the synthetic entries representing connected subscriptions.

Use a Codex subscription

A connected, ready Codex subscription with its managed secret appears in GET /v2/model-providers. Select that entry’s id exactly as you would an API provider. It is the connected credential’s ID.

The current Cloud Agent implementation routes this provider through openai_responses to https://chatgpt.com/backend-api/codex, with model gpt-5.6-sol. Use the returned provider configuration rather than substituting the ordinary OpenAI API endpoint. Subscription credentials do not authenticate to that endpoint.

The agent still runs Pi. Runta projects the subscription token and account identity only onto the trusted subscription route; the guest receives neither the real token nor a Codex credential file. The Cloud Agent image includes a subscription-specific Pi adapter.

If the subscription is absent from the list, check that it is ready, belongs to the same organization, and is visible to the API key. A caller without AI-agent-auth read access can still receive custom providers while subscription entries are omitted. The Cloud Agents catalog currently adds Codex subscriptions; it does not add Claude subscriptions.

Sharing a provider across agents

Model routing is runtime-scoped. When adding a harness with runtime.type: "existing", the provider protocol, base URL, effective model, and credential must match that runtime’s existing configuration. A mismatch is rejected before the runtime is updated.

Use a fresh runtime for another provider. See Agent lifecycle for the existing-runtime request.

Reference: List providers and Update provider.