OpenHands + Ollama in 2026: Local AI Agent Profiles, MCP Scopes & Troubleshooting

If you already have Ollama running locally and want something more capable than a chat window, OpenHands is an interesting next step: it is an agent workspace built around software-engineering tasks, with a runtime, model configuration, agent profiles, tools, MCP integrations and a Canvas-style workflow. The current project is moving quickly. OpenHands 1.24.0 was released on September 25, 2026, after a sequence of releases that added local Agent Canvas work, agent-profile controls and more granular MCP configuration.

This guide focuses on a practical gap in GyanAangan's Local AI coverage: how to approach OpenHands as a local-model agent without giving every agent profile every tool or assuming that a model that chats well will automatically work well as an autonomous coding agent. The goal is not to claim that Ollama plus OpenHands is universally reliable. Instead, it gives you a reproducible setup and a way to isolate model, runtime, MCP and permission problems.

Why OpenHands is worth testing in a local AI stack

OpenHands sits at a different layer from Ollama. Ollama is primarily a model runtime and API server; OpenHands is an agent environment that can plan work, interact with a workspace, use tools and maintain a task-oriented conversation.

This separation is important. If an Ollama request works with curl but OpenHands cannot complete an agent task, the model endpoint is only one part of the investigation.

What changed recently

The current OpenHands release stream provides a useful reason to revisit local-agent setups. OpenHands 1.17.0, released September 9, 2026, added local Agent Canvas Planner support. OpenHands 1.19.0 added the ability to scope an agent profile to specific MCP servers. OpenHands 1.20.0 added selecting secrets available to an agent profile and selecting saved agent profiles for automations. OpenHands 1.21.0 improved local/Docker runtime behavior, while 1.22.0 added testing of remote MCP servers on cloud backends. The current 1.24.0 release, dated September 25, 2026, includes fixes around Canvas runtime calls and rendering of ACP tool-call content.

Those changes make agent profiles plus deliberately scoped tools a more useful topic than another generic “install OpenHands” article. They also create an important security principle: local does not mean unrestricted.

Prerequisites

• A machine capable of running your chosen local model and the OpenHands runtime.
• Ollama installed and reachable from the environment where OpenHands runs.
• A model that is appropriate for agentic coding/tool use, not merely conversational quality.
• Docker if your chosen OpenHands deployment uses a Docker-based runtime.
• A small test repository that does not contain production secrets.
• Optional: an MCP server for the first controlled tool-integration test.

Start with a small repository. Do not point an unfamiliar agent at your entire home directory, a production checkout, SSH credentials, or a directory containing API keys.

Step 1: verify Ollama before involving OpenHands

First make sure the local model server works independently:

ollama --version
ollama list
ollama ps

Then make one minimal API request:

curl http://127.0.0.1:11434/api/chat \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      {"role": "user", "content": "Reply with exactly: LOCAL_OK"}
    ],
    "stream": false
  }'

Expected output is a JSON response containing the assistant message with LOCAL_OK. Replace YOUR_MODEL with a model that actually appears in ollama list.

If this fails, stop here. Fix Ollama networking, the model name or model loading first. Adding OpenHands on top will only make the error harder to locate.

Step 2: think about the Ollama URL from OpenHands' point of view

The most common mistake in containerized local-AI setups is treating 127.0.0.1 as if it always means the same machine. It does not. Inside a container, 127.0.0.1 refers to that container itself.

Do not expose Ollama to the public internet merely to make an agent work. If OpenHands needs a remote Ollama endpoint, use a private network path and authentication/network controls appropriate to your environment.

Step 3: configure the model endpoint deliberately

OpenHands exposes model and base-URL settings, and its API model includes fields such as llm_model, llm_api_key and llm_base_url. The exact UI labels can change between releases, so use the current OpenHands documentation alongside the release you have installed.

The conceptual configuration is:

Model: your Ollama model identifier
Base URL: http://OLLAMA_HOST:11434
API key: provider-appropriate value if the selected integration requires one

Do not copy a cloud-provider configuration into a local Ollama profile without checking what OpenHands expects from that provider adapter. A successful chat completion and a successful agent run are separate tests.

Model choice: chat quality is not the same as agent reliability

A local model can produce excellent answers in a chat interface and still struggle when an agent must decide when to call tools, interpret tool results, recover from an error and continue a multi-step task.

For a first OpenHands experiment, prioritize:

• Reliable instruction following.
• A context window large enough for the repository and tool results you expect to use.
• Tool/function-calling behavior supported by the selected serving path.
• A model size that leaves enough system memory or VRAM for the runtime and context.
• A model you can reproduce consistently rather than a huge model that barely fits.

Do not select a model solely because its parameter count is larger. For local agents, memory pressure can turn a theoretically capable model into a poor practical choice if requests constantly spill, reload or fail.

Context size is part of the hardware budget

Weights are not the whole memory requirement. The active context and KV cache also consume memory, and agent workflows can produce much more context than a short chat prompt.

GyanAangan's existing local-AI memory and Ollama troubleshooting guides cover these calculations in more depth; use them before assuming the agent itself is broken.

Agent profiles: why they matter for local AI

An agent profile is useful because different tasks should not necessarily have the same model, secrets or tools. OpenHands 1.19.0 specifically added the ability to scope an agent profile to selected MCP servers, and 1.20.0 added selection of secrets available to a profile.

A practical design might look like this:

This is particularly useful with local models because people sometimes equate “the model never leaves my machine” with “the agent is safe.” The model may be local while its tools can still access a network, filesystem, Git repository or credential-backed service.

