OpenHands + JoinGonka Gateway: agent on your own endpoint

The project currently has several interfaces, and where you look for model settings depends on which one you are running. The values themselves are the same everywhere; only the path to them differs.

Agent Canvas requires Node.js and uv — the agent's local server runs on it (details in the setup guide). The guide mentions Node.js 22.12 or newer, but the package itself starting from version 1.17 requires Node.js 24 or newer — install 24 to avoid an incompatible version warning. There is also a container option: the ghcr.io/openhands/agent-canvas image provides the interface at http://localhost:8000/canvas and sees only the directories you have mounted.

JoinGonka Key. Register at gate.joingonka.ai/register, verify your email, and create a key with the jg- prefix in the "API Keys" section. One key and one balance work for all models in the network. The OpenHands installer @joingonka/setup does not list this in its tools, and that is not an oversight: its settings live in the interface and the secure backend storage, not in a text config file that can be edited externally.

Step 1. Launch Agent Canvas and open Settings > LLM. The first-run wizard suggests the native OpenHands provider — you can skip this step, as you can easily return to the settings later.

Step 2. Click Add LLM Profile and go to the Advanced tab: the Basic tab only offers providers and models from the built-in list.

Step 3. Fill in three fields:

Step 4. Save the profile. Before saving, Canvas verifies the configuration with a backend request: if the key is rejected or the model is unavailable, the profile will not be saved, and you will see an error message.

Step 5. Start a new conversation and send a short message. Conversations already open will continue using the model they were started with.

Why openai/. LiteLLM determines the provider by the model prefix. The openai/ prefix does not mean "OpenAI model," but rather "communicate with the server via the OpenAI Chat Completions protocol." Only the first segment is stripped, so the gateway receives the actual identifier — deepseek-ai/DeepSeek-V4-Flash-0731. OpenHands documentation shows the same scheme using openai/qwen/qwen3.6-35b-a3b as an example. Without the prefix, LiteLLM will refuse to work, returning an LLM Provider NOT provided message.

Why /v1 and nothing more. LiteLLM accesses the server via the official OpenAI client, which automatically appends /chat/completions. Therefore, the address must end with /v1: without the suffix, the request will miss the API; with an extra tail, it will hit a non-existent path. Another Canvas requirement: the address must be accessible from the backend, not just from the browser. The gateway is a public HTTPS address; it is visible from the Docker container just as it is from the host. Techniques like host.docker.internal are only needed for models running on your own machine.

Profiles for all three models. Create a profile for each network model and give them short names — for example deepseek, glm, and minimax (the documentation mentions a limit of ten profiles). You can switch between them directly in the conversation without losing context: by using the profile selection button in the input field or the /model glm command; /model without arguments will display the list. To avoid inserting the key into every profile, you can save it once in the Provider Connections block — it is available on the local backend.

Legacy interface in Docker. The fields are the same: Settings → LLM tab → enable Advanced → Custom Model, Base URL, API Key → Save Changes.

The CLI installs with a single command via uv and on first launch walks you through model setup itself; you can return to it later with Ctrl+P → Settings:

uv tool install openhands --python 3.12
openhands

For scripts, environment variables are more convenient. An important detail: by default the CLI ignores them and applies them only with the --override-with-envs flag — for a single run, saving nothing:

export LLM_MODEL="openai/deepseek-ai/DeepSeek-V4-Flash-0731"
export LLM_BASE_URL="https://gate.joingonka.ai/v1"
export LLM_API_KEY="jg-your-key"

openhands --override-with-envs

The same set works without an interface — for CI and batch tasks:

openhands --headless --override-with-envs -t "Read calc.py and tell me in one sentence whether it has a bug."

In headless mode the agent always acts with auto-approval, so run it where it's allowed to do everything: in a separate directory or container. The --json flag turns the output into a stream of JSONL events — convenient for parsing in a pipeline. That's exactly how we tested the setup on September 21, 2026 on CLI 1.16.0: the CLI header prints Agent initialized with model: openai/deepseek-ai/DeepSeek-V4-Flash-0731, then the agent reads the file and answers substantively.

