Migrating Codebases with Sandboxed Agents

Large-scale migrations of legacy codebases become hard to review and carry greater merge risk when handled as a single bundle. That's why the work needs to be split into repo shard units, with an agent in an independent sandbox for each shard reading files, modifying them, running tests, and returning a patch.

The core structure is the separation between the host-side harness and the execution environment. The harness manages the Agents SDK, along with policies, credentials, MCP servers, and audit logs, while the sandbox is handed only the files and commands needed for the current task. This keeps orchestration on the trusted host while code execution and file editing are handled in an isolated environment.

The example shows two service repositories loaded into separate sandboxes, each performing the work of moving an OpenAI client wrapper from Chat Completions to the Responses API. In each sandbox, the agent first runs the tests to confirm a baseline, then modifies the code, runs the tests and a compileall check again, and finally returns a typed migration report along with the patch.

The components are as follows.

• A Manifest stages only the necessary files under /workspace.
• The sandbox capability exposes only Shell() and ApplyPatch(), limiting the scope of work.
• Provider-specific differences are kept only in the sandbox creation code, so the same harness and agent can easily be swapped across different providers such as Docker, E2B, and Cloudflare.

Before execution, the same tests are run on the host first to confirm the baseline. Afterward, each task follows MIGRATION.md, and the host receives the task results, logs them for audit, deletes the sandbox, and moves on to the next shard. This pattern presents a way to run large-scale code modernization in smaller units, more safely and repeatably.