chore: import upstream snapshot with attribution

2026-07-13 12:30:44 +08:00
commit bcbd1bdb22
5748 changed files with 562488 additions and 0 deletions
@@ -0,0 +1,56 @@
+---
+title: OpenHands
+description: Run the All-Hands OpenHands SDK against a Mirage workspace using MirageWorkspace and the Mirage terminal tool.
+icon: /images/openhands-logo.svg
+---
+
+[OpenHands](https://github.com/All-Hands-AI/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
+
+```bash
+uv add 'mirage-ai[openhands]'
+```
+
+This pulls in `openhands-sdk>=1.18.0` and `openhands-tools>=1.18.0`. The OpenHands SDK requires Python >= 3.12, on 3.11 this extra installs nothing.
+
+## Usage
+
+```python
+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.resource.ram import RAMResource
+
+ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
+
+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=ws.file_prompt,
+    )
+    conversation = Conversation(agent=agent, workspace=mirage_ws)
+    conversation.send_message("Create /hello.txt with 'hi' and ls /.")
+    conversation.run()
+```
+
+## Exports
+
+| Symbol | Purpose |
+| --- | --- |
+| `MirageWorkspace` | OpenHands `Workspace` implementation backed by a Mirage workspace. |
+| `MirageTerminalExecutor` | Terminal executor that pipes through `Workspace.execute()`. |
+| `register_mirage_terminal` | Registers the Mirage terminal tool so the agent can `Tool(name=...)` it. |
+
+## Examples
+
+- [`examples/python/agents/openhands/sandbox_agent.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/openhands/sandbox_agent.py), RAM + S3 + Slack composed into one workspace.