Saved CLI settings live in ~/.openhands/agent_settings.json: the model there is changed by editing three fields of the llm block — model, api_key, and base_url. Don't create the file from scratch: the first-launch wizard also writes the agent's other settings there, including history compression, without which a long conversation will hit the context window.

If you're embedding the agent into your own code, the OpenHands SDK takes the same three values:

from pydantic import SecretStr
from openhands.sdk import LLM

llm = LLM(
    model="openai/deepseek-ai/DeepSeek-V4-Flash-0731",
    base_url="https://gate.joingonka.ai/v1",
    api_key=SecretStr("jg-your-key"),
)

All models in the network have the same price, so the choice comes down to behavior. Two numbers are critical for an autonomous agent. Context window: every step re-sends the history, and the larger the window, the longer the agent can work without data loss. Response ceiling: the step where an agent writes a large file in full must fit within a single response. The table below shows the results of our test running the same task (reading a file and finding an error) via OpenHands CLI 1.16.0 with SDK 1.21.0.

The recommended workflow for long-running tasks follows the OpenHands documentation advice: plan with one model, execute with another. Start the conversation on the glm profile and request a plan without file modifications; then send /model deepseek and give the execution command. History, files, and task state are preserved when switching. Keep the minimax profile as a third option: it is convenient to switch to it when the other two run out of capacity during peak hours, and you can also assign it to generate conversation headers in Settings > Application.

History compression. Even a window of hundreds of thousands of tokens is finite during multi-hour tasks. In OpenHands, this is handled by a condenser: it collapses old events into a brief summary, which, according to the documentation, reduces latency and token consumption in long conversations. In Agent Canvas, it is configured in the Settings > Condenser section; in our CLI run, it enabled itself automatically with a threshold of 80 events.

Model limits. OpenHands retrieves the context window and response ceiling from the LiteLLM directory, which does not contain Gonka network identifiers (we checked on LiteLLM 1.81), so the agent does not have its own pre-set values for these models. This does not interfere with operation: the gateway applies the response ceiling itself, according to the table above. If you want to set limits explicitly, these are the max_input_tokens and max_output_tokens fields in the SDK, and in Canvas, the All tab opens the full set of profile fields. Details about the default model are available in the DeepSeek V4 Flash overview.

You can verify that requests are actually going through the gateway from two sides. From the OpenHands side: start a new conversation and give a short task, like "read the README and summarize in one sentence": the agent must call a tool and respond. From the gateway side: go to your dashboard, "Usage" section: the request will appear in the "By model" breakdown, and the last request time will update in the "By keys" section. If it's empty, the conversation is taking place on another profile: check which one is marked as active.

According to OpenHands documentation, the number of retries and pauses between them during 429 errors are configured via LLM_NUM_RETRIES, LLM_RETRY_MIN_WAIT, and LLM_RETRY_MAX_WAIT variables. Default values in documentation and SDK differ, so rely on the actual ones: in the CLI 1.16.0 conversation state, we observed 5 attempts with pauses ranging from 8 to 64 seconds.

Via JoinGonka Gateway, tokens cost $0.0069 per million for input and $0.021 per million for output — the price is identical for all network models and is pulled onto this page from a live source.

Estimates in the right column are based on September 2026 prices; how agent economics works is explained in detail in the article about the cheapest API for AI agents.

Spending cap. OpenHands advises setting spending limits — the gateway has this built into the payment model: the balance is prepaid, and the agent will not spend more than what is on the account. Remaining balance and daily consumption are visible in the dashboard. For CI and background automations, create a separate key so their consumption doesn't mix with yours; sub-keys with daily limits are described in the article about Management Keys.

Trust boundary. Agent Canvas, launched via npm, runs with your user permissions and can see the entire file system. For third-party code, use the Docker version: the agent will only see the mounted directory. This is a property of OpenHands itself; it does not depend on the model provider.

Correspondence stays with you. OpenHands stores conversation history locally in ~/.openhands and sends it to the model at each step; the gateway does not store the correspondence — your prompts and code are not retained after the response.

If the task includes images — interface screenshots, diagrams — create a separate profile for it with a vision-capable model: Gonka network models are text-only. This is not a limitation for code, commands, and files.