[Feature]: Additional documentation on OpenHands security boundaries and sandbox assumptions

Is there an existing feature request for this?

• I have searched existing issues and feature requests, and this is not a duplicate.

Problem or Use Case

While studying the OpenHands architecture, I found myself trying to better understand the project's security model and threat assumptions, particularly around the relationship between:

1. The manager/orchestration layer
2. The Docker sandbox layer
3. Host-level process execution used to coordinate containers

At the moment, I may simply be missing the relevant documentation.

Proposed Solution

A document (or section in the architecture docs) describing:

• The primary security boundary of OpenHands
• Which components are considered trusted
• Which responsibilities are delegated to Docker/container isolation
• Threat assumptions regarding subprocess execution and sandbox management
• Future hardening goals, if any

Alternatives Considered

Current approaches rely on infrastructure logging, container logs, and custom observability integrations.
While effective, they often make it difficult to reconstruct agent reasoning and execution flow in a consistent way across deployments.

Priority / Severity

Medium - Would improve experience

Estimated Scope

Small - UI tweak, config option, or minor change

Feature Area

Documentation

Technical Implementation Ideas (Optional)

Introduce optional execution audit hooks within OpenHands that allow:

Tool invocation events to be recorded
Agent decision checkpoints to be emitted
Execution chains to be reconstructed after completion
External audit systems to subscribe to execution events

Possible implementation approaches:

1. Event-based audit interface

• Standardized execution events emitted by the runtime
• Tool started
• Tool completed
• Tool failed
• Agent decision generated

2. Replay metadata export

• Structured execution traces
• Tool inputs/outputs
• Model responses
• State transitions

3. Audit provider abstraction

• Local file backend
• OpenTelemetry integration
• Third-party observability systems

Additional Context

I'm comparing governance, auditability, and security approaches across several agent frameworks and would love to better understand how the OpenHands team thinks about these architectural boundaries.

As agent frameworks mature and move into production environments, auditability and replayability may become increasingly important for debugging, governance, compliance, and operational trust.
I'm interested in hearing how the OpenHands team currently thinks about these capabilities and whether they align with the long-term roadmap.

Start by reviewing the architecture documentation and the manager/orchestration, Docker sandbox, and host-level process execution boundaries described in the issue. Document the primary security boundary, trusted components, Docker isolation responsibilities, subprocess threat assumptions, and any future hardening goals. Keep the optional audit-hook and replay ideas separate unless the project confirms they are in scope.