samples/openhands_1 — awesome-ai-stack

Example

OpenHands — an autonomous coding agent (local workspace)

A real, runnable mini-project. Download it and run with Docker.

View samples/openhands_1 on GitHub ↗

June 28, 2026

OpenHands — an autonomous coding agent (local workspace)

A headless OpenHands run on the OpenHands Agent SDK: it gives the agent terminal + file-editor tools and a task, then runs the read–edit–run loop until done. It uses the SDK's local workspace, so the agent acts inside this container — no nested Docker sandbox — and the whole thing is a single docker run.

Heavy image. OpenHands pulls a large dependency set (playwright, jupyter, …), so the image is several GB and the first build is slow.

Configure

cd samples/openhands_1
cp .env.sample .env
# edit .env: set LLM_MODEL and LLM_API_KEY

LLM_MODEL is a LiteLLM-style name, so any provider works:

Provider	`LLM_MODEL`	`LLM_API_KEY`
Anthropic Claude	`anthropic/claude-opus-4-8`	your Anthropic key
OpenAI	`openai/gpt-4o`	your OpenAI key

.env is gitignored — only .env.sample is committed.

Run with Docker

cd samples/openhands_1
docker build -t aas-openhands .
docker run --rm --env-file .env aas-openhands \
  "Create result.txt with the result of 2 + 2, then read it back."

Run with Docker (in a devcontainer with DooD)

In a dev container that talks to the host Docker daemon (Docker-outside-of-Docker), the foreground docker run above often prints nothing and exits 0 — but the run itself succeeds. The agent runs to completion and Docker captures all of its output; only the live attached stream drops it over the VM boundary. You can confirm this: docker logs on the same container shows the full output, the container exits 0, and it is not an OOM. Run detached and follow the logs instead:

cd samples/openhands_1
docker build -t aas-openhands .
docker logs -f "$(docker run -d --env-file .env aas-openhands \
  "Create result.txt with the result of 2 + 2, then read it back.")"

(This sample uses the SDK's local workspace, so it does not spawn a second container — unlike OpenHands' default Docker runtime.)

Run locally

cd samples/openhands_1
pip install -r requirements.txt
python app.py "Create result.txt with the result of 2 + 2, then read it back."

Notes

reasoning_effort=None in app.py: claude-opus-4-8 uses a newer thinking API than this OpenHands/LiteLLM build sends, so extended thinking is disabled to stay compatible. Other models (e.g. openai/gpt-4o) work unchanged.

Example run

Output varies by model and run — LLMs are non-deterministic, so the exact wording (and the agent's steps) differ each time. Below is one run with anthropic/claude-opus-4-8.

Message from User ──────────────────────────────────────────────
Create result.txt with the result of 2 + 2, then read it back.

Agent Action ───────────────────────────────────────────────────
$ echo $((2 + 2)) > /workspace/result.txt && cat /workspace/result.txt

Observation ─────────────────────────────────────────────────────
Tool: terminal
Result:
4
✅ Exit code: 0

Message from Agent ──────────────────────────────────────────────
I created `/workspace/result.txt` containing the result of 2 + 2, then read it
back. The value is **4**.

.env.sample

# Copy this file to `.env` and add your key.
#   cp .env.sample .env
#
# OpenHands routes the model through LiteLLM via LLM_MODEL.

# LiteLLM-style model name. Examples:
#   anthropic/claude-opus-4-8    Anthropic Claude   -> LLM_API_KEY = your Anthropic key
#   openai/gpt-4o                OpenAI             -> LLM_API_KEY = your OpenAI key
LLM_MODEL=anthropic/claude-opus-4-8

# API key for the provider named in LLM_MODEL.
LLM_API_KEY=

app.py

"""OpenHands: an autonomous coding agent on the OpenHands Agent SDK.

OpenHands runs a real read–edit–run loop. This sample uses the SDK's *local*
workspace, so the agent runs its terminal + file-edit tools in this container —
no nested Docker sandbox — which keeps it to a single headless run.

The model is routed through LiteLLM via LLM_MODEL, so the same code works with
Anthropic Claude, OpenAI, or any LiteLLM-supported provider.

Run:
    docker build -t aas-openhands .
    docker run --rm --env-file .env aas-openhands \
        "Create result.txt with the result of 2 + 2, then read it back."
"""

import os
import sys

from openhands.sdk import LLM, Conversation
from openhands.tools.preset.default import get_default_agent
from pydantic import SecretStr

DEFAULT_TASK = (
    "Create result.txt containing the result of 2 + 2, then read it back "
    "and tell me the value."
)


def main() -> None:
    task = " ".join(sys.argv[1:]) or DEFAULT_TASK

    llm = LLM(
        usage_id="agent",
        model=os.environ.get("LLM_MODEL", "anthropic/claude-opus-4-8"),
        api_key=SecretStr(os.environ.get("LLM_API_KEY", "")),
        # claude-opus-4-8 uses a newer thinking API than this OpenHands/LiteLLM
        # build emits, so disable extended thinking to stay compatible.
        reasoning_effort=None,
    )

    # cli_mode=True keeps the terminal + file-editor tools and drops the browser.
    agent = get_default_agent(llm=llm, cli_mode=True)

    # A local workspace runs actions in this container — no nested Docker sandbox.
    workspace = os.environ.get("WORKSPACE", "/workspace")
    conversation = Conversation(agent=agent, workspace=workspace)
    conversation.send_message(task)
    conversation.run()


if __name__ == "__main__":
    main()

Dockerfile

# Image for the OpenHands sample. OpenHands pulls a large dependency set
# (playwright, jupyter, …), so this image is several GB — expect a slow first build.
FROM python:3.12-slim

# Stream stdout/stderr unbuffered so the agent's steps appear live.
ENV PYTHONUNBUFFERED=1

# Hide the SDK's import-time startup banner so the agent's output stays clean.
ENV OPENHANDS_SUPPRESS_BANNER=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app.py .

# The agent works here — a local workspace, not a nested Docker sandbox.
RUN mkdir -p /workspace
ENV WORKSPACE=/workspace

# Provide your config at run time (.env is NOT baked into the image):
#   docker run --rm --env-file .env aas-openhands "<task>"
ENTRYPOINT ["python", "app.py"]