Apple container targets

An apple-container runtime runs each session in a separate Linux container through Apple’s container CLI. It is available only on Apple silicon with macOS 26 or newer and, like every isolated target, runs the selected harness in its unrestricted mode.

Install the runtime

Install Apple’s official signed package by following the container project installation instructions. Mjolnir does not download or install it for you.

Start the service before running setup:

container system start
container system status

On an Intel Mac or an older macOS release, use a remote SSH target or an EC2 target instead.

Configure a target

Mjolnir supplies this local target automatically on macOS and checks the runtime before allowing selection. Customize it in prefix+s Settings → Runtimes:

[targets.apple-container]
kind = "apple-container"

The target accepts the common container fields:

Key	Required	Meaning
image	no	Linux image used for every new session; defaults to the agent-dev image published for the running Mjolnir version (a development build uses :latest).
pull_policy	no	auto (default), always, newer, missing, or never.
platform	no	Explicit image platform when runtime selection needs it.
cpus	no	Backend CPU fallback when an API launch omits a per-session allocation.
memory	no	Backend memory fallback when an API launch omits a per-session allocation.
environment	no	Environment variables added inside the container.

Apple container does not accept Podman’s workspace_storage override. Each session gets an isolated workspace managed by the runtime.

The TUI new-session wizard does not use cpus and memory as its initial selection. It starts with the allocation remembered for the local container host, or the 8-CPU/32-GiB baseline when none has been remembered. The selected per-session allocation takes precedence over these target-level backend fallbacks.

Apple container takes part in the daemon’s background image download like Podman and Docker: a configured image the host does not have is downloaded a few seconds after the daemon starts, and an eligible moving tag is refreshed hourly, with container image inspect and container image pull. It also evaluates pull_policy while provisioning each session, so an eligible image refresh still happens as part of launch.

Verify it end to end

Run the static checks, then opt into the disposable smoke test:

mj doctor --json
mj doctor --json --smoke

The smoke test uses the configured target image, creates a disposable container, runs true, and removes it. If no apple-container runtime exists, doctor uses a small stock image for the runtime check. The target is ready only when the smoke result is no longer fixable.

At launch Mjolnir checks container system status, prepares the image, creates the labeled container, installs or discovers Git and the selected ACP bridge, and clones the configured bundle under /workspace. The same verified checkpoint and fresh-target resume rules as other isolated targets apply.

See Container targets for image refresh, clone cache, attachments, credentials, and recovery behavior shared by all container runtimes. See Custom images before replacing the reference agent image.