Berry Wiki

Apple Container

Properties2
tagsai, sandboxing
aliasesApple Container

9 min read

Apple Container

Checked: 2026-07-14

Project Summary

Apple Container is Apple’s command-line tool for building and running Linux containers on a Mac. Unlike Docker’s usual shared Linux VM on macOS, it starts one lightweight virtual machine (VM) for each container.

  • Host: Apple-silicon Mac
  • Supported operating system: macOS 26
  • Implementation: Swift
  • Image format: Open Container Initiative (OCI) compatible
  • Latest release: 1.1.0, released 2026-07-06
  • License: Apache-2.0
  • Primary purpose: General container build and runtime, not coding-agent sandboxing

Problem Solved

macOS cannot run Linux containers directly. Most Mac container tools place many containers inside one Linux VM, which creates a shared guest-kernel and shared-VM data boundary.

Apple Container instead creates a small VM per container. This preserves familiar OCI image workflows while giving each workload its own Linux kernel and explicit host mounts.

How It Works

  1. A signed macOS package installs the container command and helper services.
  2. container system start launches a per-user API server through launchd.
  3. Image and network helpers manage OCI content, registries, and vmnet networks.
  4. Each container gets its own runtime helper and lightweight Linux VM through Apple’s Virtualization framework.
  5. The container’s OCI image becomes the VM’s root filesystem.
  6. A small guest init and host-to-guest API start and supervise the requested process.
  7. Host folders, ports, sockets, environment values, CPU, and memory are attached only when requested.

The tool supports pulling, pushing, building, running, executing in, inspecting, copying to/from, logging, and monitoring containers. Images remain portable to other OCI runtimes.

Security Boundary

  • Compute boundary: A separate Virtualization.framework VM and Linux kernel per container.
  • Inter-container boundary: Containers on the same network still have separate VM boundaries. User-created networks are isolated from one another.
  • Host filesystem: A container receives host files only through explicit volumes, mounts, copies, or socket forwarding.
  • Resource boundary: CPU and memory limits are configurable per VM.

This is a stronger compute boundary than multiple containers sharing one Linux kernel. It does not make every launch safe:

  • Writable host mounts let container code change those host files.
  • Forwarded sockets expose the authority of their host service.
  • Normal networks allow outbound connections unless the user chooses a host-only internal network or adds controls outside the tool.
  • A Virtualization.framework or guest/host integration escape remains possible.

Apple’s documentation describes container isolation, but it does not provide a coding-agent-specific threat model or promise protection against prompt-injected code.

Platforms And Agents

  • Host hardware: Apple silicon only.
  • Supported host release: macOS 26. Older macOS releases are not supported; Apple says maintainers usually will not fix problems that cannot be reproduced on macOS 26.
  • Guest images: Standard Linux OCI images. ARM64 runs natively; AMD64 images can run through Rosetta translation when configured.
  • Agents: No built-in Claude Code, Codex, Gemini, Aider, or other coding-agent integration.
  • Editor support: The repository includes a standalone container-machine Visual Studio Code example, but not an agent policy layer.
  • Higher-level use: Other projects can use Apple Container as a backend and add agent lifecycle, file staging, network policy, and credential controls.

Setup And Workflow

  1. Use an Apple-silicon Mac running macOS 26.
  2. Download Apple’s latest signed installer package from GitHub Releases.
  3. Approve administrator access so files can be placed under /usr/local.
  4. Start the user service with container system start.
  5. Pull or build an OCI image.
  6. Run it with only the mounts, environment values, sockets, ports, CPUs, memory, and networks it needs.
  7. Use --rm for automatic cleanup when the container exits.

Image builds use a separate builder VM. Volumes persist independently; bind mounts directly expose selected host directories.

Network And Credentials

Network

  • Default: Starting the system creates a default vmnet network. Containers attach to it unless another network is selected.
  • User networks: macOS 26 supports separate IPv4/IPv6 networks isolated from one another.
  • Internal mode: container network create --internal creates a host-only network.
  • Published services: TCP or UDP ports can be forwarded from a host address to a container.
  • Host access: A special local domain can be configured to reach a host service, but Apple documents Private Relay and restart-related packet-filter limits.

Apple Container does not document built-in hostname allowlists, request inspection, secret-aware proxies, or per-destination internet filtering. A normal attached network is broad network access. The internal option removes internet reachability but is not a selective egress policy.

Credentials

  • Registry login: Registry credentials are stored through macOS Keychain services for later pulls and pushes.
  • Build secrets: container build --secret can source build-time secrets from a host environment value or local path. This follows build-secret use, not a runtime agent credential broker.
  • Runtime environment: Individual values or an environment file can be passed into the container. Values inherited or copied this way are visible to container code.
  • SSH agent: --ssh forwards the macOS SSH authentication socket into the container. The private key file stays on the host, but untrusted container code can ask the agent to authenticate or sign while the socket is available.
  • No scoped injection: No feature was found that substitutes a secret only for an approved remote host or request.

For hostile agent code, forwarding the SSH agent or passing broad tokens should be treated as granting their authority to that code.

