Configure a Model

Use this guide to choose a model configuration path in Agent Canvas. Start with the credentials or endpoint you have, then save the profile and test it in a new conversation.

​

Choose a Configuration Path

​

Provider Connection for Reusable API Credentials

Create a Provider Connection when you expect to use the same provider API key for more than one model or LLM profile. A connection stores the provider, API key, and optional base URL once; each linked profile supplies its own model configuration and uses the connection’s credentials.

1. Open Settings > LLM.
2. In Provider Connections, select Add provider connection.
3. Enter a recognizable name, such as Personal OpenHands API or Team OpenAI.
4. Choose the provider from the searchable provider list.
5. Enter the API key and, if needed, the provider base URL.
6. Save the connection.
7. Add or edit an LLM profile, select the connection in Provider Connection, then select the model and save the profile.

When a profile uses a Provider Connection, its API key and base URL come from the connection rather than the profile. Reuse that connection for additional models from the same provider. Update the connection once to rotate its key or change its base URL for every linked profile.

​

Direct Provider or OpenHands Profile

Use the Basic tab when you have an API key from Anthropic, OpenAI, Google, OpenHands, or another provider in the selector.

1. If you will reuse the key, create or choose a Provider Connection.
2. Select the provider and model.
3. Select the Provider Connection, or enter the API key directly for a profile-specific credential.
4. Save the profile.
5. Start a new conversation and send a short message to confirm the model responds.

For model recommendations and provider references, see LLM Configuration. For the OpenHands provider, see OpenHands LLM Provider.

​

Local OpenAI-Compatible Server

Use the Advanced tab for LM Studio, Ollama, vLLM, SGLang, or another server that exposes an OpenAI-compatible API.

1. Find the exact model ID served by your server, usually from its GET /v1/models endpoint.
2. Enter openai/<served-model-id> as the model.
3. If the server needs an API key or a reusable base URL, create a Provider Connection with those values and select it for the profile. Otherwise, enter them directly in the profile.
4. Make sure the base URL is reachable from the backend.
5. Save the profile and start a new conversation to verify it.

If Agent Canvas runs in Docker while the model server runs on the host, 127.0.0.1 points to the container, not the host. Use the host address appropriate for your platform, such as http://host.docker.internal:<port>/v1 where supported. See Run Local LLMs with OpenHands for server-specific examples.

​

LiteLLM Proxy

Use the Advanced tab when you use a LiteLLM proxy.

1. Enter litellm_proxy/<model-name> as the model.
2. Create or select a Provider Connection for the proxy URL and API key. You can instead enter those values directly when they are specific to one profile.
3. Make sure <model-name> exactly matches a model configured on the proxy.
4. Save the profile and start a new conversation to verify it.

See LiteLLM Proxy for the complete proxy configuration.

​

OpenRouter

Use OpenRouter when you have an OpenRouter API key and want to access a model through its catalog. Create an OpenRouter Provider Connection to reuse the key, then in the Basic tab select OpenRouter, choose a model, select the connection, and save the profile. Use the Advanced tab only when you need to enter a model ID that is not available in the selector. See OpenRouter for model-ID and recovery guidance.

​

Fix a Failed Configuration

For additional error-specific guidance, see Troubleshooting.

​

Next Steps

• Manage LLM Profiles
• Run Local LLMs with OpenHands
• LiteLLM Proxy
• Troubleshooting