The-Biomechanist Sandbox Run
Choose the boundary from the task's required property, not from whichever backend happens to be installed first.
Routing
| Requirement | isolation_requirement |
Auto route | Boundary |
|---|---|---|---|
| Linux-native compatibility or a low-risk Linux execution surface | linux_compatibility |
WSL | Interoperable Linux environment; not hostile-code containment from the Windows host. |
| Reproduce the project's declared devcontainer environment | project_reproducibility |
Dev Container | Requires the devcontainer CLI and project devcontainer configuration. |
| Run an untrusted Windows artifact away from the host | untrusted_windows |
Windows Sandbox | Disposable Windows VM with networking and clipboard disabled; the selected workload must be staged explicitly. |
environment: auto is legal only when isolation_requirement is supplied. For untrusted_windows, also supply one or more workspace-relative payload_paths; the runtime refuses an auto-routed hostile-workload plan that would launch a sandbox without the workload inside it.
Procedure
- Establish the property the boundary must provide. Do not silently substitute Linux compatibility for hostile-Windows containment.
- Inspect relevant backend availability with
env_inspectwhen it is not already established. Treatnull/unknown availability as unresolved rather than missing. - For WSL or Dev Container work, use the active project as
workspace_folder. WSL execution enters that Windows project directory through WSL's--cdboundary and usessh -lc; a task requiring Bash-specific semantics should request Bash explicitly. - For Windows Sandbox, identify exactly which project files/directories the isolated command needs and pass them as workspace-relative
payload_paths. Every selected path component and every traversed child must remain an ordinary workspace path: symbolic links and NTFS reparse points such as junctions are rejected before traversal crosses them, and failure to establish that metadata blocks staging rather than being treated as safe. Overlapping selections are rejected, and staged input is limited to 10,000 filesystem entries and 1 GiB total file bytes. Write the inner command relative to the staged payload root (C:\WDAShare\payload). - Call
sandbox_runwithexecute: falseand inspect the selected route, payload list, and launch plan. Planning must not create the temporary bundle or launch the workload. In Codex, a trustedPermissionRequesthook may auto-allow this plan-only request; without trusted hooks, the host may prompt for the plan. - To launch, call the same reviewed tool with
execute: true. The active host decides whether that exact call proceeds; do not invent a second approval token. - For WSL and Dev Container runs, use captured return code/stdout/stderr only for what they establish. For Windows Sandbox, report only that the interactive sandbox launched; the inner command remains
unknownuntil an observation from inside the sandbox establishes its outcome. - An executed Windows Sandbox launch returns
cleanup_path. Remove the temporary bundle only after the sandbox no longer needs it. If staging or process launch fails before the Sandbox starts, the runtime removes the partial bundle itself.
Safety and scope
- Sandbox execution is
approval-requiredeven when the inner command looks harmless. - WSL interoperability is not a substitute for Windows Sandbox containment.
- Hyper-V is not an implemented
sandbox_runbackend. - Do not map arbitrary host folders writable into Windows Sandbox. Only the generated staging bundle is mapped, read-only.
- Isolation establishes a boundary, not semantic correctness. Verify the task result separately.