OpenHands - Mirage

OpenHands is All-Hands’ agent SDK for autonomous software engineering. It models a Workspace and a Terminal tool, Mirage ships drop-in implementations of both so the agent operates entirely inside a Mirage workspace.

Install

uv add 'mirage-ai[openhands]'

The OpenHands SDK needs Python 3.12 or newer; on 3.11 the extra installs nothing.

Usage

import asyncio
import os

from openhands.sdk import LLM, Agent, Conversation, Tool

from mirage import MountMode, Workspace
from mirage.agents.openhands import MirageWorkspace, register_mirage_terminal
from mirage.vfs.ram import RAMVFS

ws = Workspace({"/": RAMVFS()}, mode=MountMode.WRITE)


async def main() -> None:
    llm = LLM(
        model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-6"),
        api_key=os.getenv("LLM_API_KEY"),
    )
    with MirageWorkspace(workspace=ws, working_dir="/") as mirage_ws:
        tool_name = register_mirage_terminal(mirage_ws)
        agent = Agent(
            llm=llm,
            tools=[Tool(name=tool_name)],
            system_message=await ws.vfs_md(),
        )
        conversation = Conversation(agent=agent, workspace=mirage_ws)
        conversation.send_message("Create /hello.txt with 'hi' and ls /.")
        conversation.run()


asyncio.run(main())

Exports

Symbol	Purpose
`MirageWorkspace`	OpenHands `Workspace` implementation backed by a Mirage workspace.
`MirageTerminalExecutor`	Terminal executor that pipes through `Workspace.shell()`.
`register_mirage_terminal`	Registers the Mirage terminal tool so the agent can `Tool(name=...)` it.

Examples

examples/python/agents/openhands/sandbox_agent.py, RAM + S3 + Slack composed into one workspace.