How to Run an Interactive Ubuntu Container with Apple Container

Use container run -it ubuntu:latest /bin/bash after initializing the system with container system start to launch an interactive Ubuntu shell on macOS.

Apple Container is an open-source project that runs Linux containers on macOS by launching a lightweight virtual machine for each container. Because the CLI consumes standard OCI images, you can run an interactive Ubuntu container with Apple Container using any Ubuntu image published to a Docker registry. This guide covers the complete workflow from system initialization to accessing a bash prompt inside Ubuntu.

Start the Container System

Before running any containers, you must start the backend services. According to the README.md in the apple/container repository, the following command launches the container-apiserver and helper services that manage VMs, networking, and images:

container system start

Run this once per session or ensure it is running before executing container commands.

Pull the Ubuntu Image (Optional)

While container automatically pulls images on first use, explicit pulling allows you to verify architecture compatibility and monitor download progress. As documented in docs/command-reference.md, use the --arch flag to select the variant matching your host or desired target:

# For Apple Silicon (arm64)

container image pull ubuntu:latest --arch arm64

# For Intel-based containers (amd64)

container image pull ubuntu:latest --arch amd64

If omitted, the CLI defaults to the host architecture.

Launch an Interactive Ubuntu Shell

To run an interactive Ubuntu container with Apple Container, use the run command with the -i and -t flags. The -i (interactive) keeps stdin open, while -t allocates a pseudo-TTY for terminal interaction:

container run -it ubuntu:latest /bin/bash

This command starts a bash shell inside the Ubuntu container, returning you to a Linux prompt where you can execute standard Ubuntu commands.

Cross-Architecture Support

If you are running on Apple Silicon but need an x86-64 Ubuntu environment, specify the architecture explicitly:

container run -it --arch amd64 ubuntu:latest /bin/bash

The --arch flag selects the image variant, allowing you to run Intel-based containers on ARM hosts and vice versa.

Configure Runtime Options

The container run command supports several flags defined in docs/command-reference.md to customize the container environment.

Resource Limits

Prevent oversubscription by limiting CPU and memory:

container run -it --cpus 2 --memory 4G ubuntu:latest /bin/bash

Networking

Create a custom network and attach the container with a specific MAC address:

container network create mynet
container run -it --network mynet,mac=02:42:ac:11:00:02 ubuntu:latest /bin/bash

Init Process

Run an init helper that forwards signals and reaps zombie processes:

container run -it --init ubuntu:latest /bin/bash

This is recommended for long-running interactive sessions or when running services that spawn child processes.

Stop the Container

When you exit the shell using exit or Ctrl-D, the container stops automatically if you passed the --rm flag. Otherwise, stop it explicitly using its ID:

container stop <container-id>

Summary

• Start the VM backend with container system start before running any containers, which launches the container-apiserver according to README.md
• Use container run -it ubuntu:latest /bin/bash to get an interactive shell, as specified in docs/command-reference.md
• Specify --arch amd64 or --arch arm64 to select the image architecture for cross-platform compatibility
• Add --cpus, --memory, --network, or --init flags to configure container resources, networking, and process management
• Exit the shell or use container stop to terminate the container

Frequently Asked Questions

Do I need to manually pull the Ubuntu image before running it?

No, Apple Container automatically pulls the image on first use if it is not already present locally. However, running container image pull ubuntu:latest explicitly allows you to verify the architecture and see download progress before starting the container.

Can I run x86-64 Ubuntu containers on Apple Silicon Macs?

Yes, use the --arch amd64 flag when running or pulling the image. For example: container run -it --arch amd64 ubuntu:latest /bin/bash. The system handles the architecture translation within the lightweight VM as described in docs/technical-overview.md.

What does the --init flag do when running a container?

The --init flag inserts an init process as PID 1 that forwards signals and reaps zombie processes, which is useful when running interactive shells or applications that require proper signal handling. Without it, your process runs directly as PID 1.

How do I limit CPU and memory for an Ubuntu container?

Pass the --cpus and --memory flags to the run command, such as container run -it --cpus 2 --memory 4G ubuntu:latest /bin/bash. These constraints prevent the container from oversubscribing host resources according to the limits defined in docs/command-reference.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}