Strengths

  • VM per container: Strong isolation without abandoning normal container commands.
  • OCI compatibility: Pull from and push to standard registries; images work with other runtimes.
  • Native macOS stack: Uses Virtualization, vmnet, Keychain, XPC, launchd, and unified logging.
  • Apple silicon optimization: ARM64 workloads run on the native architecture.
  • Explicit host mounts: Each VM receives only the directories selected for that container.
  • Network separation: Custom networks isolate groups of containers; internal networks provide a host-only mode.
  • Resource controls: CPU and memory can be set per container VM.
  • Familiar workflow: Build, run, exec, logs, stats, volumes, registries, port publishing, and multi-platform images.
  • Signed releases: Apple publishes signed installer packages and verified release tags.
  • Large community signal: High star and fork counts plus frequent contributions.

Limits And Risks

  • Very narrow host support: Apple silicon and macOS 26 only.
  • Not an agent sandbox: No worktree protection, approval layer, agent launcher, task lifecycle, credential broker, or result-application workflow.
  • No selective egress controls: Network policy is broad network attachment or host-only internal networking.
  • Credential exposure choices: Passed environment values are readable; SSH socket forwarding grants active SSH-agent use.
  • Writable-mount risk: Agent code can alter every writable host path mounted into its VM.
  • VM overhead: Every container has its own kernel and memory. This costs more than shared-kernel containers.
  • Memory reclamation: Freed guest pages are not fully returned to macOS; Apple recommends restarting memory-heavy containers when needed.
  • Feature gaps: Apple’s technical overview says common container features remain under development.
  • Host-service routing limits: The localhost-domain feature can disable Private Relay, and its packet-filter rule is removed after restart.
  • Rosetta tradeoff: AMD64 compatibility is useful but adds translation and differs from native execution.
  • Security depends on Apple frameworks: VM isolation still relies on Virtualization.framework and its device interfaces.
  • Documentation drift: The main README still contains pre-1.0 stability language even though the current release is 1.1.0. Release-tag documentation should be used for exact behavior.

Activity And Maturity

  • Repository created: 2025-05-30
  • Latest push when checked: 2026-07-13
  • Latest release: 1.1.0 on 2026-07-06, with a verified tag
  • Repository signal: 682 commits displayed, about 47,831 stars, 1,604 forks, and 440 combined open issues and pull requests in GitHub metadata
  • Maintenance: Active Apple-led development with many outside contributors and integration tests.
  • Assessment: A fast-moving, post-1.0 general container runtime with strong adoption signal. It is mature enough to evaluate seriously for Mac container work, but its young age, high open-work count, evolving APIs, and missing agent safeguards mean a secure coding-agent workflow still needs a higher-level tool.

Best Fit

Apple Container fits:

  • Apple-silicon developers on macOS 26;
  • teams wanting normal OCI workflows with a separate VM per container;
  • local builds and tests that benefit from stronger isolation than a shared Docker VM;
  • higher-level sandbox tools that can add network and credential policy.

It is a weak fit for Intel Macs, older macOS, Linux/Windows hosts, agent-specific workflows, selective API egress, safely brokered credentials, or the lightest possible shared-kernel container density.

Comparison-Relevant Facts

FactApple Container
Primary purposeGeneral OCI container runtime and builder
Compute boundaryOne lightweight Linux VM per container
VM technologyApple Virtualization framework
Host supportApple silicon, macOS 26
Guest imagesLinux OCI images; ARM64 native, AMD64 via Rosetta
Agent integrationNone built in
Default networkAttached to default vmnet network
Network isolationSeparate networks; host-only internal mode
Hostname allowlistNot built in
Port forwardingTCP and UDP publishing
Host filesystemExplicit bind mounts and volumes
Registry credentialsStored through macOS Keychain
Runtime credentialsEnvironment values/files or forwarded SSH agent; no scoped broker
Disposal--rm removes the container; volumes and images are separate resources
Image portabilityOCI compatible
Root/admin needAdministrator approval for installation; some system DNS operations use elevated access
LicenseApache-2.0

Hacker News Context

A commenter asked whether Clawk could use Apple Container. Clawk’s author replied that early Clawk versions did use it. Both use Apple’s Virtualization framework and one container per VM, but Clawk moved to the raw framework because it needed network filtering.

That is the most important comparison: Apple Container already supplies the VM and OCI lifecycle, while Clawk adds an agent-oriented network control layer that Apple Container does not document.

Other comments provide ecosystem context:

  • A CodeRunner author said their agent sandbox was built when Apple Container was released.
  • yoloAI lists Apple Container as one of several Mac backends, adding its own network, secret, work-directory, agent, and lifecycle controls.
  • Another commenter linked Apple’s separate sandboxy example from the underlying Containerization repository. sandboxy is related technology, not the same Apple Container command-line product.

Unknowns

  • Agent security guidance: No official Apple threat model for hostile coding agents was found.
  • Fine egress roadmap: No confirmed plan for hostname or request-level filtering was found in the reviewed official sources.
  • Build-secret cleanup: Exact exposure and retention depend on the image build frontend and instructions; it was not tested here.
  • Independent audit: No public, project-specific external security audit was found in the reviewed material.
  • Runtime density: No current official benchmark comparing many per-container VMs with Docker Desktop or OrbStack was found.

Sources

Graph View