Skip to main content
Agent Canvas supports configuring your LLM provider, model, and credentials from the UI. It also supports saved LLM profiles, which make it easier to switch models without re-entering provider settings each time.

​
Configure an LLM Profile

Open Settings > LLM to add a reusable LLM profile. Use the Basic tab for a provider and model available in the dropdowns. Use the Advanced tab when you need to enter a model name and base URL directly. Use the All tab to view and customize the full set of model configuration fields.
ACP agents such as Claude Code, Codex, and Gemini CLI manage their own model access. See ACP Agents instead.

​
Choose a Configuration Path

​
Direct Provider

In the Basic tab, select your provider and model, add the API key issued by that provider, and save the profile. Use a new conversation to test the change; an existing conversation continues with the agent and model it started with. For provider and model recommendations, see LLM Configuration.

​
OpenHands Provider

Use an OpenHands LLM API key when you want Agent Canvas to access models through the OpenHands provider:
  1. Copy your LLM API key from OpenHands Cloud.
  2. In the Basic tab, select OpenHands, choose a model, and add the key.
  3. Save the profile and start a new conversation.
For key details and available models, see OpenHands LLM Provider.

​
Local OpenAI-Compatible Endpoint

A local server can be LM Studio, Ollama, vLLM, SGLang, or another service that exposes an OpenAI-compatible API. In the Advanced tab, enter the provider, exact model ID, endpoint base URL, and the required API key or a placeholder value when the server does not require one. The URL must be reachable from the backend, not only from your browser. For example, a backend in Docker cannot use 127.0.0.1 to reach a model server running on the host. Use the host address appropriate for that backend and confirm the endpoint’s model inventory before saving. For example, if the model server runs on the host at port 1234 and the Agent Canvas backend runs in Docker, configure:
  • Model: openai/<served-model-id>, replacing <served-model-id> with the exact id returned by the server’s GET /v1/models endpoint
  • Base URL: http://host.docker.internal:1234/v1
  • API key: local-llm or another placeholder value when the server does not require authentication
See Local LLMs for LM Studio, Ollama, and other local-server examples.

​
LiteLLM Proxy

In the Advanced tab, use the model name format litellm_proxy/<model-name>, then enter your LiteLLM proxy base URL and API key. The model name after the prefix must match a model configured on the proxy. See LiteLLM Proxy for the complete configuration.

​
Working with LLM Profiles

LLM profiles are useful when you want different model setups for different tasks, such as:
  • a fast profile for iteration
  • a stronger profile for planning or review
  • a local model profile for offline experiments
LLM profiles are separate from Agent Profiles. Agent Profiles choose which agent runs a new conversation. OpenHands Agent Profiles reference an LLM profile to decide which model configuration that agent uses.

​
Manage Saved Profiles

The available profiles list shows each profile’s name, configured model, and whether it is active. Use a profile’s menu to edit or rename it, set it as the active profile for new conversations, or delete it when you no longer need it.

​
Switching Profiles in a Conversation

You can switch profiles from the profile selector in the chat input or with the /model command:
  • /model — list the saved profiles available to the conversation
  • /model <profile-name> — switch to a specific saved profile
A switch preserves the conversation history, workspace, and task state; it applies to future model requests only. Agent Canvas also shows model-switch events in the conversation timeline so you can see when a profile changed during a task.
Model switching requires saved LLM profiles. If /model is not available in the chat input, create a profile in Settings > LLM and confirm that the active backend supports profile switching.

​
Fix a Failed Configuration

For error-specific steps, see Troubleshooting.
  1. Configure and save a default profile in Settings > LLM.
  2. Create additional profiles for specific tasks or cost levels, using descriptive names that make their purpose clear.
  3. Open Settings > Agent and choose which LLM profile an OpenHands Agent Profile should use.
  4. Start a new conversation and send a simple message to confirm the selected model responds.
  5. Use the profile selector or /model when you want to switch profiles without leaving the chat.