> For the complete documentation index, see [llms.txt](https://docs.earthbuild.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.earthbuild.dev/docs/guides/apple-container.md).

# Apple Container

[Apple Container](https://github.com/apple/container) is Apple's native container runtime for macOS on Apple Silicon. It is a lightweight, daemonless container engine that runs Linux containers via macOS virtualization.

EarthBuild supports Apple Container as a native container engine on macOS (`darwin/arm64`), allowing you to run builds and manage the BuildKit daemon without Docker Desktop or Podman.

## Prerequisites

* **macOS on Apple Silicon** (`arm64`, M-series chips, macOS 26+).
* **Apple Container CLI** installed:

  ```bash
  brew install container
  ```
* **Start the container system service**:

  ```bash
  container system start --enable-kernel-install
  ```

## Getting started

When `earth` starts, it automatically detects available container engines in this order:

1. **Docker**
2. **Podman**
3. **Apple Container**

If Docker is not running and Apple Container is available, EarthBuild will automatically use Apple Container.

To explicitly configure EarthBuild to always use Apple Container:

```bash
earth config global.container_frontend apple-container
```

You can verify the configuration in your `~/.earth/config.yml` file:

```yaml
global:
  container_frontend: apple-container
```

Then, run a build to verify the integration:

```bash
earth github.com/EarthBuild/hello-world:main+hello
```

You should see BuildKit start up inside Apple Container:

```
 1. Init 🚀
————————————————————————————————————————————————————————————————————————————————

           buildkitd | Starting buildkit daemon as Apple Container (earth-buildkitd)...
           buildkitd | ...Done
```

## Features & Integration Details

### Rosetta 2 Translation

Apple Container runs containers with `--rosetta` enabled by default. This allows executing both `linux/arm64` and `linux/amd64` binaries within your build steps seamlessly using macOS Rosetta translation.

### Automatic Resource Sizing

On macOS, EarthBuild automatically probes host hardware and allocates **25% of system RAM** (minimum 4GB) and **all CPU cores** to the BuildKit daemon VM container, ensuring high performance without manual VM tuning.

## Troubleshooting

### "container system service is not running"

Ensure the Apple Container service is running:

```bash
container system status
```

If it is stopped, start it with:

```bash
container system start --enable-kernel-install
```

### Checking Container Logs

If the daemon fails to start, inspect the container logs:

```bash
container logs earth-buildkitd
```

### Cleaning Up

To reset and remove the EarthBuild daemon and cache volume in Apple Container:

```bash
container delete -f earth-buildkitd
container volume delete earth-cache
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.earthbuild.dev/docs/guides/apple-container.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
