# What Is the Purpose of `--init-image` in Apple Container?

> Discover the purpose of the --init-image flag in Apple Container. Customize your VM's boot logic by replacing the default init filesystem image before your OCI container starts.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: how-to-guide
- Published: 2026-06-20

---

**The `--init-image` flag lets you replace the default *vminit* init filesystem image in the lightweight VM with a custom one, enabling you to execute boot-time logic before the OCI container’s first process starts.**

The `apple/container` project provides a lightweight virtualization runtime for OCI containers that uses a minimal VM to host workloads. Understanding the `--init-image` flag is essential when you need to customize the initialization sequence that runs inside the VM but outside the container environment itself.

## What Is the `--init-image` Flag?

The `--init-image` flag is a runtime option for the `container run` and `container create` commands. According to the command reference in [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) (line 57), this flag accepts a container image reference that overrides the default init filesystem image used by the lightweight VM.

By default, the VM launches a minimal init process called `vminitd` that only forwards signals and reaps orphaned processes. When you specify `--init-image <image>`, the runtime swaps this default image for your custom one, which can execute a wrapper binary before handing control to the standard `vminitd.real`.

## Why Use a Custom Init Image?

### Boot-Time Initialization

Custom init images allow you to add logic that executes before the container starts. This is useful for launching daemons, configuring eBPF filters, or applying custom security policies at the VM level.

### Additional Services

You can run out-of-band services such as logging agents, network helpers, or debugging tools that must operate outside the container’s root filesystem but inside the VM boundary.

### Debugging and Instrumentation

A custom init image enables you to instrument the early boot stage by emitting custom log messages or attaching debuggers to troubleshoot boot-time failures before the container entrypoint executes.

## How the Init Image Fits Into the Boot Sequence

The init image runs **inside the lightweight VM but outside the OCI container** itself. This architectural separation means your custom init logic does not affect the container’s filesystem layout or user-space environment, yet it retains full control over the VM’s initialization sequence.

As implemented in `apple/container`, the init process executes after the VM kernel boots but before the OCI container’s entrypoint is launched. This timing is critical for setting up VM-level resources that the container will depend on.

## Building and Running a Custom Init Image

The following examples demonstrate how to build a custom init image and use it with the Container CLI, based on the implementation details found in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) (lines 558-564).

First, create a Dockerfile that wraps the default `vminitd` binary with custom logic:

```dockerfile

# Build a custom init image that wraps the default vminitd

FROM ghcr.io/apple/containerization/vminit:0.33.3 AS base

FROM ghcr.io/apple/containerization/vminit:0.33.3
COPY --from=base /sbin/vminitd /sbin/vminitd.real
COPY wrapper /sbin/vminitd

```

Build the image using the Container CLI:

```bash
container build -t local/custom-init:latest .

```

Run a container with your custom init image:

```bash
container run \
    --name my-container \
    --init-image local/custom-init:latest \
    alpine:latest \
    echo "hello world"

```

Verify that the custom init code executed by checking the VM boot logs:

```bash
container logs --boot my-container | grep custom-init

```

You can also use the flag with `container create` for containers that you start later:

```bash
container create \
    --init-image local/custom-init:latest \
    --name my-prepared-container \
    ubuntu:latest
container start my-prepared-container

```

## Testing and Validation

The CLI parsing and error handling for `--init-image` are validated in [`Tests/CLITests/Subcommands/Run/TestCLIRunInitImage.swift`](https://github.com/apple/container/blob/main/Tests/CLITests/Subcommands/Run/TestCLIRunInitImage.swift). This test file verifies that the flag correctly accepts image references and integrates with the command-line interface, ensuring proper behavior when users specify custom init images.

## Summary

- The `--init-image` flag replaces the default `vminit` init filesystem image in the lightweight VM that hosts the container.
- Custom init images execute before the OCI container starts, enabling boot-time logic, out-of-band services, and debugging capabilities.
- The init process runs inside the VM but outside the container boundary, preserving container isolation while allowing VM-level customization.
- Implementation details are documented in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) and [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md), with comprehensive tests in [`Tests/CLITests/Subcommands/Run/TestCLIRunInitImage.swift`](https://github.com/apple/container/blob/main/Tests/CLITests/Subcommands/Run/TestCLIRunInitImage.swift).

## Frequently Asked Questions

### Does the custom init image replace the container's entrypoint?

No. The custom init image runs inside the VM before the OCI container's first process starts. It does not replace the container's entrypoint or modify the container's filesystem. The init image executes `vminitd` (or your wrapper) in the VM context, then the container runs normally with its standard entrypoint.

### Can I use any container image as an init image?

While the image must conform to the expected format (containing a valid init binary at `/sbin/vminitd`), you can use any image that includes the necessary `vminit` components. The documentation in [`docs/how-to.md`](https://github.com/apple/container/blob/main/docs/how-to.md) recommends starting from the official `ghcr.io/apple/containerization/vminit` base image to ensure compatibility with the expected path structure and binary names.

### How do I debug issues with my custom init image?

Use the `container logs --boot <container-name>` command to view the VM boot logs, which include output from your custom init process. This allows you to see messages emitted during the init phase before the container's main process starts, making it easier to troubleshoot boot-time failures.

### Is the `--init-image` flag available for both `container run` and `container create`?

Yes. The flag is supported by both `container run` and `container create` commands, as verified in [`Tests/CLITests/Subcommands/Run/TestCLIRunInitImage.swift`](https://github.com/apple/container/blob/main/Tests/CLITests/Subcommands/Run/TestCLIRunInitImage.swift). When used with `container create`, the init image is configured but only executes when you subsequently run `container start`.