[BREAKING][sandbox] feat: support mounted agent runtime images

[yyDing1]

Summary

• Add provider-neutral image_mounts configuration for attaching self-contained black-box agent harness runtimes to task sandboxes.
• Add executable_paths to expose selected runtime binaries through /usr/bin.
• Support runtime image mounts in Docker, Modal, and OpenYuanRong.
• Keep existing OpenYuanRong provider-specific mounts compatible.
• Update Claude Code and mini-swe-agent examples to use the shared mount interface.
• Add a configurable sandbox smoke-test script.

Provider behavior

• Docker
  • Prepares task and mounted images with the same pull policy.
  • Uses Docker type=image mounts.
  • Uses runtime_timeout with a fixed sleep entrypoint.
• Modal
  • Builds registry images and mounts them with Sandbox.mount_image().
• OpenYuanRong
  • Converts shared image mounts into SDK Mount objects.
  • Merges them with existing provider-specific mounts.
• Local / veFaaS
  • Reject unsupported image-mount configurations explicitly.

Configured executable paths are linked after sandbox startup and image mounting, allowing harness commands such as claude to be discovered normally.

Motivation

Black-box agent harnesses often require dependencies that should not be installed into task images. Runtime image mounts keep harness environments isolated, reusable, and independent from benchmark task environments.

Breaking changes

• DockerSandbox no longer accepts configurable entrypoint or command.
• Docker sandbox lifetime is now controlled by runtime_timeout.
• Local provider-specific validation now happens during sandbox construction rather than generic config parsing.

Testing

• Added cross-provider image-mount tests.
• Added executable-path validation and linking tests.
• Extended Docker sandbox coverage for image preparation and mounts.
• Ran sandbox and agent unit tests.
• Ran ruff, ruff-format, mypy, and compileall checks.

Notes

Docker image mounts require a daemon backed by the containerd image store. The live smoke-test script is provided for manual provider validation and is not run in CI.

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 92.36641% with 10 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
uni_agent/sandbox/base.py	90.47%	6 Missing ⚠️
uni_agent/sandbox/docker.py	93.75%	2 Missing ⚠️
uni_agent/sandbox/local.py	90.00%	1 Missing ⚠️
uni_agent/sandbox/vefaas.py	75.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!