Skip to main content
The OpenAI Agents SDK gives an agent a local ShellTool and ApplyPatchTool, and a SandboxAgent that works inside a sandbox session. Mirage backs each of them with a Workspace, so every command, patch and file read the agent makes runs in the workspace’s mounts, not on the host.

Install

Usage

MirageShellExecutor runs ShellTool commands in the workspace, and MirageEditor applies ApplyPatchTool patches to it:

Tools

The agent keeps the SDK’s own tools, run in Mirage:
  • shell (ShellTool) runs each command as a Mirage shell line.
  • apply_patch (ApplyPatchTool) creates, updates and deletes workspace files.
  • A SandboxAgent gets exec_command, write_stdin, apply_patch and view_image from Capabilities.default().
Every call is held to the workspace’s mount modes and policy.

Sandbox agent

MirageSandboxClient makes a SandboxAgent’s sandbox session a Mirage workspace. MirageCapability adds the workspace’s mounts (backend, mode, commands) to the agent’s instructions:
  • Every command starts at the manifest root (/ unless a Manifest sets another), and a cd or export ends with its command, as in the SDK’s other sandboxes. Commands see the manifest’s environment.
  • Each sandbox session has its own Mirage session. Its commands run side by side, so one left running in the background does not hold up the next.
  • A command still running after exec_command’s yield time keeps running. The model polls it with write_stdin and stops it with Ctrl-C (\u0003). A direct exec(..., timeout=...) raises ExecTimeoutError.
  • Relative paths resolve against the manifest root, and writes create missing parent directories.
  • A run paused for tool approval resumes on the same workspace and keeps the files the agent wrote.
  • exec("ls", "-la", path, shell=False) quotes each argument. A single string with shell=False is one program name, as in the SDK’s other sandboxes.

Attachments

MirageRunner reads workspace files into the user message: images as input_image, PDFs (uploaded through the Files API) as input_file, anything else as text:

Exports

Examples