OpenHands

OpenHands runs a sandboxed agent inside Docker. The CodeActAgent parses text-action tags (<execute_bash>, <execute_ipython>) out of plain-text LLM output — NOT OpenAI function calls — and applies file edits through its Docker runtime. rapid-mlx is wired as an OpenAI-compatible provider through LiteLLM.

Install

$ pip install openhands
# Docker Desktop / dockerd must be running — OpenHands ships a
# sandbox-runtime container image and a docker-in-docker sock passthrough.

Config

LiteLLM env vars (rapid-mlx 0.10.3 output for rapid-mlx agents openhands):

$ export LLM_BASE_URL=http://localhost:8000/v1
$ export LLM_API_KEY=not-needed
$ export LLM_MODEL=openai/default
# The ``openai/`` prefix is a LiteLLM routing hint — without it LiteLLM
# tries to guess the provider from the alias string and fails on
# non-canonical rapid-mlx names.

Run

$ rapid-mlx serve qwen3.6-35b-4bit \
    --tool-call-parser qwen3_coder_xml --enable-auto-tool-choice
$ LLM_BASE_URL=http://localhost:8000/v1 \
  LLM_API_KEY=not-needed \
  LLM_MODEL=openai/qwen3.6-35b-4bit \
  openhands

Recommended aliases (per rapid-mlx agents openhands): qwen3.5-9b-4bit, qwen3.6-35b-4bit, qwen3.5-4b-4bit.

Docker E2E harness

The integration test tests/integrations/test_openhands.sh drives the pinned OpenHands 0.9.0 app + runtime images against a running rapid-mlx serve:

# pinned by manifest-list digest so a moved tag can't silently swap the image
OPENHANDS_IMAGE="ghcr.io/all-hands-ai/openhands:0.9.0@sha256:d4b028…"
OPENHANDS_RUNTIME_IMAGE="ghcr.io/all-hands-ai/runtime:od_v0.9.0_…"

$ docker run --rm \
    -e SANDBOX_CONTAINER_IMAGE="$OPENHANDS_RUNTIME_IMAGE" \
    -e LLM_BASE_URL="http://host.docker.internal:8000/v1" \
    -e LLM_MODEL="openai/$MODEL" \
    -e LLM_API_KEY="rapidmlx" \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v "$WORKDIR:/opt/workspace_base" \
    --add-host host.docker.internal:host-gateway \
    "$OPENHANDS_IMAGE" \
    python -m openhands.core.main \
      -i 10 -d /opt/workspace_base \
      -t "Fix the bug in add.py — this function should add, not subtract."

When the LLM is running on the same Mac as Docker Desktop, localhost inside the container refers to the container itself. The harness rewrites the URL host to host.docker.internal so the container can reach the rapid-mlx server. Any non-loopback host (remote-serve node, RFC1918 IP, DNS name) is preserved as-is.

Gotchas

• Docker daemon required. OpenHands' sandbox runtime is a docker-in-docker sock passthrough — non-Docker CI skips the harness cleanly.
• Text-action, not function calling. OpenHands parses <execute_bash> / <execute_ipython> blocks out of plain text. This is why R1-Distill (which can't emit function calls) still passes OpenHands cells — it can emit text-action tags.
• gpt-oss XFAILs. User-supplied stop=['</execute_ipython>', ...] gets applied across both analysis and final channels of the harmony parser, so the model's analysis-channel reasoning about the action triggers a premature stop. Server fix landed in PR #1051 — matrix cell will flip PASS once re-run.
• Small local models struggle with the complex action format. 7B-and-below can loop; 12B-and-up (Gemma 4, Qwen 3.5 9B, Qwen 3.6 35B-A3B) hit the AST whitelist reliably.

Empirical

The 2026-07-07 pilot ran the harness across all four Tier-1 families with the pinned image pair. Family × wall-time (single cell, cached-image path): Qwen 3.5-4B-4bit 32.14 s (2 CodeAct steps: read → edit_file_by_replace → finish), Gemma-4-31B-4bit 47.87 s, DeepSeek R1-Distill-32B-4bit 72.08 s (long analysis-channel CoT before the edit action, still one-shot), gpt-oss-20B-MXFP4-Q8 XFAIL at 615 s (harness timeout — see the gotcha above). All three passing families satisfied the AST whitelist on add.py.

See also