# OpenHands

<img
  src="/brand/banner-b-02.webp"
  alt=""
  loading="lazy"
  width="1280"
  height="549"
  className="brand-band"
/>

[OpenHands](https://docs.openhands.dev) (formerly OpenDevin) is a self-hosted
agent runtime that runs an agent in a sandboxed container and lets it edit
code, run commands and browse. It accepts any OpenAI-compatible endpoint.

*Setup guide: this config comes from OpenHands's official documentation and
has not been run end to end against the gateway. Corrections to [support@hyphen-solution.com](mailto:support@hyphen-solution.com).*

## The easy mistake

OpenHands routes through LiteLLM, so the model name needs an `openai/` prefix
telling the router this is a generic OpenAI-shaped endpoint.

```
openai/minimax-m3     correct
minimax-m3            fails with "LLM Provider NOT provided"
```

The prefix is stripped before the request. Hyphen receives `minimax-m3`.

## 1. Get a key

[app.hyphen-solution.com](https://app.hyphen-solution.com) → sign in → pick a
plan or credit pack → **Dashboard → API Keys**. Copy the `sk-...` key.

## 2. Start OpenHands

```bash
docker run -it --rm --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
    -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
    -e LOG_ALL_EVENTS=true \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/.openhands \
    -p 3000:3000 \
    --add-host host.docker.internal:host-gateway \
    --name openhands-app \
    docker.openhands.dev/openhands/openhands:1.8
```

Check the [installation docs](https://docs.openhands.dev) for the current image
tags before pasting. They move fast.

## 3. Configure the model in the UI

Open `http://localhost:3000`, then **Settings → LLM tab → "see advanced
settings"** and turn on the **Advanced** toggle. That reveals three free-text
fields:

- **Custom Model:** `openai/minimax-m3`
- **Base URL:** `https://api.hyphen-solution.com/v1`
- **API Key:** `sk-YOUR_KEY`

Save. This is the supported path for Docker deployments.

## 4. Verify

Start a new conversation and ask:

```
Reply with the single word: connected
```

If OpenHands answers, the runtime is wired up. Then give it a real task and
watch it work in the sandbox.

## The CLI

The CLI reads environment variables, but `LLM_MODEL` and `LLM_BASE_URL` only
take effect with an explicit flag:

```bash
export LLM_MODEL="openai/minimax-m3"
export LLM_BASE_URL="https://api.hyphen-solution.com/v1"
export LLM_API_KEY="sk-YOUR_KEY"

openhands --override-with-envs
```

Leave `--override-with-envs` off and OpenHands uses its stored settings
instead, silently ignoring your variables.

## `config.toml`

```toml
[llm]
model = "openai/minimax-m3"
base_url = "https://api.hyphen-solution.com/v1"
api_key = "sk-YOUR_KEY"
temperature = 0.0
```

:::warning[Development mode only]
OpenHands' own docs state that custom LLM configurations in `config.toml` apply
only when running from source via `main.py` or `cli.py`. Running through
`docker run` ignores this file. Use the UI fields or the CLI env vars above.
:::

## Which model

Use `openai/minimax-m3`. OpenHands runs long multi-step tasks with heavy tool
use, which is exactly what the flagship is for. `minimax-m2.5` works for cheap
experiments; the flagship is the one built for long runs.

## Troubleshooting

- **"LLM Provider NOT provided"**. The `openai/` prefix is missing. This is
  the easiest mistake to make, and it shows up in headless mode too.
- **404**. Base URL is missing `/v1`.
- **`401`**. Wrong key.
- **CLI ignores your env vars**. You forgot `--override-with-envs`.
- **Agent stalls or returns nothing**. The M-series reason before acting and
  need output headroom. See
  [Choosing a model](/choosing-a-model#the-max_tokens-gotcha).
- **`429`**. Monthly budget spent. OpenHands runs long, so this is a real
  risk on a small plan. See [Rate limits & caps](/rate-limits).
- **Settings moved?** Check
  [OpenHands' custom endpoint walkthrough](https://docs.openhands.dev/openhands/usage/llms/local-llms),
  which is written for local models but is the same three fields.

## Related

- [Choosing a model](/choosing-a-model): which model for which job.
- [Handling the 429 cap](/recipes/handling-429): long agent runs and budgets.