Adding MCP: start with one harmless server

OpenHands supports MCP configuration, including stdio and HTTP-style server entries. Its settings API documents fields for MCP server configuration, including server names, commands, arguments, environment variables and HTTP endpoints.

For the first test, use a tool that does not have destructive privileges. Avoid starting with a shell server that can execute arbitrary commands.

The debugging sequence should be:

1. Confirm the MCP server works with its own documented client or Inspector.
2. Add it to an isolated OpenHands profile.
3. Start a simple task that requires exactly one tool.
4. Confirm the tool appears and returns a valid result.
5. Only then add another tool or secret.

If the MCP server works in Inspector but not in OpenHands, investigate the OpenHands client configuration, transport and profile scope. If it fails in Inspector too, fix the server first.

A useful local-agent test task

Do not begin by asking the agent to “build my entire application.” Use a deterministic test:

Create a file named AGENT_TEST.md.
Write three bullet points explaining what this repository contains.
Do not modify any existing source files.
Do not access files outside the workspace.

Then verify manually:

git status
git diff -- AGENT_TEST.md
cat AGENT_TEST.md

This test checks workspace access, basic tool execution, file creation and the agent's ability to follow a constrained instruction without introducing a large debugging surface.

Failure mode: chat works but the agent does nothing

This usually means you have proved model inference but not the complete agent path. Check the following in order:

1. Can OpenHands reach the configured model endpoint?
2. Is the selected model actually the model you intended?
3. Can the model produce the tool-call format expected by the selected integration?
4. Does the runtime have access to the workspace?
5. Is the agent profile allowed to use the required tool?
6. If MCP is involved, does the server appear and respond independently?
7. Is the task too large for the available context or memory?

Do not immediately increase context or switch to a much larger model. First identify which layer failed.

Failure mode: MCP works elsewhere but not in OpenHands

OpenHands has had MCP-related lifecycle and configuration work across its recent releases. A March 2026 software-agent-sdk issue documented a lifecycle problem where long-lived MCP clients could accumulate because client ownership was tied to conversations. That is a project issue report, not a statement that every current deployment has the same problem. The current release stream should therefore be checked before applying old workarounds.

There is also a July 2026 community issue describing an OpenHands local ACP automation failure involving OpenCode and Ollama. The report is useful as a diagnostic example because the normal conversation path worked while the automation path returned an ACP-server error. Again, treat community reports as evidence about possible failure modes, not universal behavior.

Security: local models still need boundaries

• Use a dedicated test repository for initial agent experiments.
• Keep secrets out of the workspace and grant only the profile that needs them.
• Prefer narrowly scoped MCP servers over a single server with broad capabilities.
• Do not expose Ollama publicly just to solve a container networking problem.
• Review filesystem and shell permissions before enabling autonomous execution.
• Keep deployment credentials separate from development credentials.
• After upgrading OpenHands, retest agent profiles and MCP access instead of assuming old permissions still behave identically.

Agent profiles and MCP scopes are therefore not just convenience features. They can form part of the boundary between a local model and the systems it is allowed to affect.

When OpenHands is not the right choice

OpenHands is not automatically better than a terminal coding agent, IDE extension or simple Ollama API client. If you only need short code explanations, a direct local chat interface is simpler. If you want a lightweight terminal pair programmer, Aider may be a better fit. If your workflow is primarily MCP-centric, a dedicated MCP client can reduce the number of moving parts.

OpenHands becomes more interesting when you specifically want a structured agent workspace, runtime isolation, longer engineering tasks, agent profiles or automation-oriented workflows.

Verification checklist after installation or upgrade

1. Run ollama --version and ollama ps.
2. Make one direct Ollama API request.
3. Confirm OpenHands can reach the same endpoint from its runtime.
4. Run the small AGENT_TEST.md task.
5. Verify the resulting Git diff.
6. Test one MCP server independently.
7. Enable that MCP server only in the intended OpenHands profile.
8. Run one task requiring the MCP tool.
9. Check that unrelated profiles do not receive the tool or secret.

FAQ

Can OpenHands use Ollama locally?

OpenHands supports configurable LLM endpoints, and its settings model includes an LLM model and base URL. Whether a particular local model behaves well as an agent depends on the model, provider adapter, tool-calling behavior, context and runtime configuration.

Should I use a huge local model for OpenHands?

Not automatically. A model that leaves insufficient memory for context, the runtime or other services can be less practical than a smaller model. Start with a model that comfortably fits and then test the actual agent workflow.

Does local inference mean my data stays completely private?

Not necessarily. The model request can stay local while an MCP server, web-search tool, Git integration, package manager or other tool sends data elsewhere. Inspect the complete tool chain, not only the model endpoint.

Why use agent profiles?

Profiles let you separate task-specific configuration and, in current OpenHands releases, can be used with more granular MCP and secret access. That makes it easier to give an agent only the capabilities needed for a particular job.

Should I enable MCP immediately?

No. First prove the model endpoint and basic workspace operation. Then add one MCP server and verify it independently. This creates a much smaller debugging surface.

Official sources

• OpenHands release history
• OpenHands GitHub repository
• OpenHands documentation
• OpenHands settings API documentation
• OpenHands software-agent-sdk issues

Related GyanAangan guides

• Goose + Ollama Local AI Agent Setup in 2026
• How to Run Cline with Ollama or LM Studio in 2026
• MCP Inspector 2.8.0: Debug Local AI MCP Servers
• Ollama Out of Memory in 2026
• How to Secure a Remote Ollama Server in 2026