OpenHands Architecture and Runtime
1. The workspace shape​
The repo layout makes OpenHands look like a real platform, not a tiny wrapper:
| Area | Why it matters |
|---|---|
openhands/ | Main runtime and platform logic |
frontend/ | User-facing application surface |
containers/ | Execution and packaging support |
config.template.toml | Operator-facing runtime setup |
tests/ | Validation of agent behavior and platform pieces |
The important architectural point is that the agent logic and the execution environment are treated as separate concerns.
2. The runtime mental model​
At runtime, OpenHands usually follows this shape:
- the user gives a software task,
- the agent inspects the repository,
- it runs commands or tests inside a controlled environment,
- it edits files,
- it iterates until the task or stop condition is reached.
That makes it closer to a practical software worker than to a plain code-completion tool.
3. Why the sandbox matters so much​
Because OpenHands is meant to run commands and change code, the sandbox is not an accessory. It is part of the runtime contract itself.
If you ignore the sandbox model, you are not really understanding OpenHands.
4. UI and automation surfaces​
The frontend and automation-related docs show that OpenHands is not only a local hacker tool. It is trying to support broader operational workflows where sessions can be inspected, repeated, and managed more deliberately.
5. What to read first in code​
Start with:
- the intro and setup docs,
openhands/,- execution container and config files,
frontend/,- tests after the main agent loop is clear.