Per-run Model Overrides

Per-run model overrides let you choose the main agent, or computer-use, model when you create a run. Use this when your application decides which model to use at trigger time. For example, your runner UI might route simple jobs to one model and harder jobs to another, while still using one shared Cyberdesk workflow.

Why this exists

Normally, a run uses the workflow’s saved model_metadata. That is the right default when the workflow owns model selection. If your system launches many concurrent runs from one workflow, patching the workflow’s model_metadata before each run can race:

run A should use model A
run B should use model B
both runs use the same workflow
patching the workflow would mutate shared state

With a per-run model override, each run carries its own model selection. The workflow’s saved model configuration stays unchanged.

1. List Available Models

First, fetch the model configurations available to your organization:

HTTP
TypeScript
Python

curl "https://api.cyberdesk.io/v1/model-configurations" \
  -H "Authorization: Bearer $CYBERDESK_API_KEY"

const { data: modelConfigurations } = await client.model_configurations.list();

response = client.model_configurations.list_sync()
model_configurations = response.data

Each model configuration includes an id, name, provider details, and flags such as is_computer_use_model and is_archived. For the main agent, choose a model where:

is_computer_use_model is true
is_archived is false
the model matches your cost, latency, and reliability needs

Show users the model name in your UI, but store and send the model configuration id when creating a run.

2. Create a Run With a Model Override

Use main_agent_model_id when you only need to override the main agent model:

HTTP
TypeScript
Python

curl -X POST "https://api.cyberdesk.io/v1/runs" \
  -H "Authorization: Bearer $CYBERDESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "workflow-uuid",
    "main_agent_model_id": "model-configuration-uuid",
    "input_values": {
      "account_id": "acct_123"
    }
  }'

const { data: run } = await client.runs.create({
  workflow_id: "workflow-uuid",
  main_agent_model_id: "model-configuration-uuid",
  input_values: {
    account_id: "acct_123",
  },
});

from cyberdesk import RunCreate

run = client.runs.create_sync(
    RunCreate(
        workflow_id=workflow_id,
        main_agent_model_id=model_configuration_id,
        input_values={"account_id": "acct_123"},
    )
)

This applies only to the run you create. The workflow’s saved model_metadata is not changed.

Full Metadata Shape

You can also send model_metadata directly. This is useful if you want to override more model roles later while keeping the same payload shape as workflow-level model metadata:

{
  "workflow_id": "workflow-uuid",
  "model_metadata": {
    "main_agent_model_id": "model-configuration-uuid"
  }
}

If both main_agent_model_id and model_metadata.main_agent_model_id are present, they must match.

Fallback Behavior

Per-run model metadata is merged on top of the workflow’s model metadata:

provided run-level fields win
omitted run-level fields fall back to the workflow
if no run-level model override is provided, behavior is unchanged

For example, if the workflow has cache detection and fallback models configured, and the run only provides main_agent_model_id, the run uses:

run-level main_agent_model_id
workflow-level cache detection model
workflow-level fallback models

Validation

Cyberdesk validates model override IDs when the run is created. The request fails with 400 if the model configuration:

does not exist
is not accessible to your organization
conflicts between main_agent_model_id and model_metadata.main_agent_model_id

When to Use This

Use per-run model overrides when:

your runner UI lets users pick a model at trigger time
different workflow steps or jobs should use different main agent models
you batch many concurrent runs of one workflow
the workflow should remain a stable template instead of mutable runtime state

Do not use this when the workflow itself should remain the single source of truth for model selection. In that case, update the workflow’s model configuration and create runs without main_agent_model_id.

Getting started

SDK Guides

Cyberdriver

Workflow Prompting

Webhooks

Concepts

Additional Details

Why this exists

1. List Available Models

2. Create a Run With a Model Override

Full Metadata Shape

Fallback Behavior

Validation

When to Use This

​Why this exists

​1. List Available Models

​2. Create a Run With a Model Override

​Full Metadata Shape

​Fallback Behavior

​Validation

​When to Use This

​Related

Why this exists

1. List Available Models

2. Create a Run With a Model Override

Full Metadata Shape

Fallback Behavior

Validation

When to Use This

Related