> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cyberdesk.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Model Configuration
> Configure which AI models power your workflow agents and actions
Model configuration determines which AI models run your workflows. You can set workflow-level defaults for the **main agent** and **cache detection**, and optionally **override the model per-action** directly in your prompts for `focused_action` and `extract_prompt` operations.
The runtime applies defaults differently depending on the action:
* `focused_action` inherits the workflow's main agent model unless you override it
* `extract_prompt` does not inherit the workflow's main agent model; without an override, it uses Cyberdesk's extraction default (currently `Gemini 3.1 Pro Preview (Medium)`)
## Workflow-Level Model Configuration
When you create or edit a workflow in the dashboard, you can select which model the main agent should use and which model should handle cache detection.
### Selecting a Model
1. Open the **Workflows** page in your dashboard
2. Click to create a new workflow or edit an existing one
3. In the workflow editor, use the **Main Model** and **Cache Detection Model** selectors
4. Choose from the available model configurations
5. Save your workflow
If you leave either selector on **System Default**, Cyberdesk resolves the current system default and saves that model on the workflow when you save it.
### Current Default Assignments
Cyberdesk currently applies these defaults automatically:
| Role | Current model |
| ----------------------------------------------- | ------------------------------------------------- |
| Main agent default | `Sonnet 4.6 (Medium)` |
| `extract_prompt` default | `Gemini 3.1 Pro Preview (Medium)` |
| Post-run attachment image check default | `GPT 5.6 Sol (Low)` |
| Webhook/output transformation default | `GPT 5.5 (Low)` |
| Cache detection default | `Gemini 3 Flash Preview (Minimal, Short Timeout)` |
| Cache detection fallback | `GPT 5.5` |
| Fallback 1 when the primary agent model fails | `Vertex Sonnet 4.5 (Thinking)` |
| Fallback 2 when the primary and Fallback 1 fail | `Bedrock Sonnet 4.5 (Thinking)` |
Older `Gemini 3 Pro Preview` system configurations are retired. Existing workflow references and prompt overrides that used them are migrated to the matching `Gemini 3.1 Pro Preview` configurations.
The model picker also includes other Cyberdesk system defaults and any custom model configurations owned by your organization. Current OpenAI system defaults include the `GPT 5.6` family (`Sol`, `Terra`, and `Luna` tiers) alongside `GPT 5.5`, `GPT 5.5 (Low)`, `GPT 5.5 (Medium)`, `GPT 5.5 (High)`, and `GPT 5.5 (XHigh)`. Older `GPT 5.4` configurations may appear in archived-model sections for existing workflows, but new defaults use `GPT 5.5`.
### Newly Available Model Options
Cyberdesk also includes selectable configurations for newer provider models that are available without changing the platform defaults:
* `GPT 5.6 Sol`, `GPT 5.6 Terra`, and `GPT 5.6 Luna` reasoning-effort variants (base, `Low`, `Medium`, `High`, and `XHigh`) for main workflow agents and computer-use tasks. Sol is the flagship tier for the hardest reasoning and agentic coding; Terra is the balanced everyday tier; Luna is the cost-optimized, high-volume tier for fast extraction, post-run checks, cache-style checks, and classification.
* `Sonnet 5`, `Sonnet 5 (Low)`, `Sonnet 5 (Medium)`, and `Sonnet 5 (High)` for main workflow agents and computer-use tasks.
* `Gemini 3.5 Flash (Minimal)`, `Gemini 3.5 Flash (Low)`, `Gemini 3.5 Flash (Medium)`, and `Gemini 3.5 Flash (High)` for main workflow agents, computer-use tasks, fast multimodal extraction, and cache-style checks.
* `Gemini 3.5 Flash (Minimal, Short Timeout)` for computer-use selection and cache detection paths where quickly falling back is more useful than waiting on a long primary response.
## Per-Action Model Overrides
The most powerful feature of model configuration is the ability to **specify a different model for individual actions** directly in your workflow prompts. This works for:
* **`focused_action`** — dynamic decisions and observations
* **`extract_prompt`** — vision-based data extraction from screenshots
### How to Specify a Model in Your Prompt
Use the `model="Model Name"` parameter in your prompt text:
```text theme={null}
Take a screenshot with extract_prompt="Extract all invoice data as JSON" and model="Sonnet 4.5"
```
```text theme={null}
Use focused_action with model="Sonnet 4.5 (Thinking)" to find and click on the patient
whose name is {patient_name}
```
### Using the Model Picker in the Prompt Editor
The prompt editor provides easy access to the model picker:
1. **Slash menu**: Type `/` and select "Model Override" to insert `model=""`
2. **Tab autocomplete**: Start typing `model` and press Tab to autocomplete
3. **Direct typing**: Type `model=""` and place your cursor inside the quotes
Once your cursor is inside the `model=""` quotes, a dropdown appears showing all available models. Use arrow keys to navigate, and press Enter or Tab to select. Choosing **System Default** clears the per-action override.
Hover over a model in the dropdown to see its details, including whether it supports computer use, the provider, and configuration parameters.
### Computer Use Models vs. Extraction Models
**Important**: For `focused_action`, prefer models that are marked as computer use models. The model picker indicates which models support computer use, and the editor warns if you pick a model that is not marked for computer use.
For `extract_prompt` (vision-based extraction), any configured vision-capable model can be used.
When you select a non-computer-use model, you'll see a toast warning:
> "This model isn't a known computer use model. Only use this for screenshots with extract\_prompt."
### Example: Hybrid Model Strategy
Use different models for different parts of your workflow:
```text theme={null}
Navigate to the invoice details page.
Use focused_action with model="Sonnet 4.5 (Thinking)" to verify the invoice
status shows "Approved" before proceeding.
Take a screenshot with extract_prompt="Extract all line items as JSON:
{item_name, quantity, unit_price, total}" and model="Sonnet 4.5" and process_async="batch"
Scroll down and take another screenshot with extract_prompt="Extract payment
details and due date" and model="Sonnet 4.5" and process_async="batch"
```
This strategy allows you to:
* Use a thinking model for complex decisions in `focused_action`
* Use a faster model for bulk extraction with `extract_prompt`
* Optimize for both accuracy and cost
## Automatic Fallbacks
Cyberdesk automatically handles model failures with a fallback chain:
1. **Primary model** fails (rate limit, timeout, etc.)
2. **Fallback 1** is attempted (currently `Vertex Sonnet 4.5 (Thinking)`)
3. **Fallback 2** is attempted if Fallback 1 also fails (currently `Bedrock Sonnet 4.5 (Thinking)`)
This ensures your workflows remain resilient even during provider outages.
## Custom Model Configurations
Want to use a specific model, provider, or configuration? Cyberdesk can set up organization-owned model configurations for teams that need a custom provider, model version, API key, or endpoint.
Custom model configurations are scoped to your organization. Once configured, they appear in the same workflow selectors and prompt-editor model pickers as Cyberdesk's system defaults. The dashboard currently lets you select them, but not create or edit them in a dedicated UI.
### What You Can Customize
* **Provider**: Choose from any supported provider
* **Model**: Select specific model versions
* **Temperature**: Control response randomness
* **Max tokens**: Set output length limits
* **Timeout**: Configure request timeouts
* **API keys**: Use your own provider API keys for billing and rate limits
* **Base URL**: Route to an approved custom provider endpoint when needed
For providers Cyberdesk does not supply keys for, include your own API key when creating the configuration. Cyberdesk stores the secret securely and persists only an alias.
### Custom OpenAI-Compatible Providers
If your model exposes an OpenAI-compatible API, Cyberdesk can configure it as an organization-scoped OpenAI-compatible model. This is useful for custom fine-tuned models, private gateways, or provider endpoints that use OpenAI-style chat completions.
For custom OpenAI-compatible endpoints, Cyberdesk needs:
* The provider base URL
* The model identifier
* Your provider API key
* Whether the model should be available for workflow agents, focused actions, extraction, or cache detection
Custom OpenAI-compatible base URLs require your own API key. Cyberdesk does not send Cyberdesk-provided OpenAI keys to custom endpoints.
### Need Help Setting One Up?
Contact the Cyberdesk team:
* **Email**: [founders@cyberdesk.io](mailto:founders@cyberdesk.io)
* **Discord**: [Join our community](https://discord.gg/ws5ddx5yZ8)
Include details about:
* Which provider and model you want to use
* Any custom base URL or OpenAI-compatible endpoint
* Any specific parameters (temperature, max tokens, etc.)
* Whether you'll provide your own API key
## Supported Providers
Cyberdesk uses [LangChain's `init_chat_model`](https://docs.langchain.com/oss/python/integrations/providers/overview) under the hood, and the production app currently allows a curated set of providers that match our installed integrations and runtime validation. This includes:
Claude models including Sonnet, Opus, and Haiku variants
GPT-4, GPT-5, and other OpenAI models
Access models through AWS infrastructure
Gemini models via Vertex AI or Google AI
Azure OpenAI and Azure AI services
Groq, Mistral, Cohere, Together, and others
For the broader ecosystem of providers and capabilities supported by LangChain itself, see the [LangChain integrations documentation](https://docs.langchain.com/oss/python/integrations/providers/overview). Cyberdesk's exact allowlist is narrower and is enforced by the API when you create custom model configurations.
## Best Practices
System defaults are optimized for most use cases. Only customize if you have specific requirements.
Use computer-use models for `focused_action`, and consider faster/cheaper models for bulk `extract_prompt` operations.
When switching models, test your workflows thoroughly. Different models may behave differently on the same tasks.
Track run success rates after model changes. Some models may perform better on specific workflow types.
## Quick Reference
| Use Case | Recommended Approach |
| ----------------------------------- | ------------------------------------------------------ |
| Main workflow agent | Set at workflow level in dashboard |
| Dynamic decisions during navigation | `focused_action` with computer-use model |
| Vision-based data extraction | `extract_prompt` (any vision model works) |
| Bulk extraction for output | `extract_prompt` with `process_async` and faster model |
| Cost optimization | Override with cheaper model for extraction tasks |
## FAQ
Yes. Custom model configurations can use your own provider API keys. This gives you control over billing and rate limits. Contact the Cyberdesk team to set this up. Note that this will most likely result in a change to your Cyberdesk plan.
Cyberdesk monitors provider announcements and updates system defaults accordingly. For custom configurations, we'll notify you in advance and help migrate to newer model versions.
Yes! Use the `model="Model Name"` parameter in your prompts to override the model for specific `focused_action` or `extract_prompt` operations. This is the recommended way to optimize for accuracy and cost.
`focused_action` works best with models that understand computer use—clicking, typing, and navigating. The model picker shows which models support computer use, and the editor warns if you choose a model that is not marked for it. Non-computer-use models are still fine for `extract_prompt`, which only needs vision/extraction capability.
Start with the system defaults. If you need more reasoning power for complex decisions, try a higher-reasoning model. For bulk extraction where speed matters, consider a faster vision-capable model. The model details panel in the picker shows each model's characteristics.