Skip to main content
The apple_container machine provider reaches a running container under Apple’s container tool, and runs the programs it captures in it. You start the containers; Mirage only runs programs in them. Needs Apple silicon and macOS 26 or later. Python SDK and Node.

Installation

Install and start Apple’s container. From the Mirage repository root, build the machine image, which carries Mirage and fuse3, and start a container from it:
--init gives the container a process that collects what ends; without it a program that is killed stays behind as a zombie.

Usage

captures defaults to @external: every program Mirage does not have itself. Name @python to run Python in the container too. For one container per agent, make each container a machine of its own and send each session to its machine with a route.

Connecting the workspace

Pick a mount_type. The default image lacks sshfs for ssh; add it with apt-get update && apt-get install sshfs, or mirage-fuse for mirage. With own, copy sandbox.yaml in and start Mirage in the container:

Notes

  • Set container to the name of a running container.
  • The image needs a POSIX-compatible /bin/sh. The session’s environment wins over the image’s. The working directory must already exist in the container.
  • Host directories reach the container only through --volume. A service on your Mac is not at 127.0.0.1 inside; Apple’s host integration guide sets up host.container.internal.
  • Each container is its own VM, so agents with one each share no files, processes, CPU or memory. Give each one that agent’s rules: the default profile in its sandbox.yaml.
  • A timeout does not kill the program: container 1.4.1 does not deliver signals into the guest (apple/container#1941).