OpenHands — connecting your own model through an API gateway

OpenHands is an open-source agent that differs from its terminal siblings in one important way: it runs commands inside an isolated container rather than directly on your system. For working with unfamiliar code or running autonomous tasks, that is noticeably calmer.

The model underneath isn't fixed: any compatible API will do.

Provider setup

OpenHands reaches models through LiteLLM, so three things matter: base address, key, and a model name with a provider prefix. For a gateway the simplest route is the OpenAI-compatible one: an openai/ prefix before the model name and an address with /v1.

Through environment variables:

export LLM_MODEL=openai/gpt-5.6-sol
export LLM_BASE_URL=https://api.zukko.pro/v1
export LLM_API_KEY=fetch_your_key

Or in the interface: Settings → LLM tab → enable Advanced options and set Custom Model to openai/gpt-5.6-sol, Base URL to https://api.zukko.pro/v1, and the API Key — then no variables are needed.

The same address also reaches Claude — for example, openai/claude-opus-5-5: the gateway translates the request into the right format.

Mind the /v1 in the address and the openai/ prefix in the model name: without /v1 requests miss and get a 404, and without the prefix LiteLLM won't know which protocol to speak. These are the most common connection mistakes.

A fetch_... key comes from your Zukko↗ dashboard and works in both formats.

Choosing a model

What's available right now:

curl https://api.zukko.pro/v1/models -H "Authorization: Bearer fetch_your_key"

Models failing a check at that moment are dropped from the list — specifically for agents, so you don't pick a broken one at random.

For OpenHands it matters that the model calls tools confidently: the agent works in long chains, and a model that fumbles calls will burn budget on retries. The main option is claude-opus-5-5 or gpt-5.6-sol ($0.30/$0.30 per million); glm-5.3 is much cheaper ($0.10/$0.10, 128K context) and may suit simpler work — test on your own tasks.

The sandbox and your bill

Isolation buys safety, with a side effect on cost: an agent in a container re-explores its environment more often — installing dependencies, inspecting structure, checking versions. Every such action enters the context and is paid for on every subsequent step.

Two ways to contain it. First, be specific: not "figure out this project" but "in app/models.py, fix the type of the days field". Second, don't stretch one session across several different tasks — finish, then start fresh.

If it doesn't work

401. The key didn't get through or was truncated. Check for a trailing space.

404. No /v1 in the Base URL, or no openai/ prefix on the model name.

The agent suggests writing code by hand. Tool calls aren't arriving; a single request settles it.

A long silence on the first step. Some models spend tokens on internal reasoning first; with a small output limit they never reach the text. Raise it to a few thousand tokens.