### Start Container System Services

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Starts the container services and optionally installs a default kernel. Use this command to ensure all background services are running.

```bash
container system start [--app-root <app-root>] [--install-root <install-root>] [--log-root <log-root>] [--enable-kernel-install] [--disable-kernel-install] [--timeout <timeout>] [--debug]
```

--------------------------------

### Install Bash Completions with Bash-Completion (Homebrew)

Source: https://github.com/apple/container/blob/main/docs/how-to.md

This example demonstrates installing bash completions using the `bash-completion` package, specifically when installed via Homebrew. The script is placed in the `bash_completion.d` directory.

```bash
container --generate-completion-script bash > /opt/homebrew/etc/bash_completion.d/container
source /opt/homebrew/etc/bash_completion.d/container
```

--------------------------------

### Container System Version - Table Output Example

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of the table output for `container system version`, showing component, version, build, and commit information.

```bash
container system version
```

```text
COMPONENT            VERSION                                                             BUILD    COMMIT
container            1.2.3                                                               debug    abcdef1
container-apiserver  container-apiserver version 1.2.3 (build: release, commit: 1234abc)  release  1234abcdef
```

--------------------------------

### Start BuildKit Builder Container

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Starts the BuildKit builder container. CPU and memory limits can be set for the builder.

```bash
container builder start [--cpus <cpus>] [--memory <memory>] [--dns <ip> ...] [--dns-domain <domain>] [--dns-option <option> ...] [--dns-search <domain> ...] [--debug]
```

--------------------------------

### Start Container System Service

Source: https://github.com/apple/container/blob/main/README.md

Starts the container system service. This command is used after initial installation or after stopping the service.

```bash
container system start
```

--------------------------------

### Handle Unsupported Virtualization

Source: https://github.com/apple/container/blob/main/docs/how-to.md

This example shows the error message received when nested virtualization is not supported on the platform.

```console
container run --name nested-virtualization --virtualization --kernel /path/to/a/kernel/with/virtualization/support --rm ubuntu:latest sh -c "dmesg | grep kvm"
Error: unsupported: "nested virtualization is not supported on the platform"
```

--------------------------------

### List Properties as JSON for Scripting

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of listing system properties in JSON format, suitable for scripting.

```bash
# output as JSON for scripting
container system property list --format json
```

--------------------------------

### Start Container Services

Source: https://github.com/apple/container/blob/main/BUILDING.md

Starts the container services after configuration changes or builds. Ensure services are stopped before starting.

```bash
bin/container system stop
bin/container system start
```

--------------------------------

### Example Container CLI version output

Source: https://github.com/apple/container/blob/main/docs/bug-report-how-to.md

Sample output format for the container --version command.

```text
container CLI version 0.10.0-27-g9fd15f0 (build: debug, commit: 9fd15f0)
```

--------------------------------

### Install Fish Completions

Source: https://github.com/apple/container/blob/main/docs/how-to.md

This snippet shows how to generate and install completion scripts for the Fish shell. The script is placed in the `~/.config/fish/completions/` directory.

```fish
container --generate-completion-script fish > ~/.config/fish/completions/container.fish
```

--------------------------------

### List All Properties in TOML Format

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of listing all system properties using the default TOML format.

```bash
# list all properties in TOML format (default)
container system property list
```

--------------------------------

### Example Xcode version output

Source: https://github.com/apple/container/blob/main/docs/bug-report-how-to.md

Sample output format for the xcodebuild -version command.

```text
Xcode 15.0
Build version 15A240d
```

--------------------------------

### Start Host HTTP Server for Container Access

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Start a simple HTTP server on the host machine to test access from a container. Ensure the server binds to an IP address accessible by the container.

```bash
mkdir -p /tmp/test; cd /tmp/test; echo "hello" > index.html
python3 -m http.server 8000 --bind 127.0.0.1
```

--------------------------------

### Install Pre-commit Hook

Source: https://github.com/apple/container/blob/main/BUILDING.md

Run the `make pre-commit` command to install a pre-commit hook for code formatting and license headers.

```bash
make pre-commit
```

--------------------------------

### Container System Version - YAML Output Example

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of the YAML output for `container system version`, similar to JSON but in YAML format.

```yaml
- version: 1.2.3
  buildType: debug
  commit: abcdef1
  appName: container
- version: 'container-apiserver version 1.2.3 (build: release, commit: 1234abc)'
  buildType: release
  commit: 1234abcdef
  appName: container-apiserver
```

--------------------------------

### Container System Version - JSON Output Example

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of the JSON output for `container system version`, representing components as an array of objects.

```json
[
  {
    "appName": "container",
    "buildType": "debug",
    "commit": "abcdef1",
    "version": "1.2.3"
  },
  {
    "appName": "container-apiserver",
    "buildType": "release",
    "commit": "1234abcdef",
    "version": "container-apiserver version 1.2.3 (build: release, commit: 1234abc)"
  }
]
```

--------------------------------

### Install Container Binaries

Source: https://github.com/apple/container/blob/main/BUILDING.md

Copies the compiled binaries to the system's standard locations. Requires administrator privileges.

```bash
make install
```

--------------------------------

### Container System Version - TOML Output Example

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of the TOML output for `container system version`, with component data nested under an 'items' key.

```toml
[[items]]
appName = "container"
buildType = "debug"
commit = "abcdef1"
version = "1.2.3"

[[items]]
appName = "container-apiserver"
buildType = "release"
commit = "1234abcdef"
version = "container-apiserver version 1.2.3 (build: release, commit: 1234abc)"
```

--------------------------------

### Example macOS version output

Source: https://github.com/apple/container/blob/main/docs/bug-report-how-to.md

Sample output format for the sw_vers command.

```text
ProductName:		macOS
ProductVersion:		26.0
BuildVersion:		12A345
```

--------------------------------

### Create Container with Init Process

Source: https://github.com/apple/container/blob/main/docs/how-to.md

The `--init` flag can also be used with `container create`. The container must then be started separately.

```bash
container create --init --name my-container ubuntu:latest my-app
container start my-container
```

--------------------------------

### Start Builder with Custom Resources

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Increase memory and CPU limits for the builder VM. This is useful for resource-intensive builds.

```bash
container builder start --cpus 8 --memory 32g
```

--------------------------------

### Build and Test Release Version

Source: https://github.com/apple/container/blob/main/BUILDING.md

Builds a release version of the container project for better performance and runs tests. Then installs the release binaries.

```bash
BUILD_CONFIGURATION=release make all test integration
BUILD_CONFIGURATION=release make install
```

--------------------------------

### Build Multiplatform Image

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Build an image supporting multiple architectures by specifying --arch options. This example builds for arm64 and amd64.

```bash
container build --arch arm64 --arch amd64 --tag registry.example.com/fido/web-test:latest --file Dockerfile .
```

--------------------------------

### Get Container CLI Help

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Displays help information for the container CLI and its subcommands. Use this to discover available commands and options.

```bash
container --help
```

--------------------------------

### Install Zsh Completions with Oh My Zsh

Source: https://github.com/apple/container/blob/main/docs/how-to.md

This snippet shows how to install zsh completion scripts when using oh-my-zsh. Ensure the completion script is named `_container` and placed in the `completions` directory.

```zsh
mkdir -p ~/.oh-my-zsh/completions
container --generate-completion-script zsh > ~/.oh-my-zsh/completions/_container
source ~/.oh-my-zsh/completions/_container
```

--------------------------------

### Example reproduction steps

Source: https://github.com/apple/container/blob/main/docs/bug-report-how-to.md

A template for documenting the sequence of actions that lead to a container failure.

```text
1. Create new container: `container create --name test-app ubuntu:latest`
2. Start the container: `container start test-app`
3. Container fails during bootstrap with error:
   "failed to bootstrap container test-app"
4. Container exits with code 1
```

--------------------------------

### Run a container with a specific image

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

This is the most basic usage of `container run`. It starts a container from the specified image.

```bash
container run IMAGE_NAME
```

--------------------------------

### Create volume with ordered journaling

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of creating a volume with ordered journaling using the --opt flag.

```bash
# create a volume with ordered journaling
container volume create --opt journal=ordered myvolume
```

--------------------------------

### Start a stopped container

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Use this command to start a container that has been previously stopped. You can optionally attach to its output streams and keep STDIN open.

```bash
container start [--attach] [--interactive] [--debug] <container-id>
```

--------------------------------

### Install Bash Completions Manually

Source: https://github.com/apple/container/blob/main/docs/how-to.md

If `bash-completion` is not installed, this method manually sources the completion script. It involves creating a directory and adding a source line to your bash profile.

```bash
mkdir -p ~/.bash_completions
container --generate-completion-script bash >  ~/.bash_completions/container
source ~/.bash_completions/container

source ~/.bash_completions/container
```

--------------------------------

### Go Wrapper for Custom Init Logic

Source: https://github.com/apple/container/blob/main/docs/how-to.md

A Go program that logs a message to the kernel and then executes the real vminitd binary. Useful for running custom initialization code before the main init process starts.

```go
// wrapper.go
package main

import (
    "os"
    "syscall"
)

func main() {
    // Write a message to kernel log
    kmsg, err := os.OpenFile("/dev/kmsg", os.O_WRONLY, 0)
    if err == nil {
        kmsg.WriteString("<6>custom-init: === CUSTOM INIT IMAGE RUNNING ===\n")
        kmsg.Close()
    }

    // Execute the real vminitd
    err = syscall.Exec("/sbin/vminitd.real", os.Args, os.Environ())
    if err != nil {
        os.Exit(1)
    }
}
```

--------------------------------

### Retrieve Xcode version

Source: https://github.com/apple/container/blob/main/docs/bug-report-how-to.md

Command to identify the installed Xcode version.

```bash
xcodebuild -version
```

--------------------------------

### Start Shell in Container Machine

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Starts an interactive shell session within the container machine. This allows for running ad-hoc commands directly inside the container.

```bash
container machine run
```

--------------------------------

### Run Web Server Container

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Starts a detached container named 'my-web-server' from the 'web-test' image. The container is automatically removed on stop.

```bash
container run --name my-web-server --detach --rm web-test
```

--------------------------------

### Create volume with writeback journaling and specific journal size

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of creating a volume with writeback journaling and a 64 MiB journal size.

```bash
# create a volume with writeback journaling and a 64 MiB journal
container volume create --opt journal=writeback:64m myvolume
```

--------------------------------

### Create Container Machine Without Booting

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Creates a container machine from an image but does not boot it. Useful for pre-configuration before starting.

```bash
# create a container machine without booting it
container machine create --no-boot alpine:3.22
```

--------------------------------

### Create volume with full data journaling and explicit size

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Example of creating a volume with full data journaling and an explicit 10 GiB size.

```bash
# create a volume with full data journaling and an explicit volume size
container volume create --opt journal=journal --opt size=10g myvolume
```

--------------------------------

### Get Container System Version Information

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Displays version information for the CLI and the API server. The output format can be specified.

```bash
container system version [--format <format>] [--debug]
```

--------------------------------

### Share Host Files with Container using --volume

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Mount a host folder to a filesystem path in the container to share data. This example mounts a local assets folder.

```bash
container run --volume ${HOME}/Desktop/assets:/content/assets docker.io/python:alpine ls -l /content/assets
```

--------------------------------

### Create a container

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Use this command to create a container from an image without starting it. It accepts various process, resource, and management flags similar to `container run`.

```bash
container create [<options>] <image> [<arguments> ...]
```

--------------------------------

### Find Launchd Service Labels

Source: https://github.com/apple/container/blob/main/BUILDING.md

List launchd services to find the labels for XPC helpers. This involves starting the container system, running a test container, and then listing services.

```console
% container system start
% container run -d --name test debian:bookworm sleep infinity
test
% launchctl list | grep container
27068   0       com.apple.container.container-network-vmnet.default
27072   0       com.apple.container.container-core-images
26980   0       com.apple.container.apiserver
27331   0       com.apple.container.container-runtime-linux.test
```

--------------------------------

### Create User Configuration Directory and File

Source: https://github.com/apple/container/blob/main/docs/tutorials/container-system-config-tutorial.md

Use these commands to create the necessary directory and an empty configuration file for the container service if they do not already exist.

```bash
mkdir -p ~/.config/container
touch ~/.config/container/config.toml
```

--------------------------------

### Run a container with an interactive shell

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Use this command to start a container and immediately open an interactive bash shell within it. This is useful for debugging or manual inspection.

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

--------------------------------

### Create and Boot Container Machine

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Creates and boots a container machine from a specified image. Allows configuration of name, resources, and default status.

```bash
# create and boot a container machine named my-machine
container machine create alpine:3.22 --name my-machine
```

--------------------------------

### Install Zsh Completions without Oh My Zsh

Source: https://github.com/apple/container/blob/main/docs/how-to.md

For zsh users without oh-my-zsh, this configures the function path and autoloads completions. The script is copied to `~/.zsh/completion`.

```zsh
fpath=(~/.zsh/completion $fpath)
autoload -U compinit
compinit

mkdir -p ~/.zsh/completion
container --generate-completion-script zsh > ~/.zsh/completion/_container
source ~/.zshrc
```

--------------------------------

### Start an interactive shell in a container

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Opens an interactive shell ('sh') within the 'my-web-server' container. Use '--tty' and '--interactive' (or '-ti') to enable terminal interaction. Useful for debugging and exploring the container's filesystem.

```bash
% container exec --tty --interactive my-web-server sh
/content # ls
index.html
/content # uname -a
Linux my-web-server 6.12.28 #1 SMP Tue May 20 15:19:05 UTC 2025 aarch64 Linux
/content # exit
%
```

--------------------------------

### Create Project Directory

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Creates a new directory for your project files and navigates into it.

```bash
mkdir web-test
cd web-test
```

--------------------------------

### Exposing Virtualization Capabilities

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Enable virtualization capabilities within the container using the `--virtualization` flag, requiring host and guest support.

```bash
container run --virtualization <image>
```

--------------------------------

### Build Swift Project

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Build the Swift project using the swift build command.

```bash
swift build
```

--------------------------------

### Install or Update Container Runtime Kernel on macOS

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Installs or updates the Linux kernel used by the container runtime on macOS hosts. Supports specifying architecture, binary path, or using a recommended kernel.

```bash
container system kernel set [--arch <arch>] [--binary <binary>] [--force] [--recommended] [--tar <tar>] [--debug]
```

--------------------------------

### Create and Run a Container Machine

Source: https://github.com/apple/container/blob/main/docs/container-machine.md

Create a container machine named 'dev' using the 'alpine:latest' image and then run commands within it. The 'whoami' command shows the host username, and 'pwd' shows the mounted home directory.

```bash
container machine create alpine:latest --name dev
container machine run -n dev whoami       # your host username, not root
container machine run -n dev pwd          # /home/<you> — your Mac home dir, mounted in
container machine run -n dev              # interactive shell; cd into your repos in $HOME
```

--------------------------------

### Enable Virtualization Capabilities

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Use the `--virtualization` flag with `container run` to expose virtualization capabilities to a container. This requires specific hardware and kernel support.

```console
container run --name nested-virtualization --virtualization --kernel /path/to/a/kernel/with/virtualization/support --rm ubuntu:latest sh -c "dmesg | grep kvm"
[    0.017245] kvm [1]: IPA Size Limit: 40 bits
[    0.017499] kvm [1]: GICv3: no GICV resource entry
[    0.017501] kvm [1]: disabling GICv2 emulation
[    0.017506] kvm [1]: GIC system register CPU interface enabled
[    0.017685] kvm [1]: vgic interrupt IRQ9
[    0.017893] kvm [1]: Hyp mode initialized successfully
```

--------------------------------

### Basic Container Run Usage

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

This is the basic syntax for running a container from an image. You can optionally provide arguments that will be passed to the container's init process.

```bash
container run [<options>] <image> [<arguments> ...]
```

--------------------------------

### Build Custom Init Wrapper for Linux arm64

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Command to compile the Go wrapper program into a Linux arm64 executable. Ensures cross-compilation for the target architecture.

```bash
CGO_ENABLED=0 GOOS=linux GOARCH=arm64 go build -o wrapper wrapper.go
```

--------------------------------

### List Containers with Abbreviations

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Demonstrates using abbreviated commands and options for listing containers. Use the --help flag to discover available abbreviations.

```bash
container ls -a
```

--------------------------------

### Create Container Machine with Custom Resources

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Creates a container machine with specified CPU and memory resources, and sets it as the default machine. Requires specifying the image.

```bash
# create a container machine with custom resources and set it as the default
container machine create --cpus 4 --memory 8G --set-default alpine:3.22
```

--------------------------------

### View Container Logs

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Display application output from a container using the `container logs` command. Use the `--boot` option to view logs related to the virtual machine boot and init process.

```bash
% container run -d --name my-web-server --rm registry.example.com/fido/web-test:latest
my-web-server
% curl http://my-web-server.test
< !DOCTYPE html><html ><head ><title >Hello</title ></head ><body ><h1 >Hello, world!</h1 ></body ></html >
% container logs my-web-server
192.168.64.1 - - [15/May/2025 03:00:03] "GET / HTTP/1.1" 200 -
%

```

```bash
% container logs --boot my-web-server
[    0.098284] cacheinfo: Unable to detect cache hierarchy for CPU 0
[    0.098466] random: crng init done
[    0.099657] brd: module loaded
[    0.100707] loop: module loaded
[    0.100838] virtio_blk virtio2: 1/0/0 default/read/poll queues
[    0.101051] virtio_blk virtio2: [vda] 1073741824 512-byte logical blocks (550 GB/512 GiB)
...
[    0.127467] EXT4-fs (vda): mounted filesystem without journal. Quota mode: disabled.
[    0.127525] VFS: Mounted root (ext4 filesystem) readonly on device 254:0.
[    0.127635] devtmpfs: mounted
[    0.127773] Freeing unused kernel memory: 2816K
[    0.143252] Run /sbin/vminitd as init process
2025-05-15T02:24:08+0000 info vminitd : [vminitd] vminitd booting...
2025-05-15T02:24:08+0000 info vminitd : [vminitd] serve vminitd api
2025-05-15T02:24:08+0000 debug vminitd : [vminitd] starting process supervisor
2025-05-15T02:24:08+0000 debug vminitd : port=1024 [vminitd] booting grpc server on vsock
...
2025-05-15T02:24:08+0000 debug vminitd : exits=[362: 0] pid=363 [vminitd] checking for exit of managed process
2025-05-15T02:24:08+0000 debug vminitd : [vminitd] waiting on process my-web-server
[    1.122742] IPv6: ADDRCONF(NETDEV_CHANGE): eth0: link becomes ready
2025-05-15T02:24:39+0000 debug vminitd : sec=1747275879 usec=478412 [vminitd] setTime
%

```

--------------------------------

### Clone Project Repository

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Clones the 'swift-server-todos-tutorial' project from GitHub to your macOS home directory. This project will be developed within the container machine.

```bash
cd ${HOME}
git clone git@github.com:swiftlang/swift-server-todos-tutorial.git
```

--------------------------------

### Build and Test Container Project

Source: https://github.com/apple/container/blob/main/BUILDING.md

Builds the container project and its background services, then runs basic and integration tests. Ensure to clean previous test data first.

```bash
rm -rf test-data
make APP_ROOT=test-data all test integration
```

--------------------------------

### Ping Container Machine

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Pings the container machine using its configured hostname to verify that the DNS setup is working correctly and the machine is reachable.

```bash
ping -c 1 ubuntu.machine
```

--------------------------------

### Run Container with Init Process

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Use the `--init` flag with `container run` to ensure a lightweight init process runs as PID 1, handling signals and reaping zombie processes.

```bash
container run --init ubuntu:latest my-app
```

--------------------------------

### Run a container in detached mode

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Starts a container in the background and maps a host port to a container port. Ideal for running services like web servers.

```bash
container run -d --name web -p 8080:80 nginx:latest
```

--------------------------------

### Guest Kernel Configuration

Source: https://github.com/apple/container/blob/main/docs/container-system-config.md

Specify the guest kernel binary path and the URL for downloading the kernel archive. The `binaryPath` is relative to the archive's root.

```toml
binaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186"
url = "https://github.com/kata-containers/kata-containers/releases/download/3.28.0/kata-static-3.28.0-arm64.tar.zst"
```

--------------------------------

### Build VM Resources Configuration

Source: https://github.com/apple/container/blob/main/docs/container-system-config.md

Configure resources and image for the builder VM. The `image` key specifies the builder image reference, and its tag is derived from the project's bundled `container-builder-shim` version.

```toml
rosetta = true
cpus = 2
memory = "2048mb"
image = "ghcr.io/apple/container-builder-shim/builder:<tag>"
```

--------------------------------

### Verify Custom Init in Container Logs

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Command to retrieve and filter boot logs for a specific container. Used to confirm that the custom init logic executed successfully.

```console
% container logs --boot my-container | grep custom-init
```

--------------------------------

### Get BuildKit Builder Status

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Shows the current status of the BuildKit builder. Without flags a human-readable table is displayed; formatted output is available for scripting.

```bash
container builder status [--format <format>] [--quiet] [--debug]
```

--------------------------------

### List Container System Properties in JSON Format

Source: https://github.com/apple/container/blob/main/docs/tutorials/container-system-config-tutorial.md

To obtain machine-readable output of the container service's configuration, use the `--format json` flag with the list command.

```bash
container system property list --format json
```

--------------------------------

### Reading Environment Variables from a File

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

The `--env-file` option allows you to load environment variables from a file, which should be in a key=value format. Blank lines and lines starting with '#' are ignored.

```bash
container run --env-file ./my_vars.env <image>
```

--------------------------------

### Log in to a container registry

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Authenticates with a specified container registry using username and password prompts. Replace 'some-registry.example.com' with your actual registry.

```bash
container registry login some-registry.example.com
```

--------------------------------

### Set Debugger Environment Variable (Service Prefix)

Source: https://github.com/apple/container/blob/main/BUILDING.md

Export the `CONTAINER_DEBUG_LAUNCHD_LABEL` environment variable with a prefix. This will cause all services whose labels start with this prefix to wait for a debugger.

```console
% export CONTAINER_DEBUG_LAUNCHD_LABEL=com.apple.container.container-runtime-linux
% container system start # Every service starting with `com.apple.container.container-runtime-linux` waits debugger
```

--------------------------------

### Drop a Single Linux Capability

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Use `--cap-drop` to remove a specific capability from the default set. This example demonstrates dropping CHOWN and attempting a privileged operation.

```console
% container run --cap-drop CHOWN alpine chown 100 /tmp
chown: /tmp: Operation not permitted
```

--------------------------------

### Create Local DNS Domain

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Sets up a local DNS domain for accessing containerized applications. Requires administrator privileges and prompts for a password.

```bash
sudo container system dns create test
```

--------------------------------

### Running with an Init Process

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Use the `--init` flag to run an init process inside the container, which helps in managing signals and reaping zombie processes. You can specify a custom init image with `--init-image`.

```bash
container run --init <image>
```

```bash
container run --init --init-image custom/init <image>
```

--------------------------------

### Setting Working Directory

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Use `-w`, `--workdir`, or `--cwd` to set the initial working directory inside the container.

```bash
container run -w /app <image>
```

--------------------------------

### Execute a command in a container

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Run a specific command, like 'ls /content', inside a named container ('my-web-server'). Useful for inspecting container contents without starting an interactive shell.

```bash
% container exec my-web-server ls /content
index.html
%
```

--------------------------------

### List Container Images

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Displays a list of available container images, including the newly built 'web-test' image.

```bash
container image list
```

--------------------------------

### List Container System Properties

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Lists all system properties and their current values. Output can be formatted as TOML (default) or JSON.

```bash
container system property list [--format <format>] [--debug]
```

--------------------------------

### Run a Single Command in a Container Machine

Source: https://github.com/apple/container/blob/main/docs/container-machine.md

Executes a single command within the specified container machine ('dev') and then exits. Examples include checking the system kernel version or displaying CPU information.

```bash
container machine run -n dev uname -a
```

```bash
container machine run -n dev -- cat /proc/cpuinfo
```

--------------------------------

### Create a Container Machine

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Creates a new container machine with a specified name and base image. Use this to set up a persistent Linux environment for development.

```console
% container machine create --name mymachine --set-default alpine:3.22
mymachine
```

--------------------------------

### Verify Ubuntu System

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Verify that the containerized environment is running Ubuntu Linux.

```bash
uname -s
cat /etc/os-release | grep PRETTY_NAME
```

--------------------------------

### Configure Container Resources

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Override default memory and CPU limits for a container. Use abbreviations for memory units.

```bash
container run --rm --cpus 8 --memory 32g big
```

--------------------------------

### Build Container Image

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Builds a container image named 'web-test' from the Dockerfile in the current directory.

```bash
container build --tag web-test --file Dockerfile .
```

--------------------------------

### Run Multiplatform Image (arm64)

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Run the arm64 variant of a multiplatform image to check system information.

```bash
container run --arch arm64 --rm registry.example.com/fido/web-test:latest uname -a
```

--------------------------------

### List Running Containers and Select IP Addresses with jq

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Use `container ls` with `--format json` and `jq` to select the ID and IP address of all running containers.

```bash
% container ls --format json --all | jq '.[] | select ( .status == "running" ) | [ .configuration.id, .networks[0].address ]'
[
  "my-web-server",
  "192.168.64.3/24"
]
[
  "buildkit",
  "192.168.64.2/24"
]

```

--------------------------------

### Run a container with environment variables and resource limits

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Configure a container to run with specific environment variables and set limits on CPU and memory usage. Useful for controlling application behavior and resource consumption.

```bash
container run -e NODE_ENV=production --cpus 2 --memory 1G node:18
```

--------------------------------

### Build Custom Init Image

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Command to build the Docker image defined in the Containerfile. Tags the image as local/custom-init:latest.

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

--------------------------------

### Run a container with restart policy

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Configure a restart policy using `--restart` to automatically restart the container if it stops or the host reboots.

```bash
container run --restart unless-stopped IMAGE_NAME
```

--------------------------------

### Create a container network

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Creates a new network with the specified name. Options include restricting to host-only, setting labels, options, plugins, and subnets.

```bash
container network create [--internal] [--label <label> ...] [--option <option> ...] [--plugin <plugin>] [--subnet <subnet>] [--subnet-v6 <subnet-v6>] [--debug] <name>
```

--------------------------------

### Mounting Volumes and Bind Mounts

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Use `-v` or `--volume` for bind mounts and `--mount` for more complex mount configurations, specifying source, target, and type.

```bash
container run -v /host/path:/container/path <image>
```

```bash
container run --mount type=bind,source=/host/path,target=/container/path <image>
```

--------------------------------

### Share Host Files with Container using --mount

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Achieve the same result as --volume using the --mount option with key=value syntax. This mounts a local assets folder.

```bash
container run --mount source=${HOME}/Desktop/assets,target=/content/assets docker.io/python:alpine ls -l /content/assets
```

--------------------------------

### Fetch container logs

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Fetches logs from a container. Use `--follow` to stream logs in real-time, `-n` to limit the number of lines, or `--boot` to view boot logs.

```bash
container logs [--boot] [--follow] [-n <n>] [--debug] <container-id>
```

--------------------------------

### Build and Create Container Machine

Source: https://github.com/apple/container/blob/main/docs/container-machine.md

Commands to build a container machine image from a Dockerfile and then create a container machine instance from that image.

```bash
container build -t local/ubuntu-machine:latest .
container machine create local/ubuntu-machine:latest --name ubuntu
```

--------------------------------

### Configure Local vminit Image

Source: https://github.com/apple/container/blob/main/BUILDING.md

Sets the init image for the container runtime to a local version. This is done by modifying the runtime configuration file.

```toml
[vminit]
image = "vminit:latest"
```

--------------------------------

### Build an OCI image with build arguments

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Passes build-time variables to the image build process. This allows for dynamic configuration during the image creation, such as specifying a Node.js version.

```bash
container build --build-arg NODE_VERSION=18 -t my-app .
```

--------------------------------

### List Container System Properties

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Command to display all configurable system properties for the container CLI and services. Shows default values for build, container, DNS, kernel, network, registry, and vminit settings.

```console
% bin/container system property ls
```

--------------------------------

### Create a Local DNS Domain for Containers

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Creates a new local DNS domain for containers. Requires administrator privileges and allows specifying a localhost IP.

```bash
container system dns create [--debug] [--localhost <localhost>] <domain-name>
```

--------------------------------

### VS Code Launch Configuration

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Configure VS Code to launch the Swift executable. Replace the program path with your specific executable location.

```json
{
    "type": "swift",
    "request": "launch",
    "name": "Launch Swift Executable",
    "program": "${workspaceRoot}/.build/debug/SwiftServerTodos",
    "args": [],
    "env": {},
    "cwd": "${workspaceRoot}"
}
```

--------------------------------

### Containerfile for Custom Init Image

Source: https://github.com/apple/container/blob/main/docs/how-to.md

A Dockerfile that copies a custom wrapper binary and the real vminitd into a new image. This image can then be used as a custom init image.

```dockerfile
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
```

--------------------------------

### Create and reuse an anonymous volume

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Demonstrates creating an anonymous volume by running a container with a volume mount, then reusing it by its ID.

```bash
# Creates anonymous volume
container run -v /data alpine

# Reuse anonymous volume by ID
VOL=$(container volume list -q | grep anon)
container run -v $VOL:/data alpine

# Manual cleanup
container volume rm $VOL
```

--------------------------------

### Build an OCI image with a specific tag

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Builds an OCI image from the current directory's build context and tags it. This is the standard way to create container images.

```bash
container build -t my-app:latest .
```

--------------------------------

### Compare Host and Container Environment

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Compares the working directory and username between the macOS host and a container machine. This helps in understanding the isolation and integration of the container environment.

```console
% pwd
/Users/max-mustermann/projects/container/examples/container-machine-vscode
% whoami
john
% container machine run
$ pwd
/Users/max-mustermann/projects/container/examples/container-machine-vscode
$ whoami
john
$ exit
%
```

--------------------------------

### Configuring Network Attachments

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Connect the container to a network using `--network`, optionally specifying MAC address and MTU.

```bash
container run --network my_network <image>
```

```bash
container run --network my_network,mac=02:42:ac:11:65:43,mtu=1500 <image>
```

--------------------------------

### Default Per-Container Resources Configuration

Source: https://github.com/apple/container/blob/main/docs/container-system-config.md

Set default CPU and memory limits for containers when not specified at runtime. These defaults are applied to `container run` and `container create` commands.

```toml
cpus = 4
memory = "1g"
```

--------------------------------

### Fetch container machine logs

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Retrieves logs from a container machine. Options include displaying the boot log, following new output in real-time, and limiting the number of lines shown.

```bash
container machine logs
```

--------------------------------

### Build Container Machine Image

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Builds a Docker image for the container machine using a provided Dockerfile. This image will be used to create the container machine.

```bash
container build -t ubuntu-machine:latest -f Dockerfile .
```

--------------------------------

### Access web server from another container using IP

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Launches a 'web-test' container to fetch 'index.html' from the web server using its IP address. Requires macOS 26 or later.

```bash
container run -it --rm web-test curl http://192.168.64.3
```

```bash
% container run -it --rm web-test curl http://192.168.64.3
<!DOCTYPE html><html lang="en"><head><title>Hello</title></head><body><h1>Hello, world!</h1></body></html>
%
```

--------------------------------

### TOML Configuration Sections

Source: https://github.com/apple/container/blob/main/docs/container-system-config.md

Overview of the main configuration sections available in `config.toml`. All top-level sections are optional and fall back to their defaults if omitted.

```toml
[build]
[container]
[dns]
[kernel]
[network]
[registry]
[vminit]
[plugin.<id>]
```

--------------------------------

### List Merged Container System Properties

Source: https://github.com/apple/container/blob/main/docs/tutorials/container-system-config-tutorial.md

Use this command to display the currently active configuration of the container service, showing merged values from all sources.

```console
% container system property list
```

--------------------------------

### Build Custom Builder Image

Source: https://github.com/apple/container/blob/main/BUILDING.md

Build a custom builder image and remove the existing buildkit container to use the new image.

```bash
container build -t builder .
container rm -f buildkit
```

--------------------------------

### Navigate to Container Project Directory

Source: https://github.com/apple/container/blob/main/BUILDING.md

Changes the current directory to the container project's root. This is a prerequisite for subsequent development commands.

```bash
cd container
```

--------------------------------

### List Running Containers

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Shows all currently running containers, including their IDs, images, and IP addresses.

```bash
container ls
```

--------------------------------

### Configure Local Builder Image

Source: https://github.com/apple/container/blob/main/BUILDING.md

Add the custom builder image configuration to `~/.config/container/config.toml`.

```toml
[build]
image = "builder:latest"
```

--------------------------------

### Create Ubuntu Container Machine

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Creates a container machine named 'ubuntu' using the previously built 'ubuntu-machine:latest' image. It also sets this machine as the default.

```bash
container machine create --set-default --name ubuntu ubuntu-machine:latest
```

--------------------------------

### List Container Registry Logins

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Lists image registry logins. Can be filtered by format or output only the registry hostname.

```bash
container registry list [--format <format>] [--quiet] [--debug]
```

--------------------------------

### Drop All Capabilities and Add Specific Ones

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Use `--cap-drop ALL` followed by `--cap-add` to remove all default capabilities and then selectively grant only the necessary ones. Adds are processed after drops.

```bash
container run --cap-drop ALL --cap-add SETUID --cap-add SETGID alpine id
```

--------------------------------

### Dockerfile for Ubuntu 24.04 Container Machine

Source: https://github.com/apple/container/blob/main/docs/container-machine.md

This Dockerfile sets up an Ubuntu 24.04 image with systemd and essential tools for use as a container machine. It includes steps for updating packages, cleaning up, and configuring systemd services.

```dockerfile
FROM ubuntu:24.04

ENV container container

RUN apt-get update && \
    apt-get install -y \
    dbus systemd openssh-server net-tools iproute2 iputils-ping curl wget vim-tiny man sudo && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/* && \
    yes | unminimize

RUN >/etc/machine-id
RUN >/var/lib/dbus/machine-id

RUN systemctl set-default multi-user.target
RUN systemctl mask \
      dev-hugepages.mount \
      sys-fs-fuse-connections.mount \
      systemd-update-utmp.service \
      systemd-tmpfiles-setup.service \
      console-getty.service
RUN systemctl disable \
      networkd-dispatcher.service

RUN sed -i -e 's/^AcceptEnv LANG LC_*/#AcceptEnv LANG LC_*/' /etc/ssh/sshd_config
```

--------------------------------

### Access Web Server via Hostname

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Opens the web server using the container's hostname, assuming local domain configuration.

```bash
open http://my-web-server.test
```

--------------------------------

### Publishing Ports and Sockets

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Expose container ports to the host using `-p` or `--publish`, and publish host sockets using `--publish-socket`.

```bash
container run -p 8080:80 <image>
```

```bash
container run -p 127.0.0.1:8080:80/tcp <image>
```

```bash
container run --publish-socket /host/path.sock:/container/path.sock <image>
```

--------------------------------

### Build an OCI image with multiple tags

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Tags a newly built OCI image with multiple names and versions simultaneously. This is useful for releasing an image under different identifiers.

```bash
container build -t my-app:latest -t my-app:v1.0.0 -t my-app:stable .
```

--------------------------------

### Inspect container networks

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Shows detailed information about one or more specified networks.

```bash
container network inspect <networks> ... [--debug]
```

--------------------------------

### Run Container with Custom Init Image

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Command to run a container using a specified custom init image. The --init-image flag directs the container runtime to use the custom image for initialization.

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

--------------------------------

### Retrieve system logs

Source: https://github.com/apple/container/blob/main/docs/bug-report-how-to.md

Command to fetch system-level logs for container issues.

```bash
container system logs
```

--------------------------------

### Set Custom Container and DNS Configuration Values

Source: https://github.com/apple/container/blob/main/docs/tutorials/container-system-config-tutorial.md

Add these TOML entries to your user configuration file to override default CPU and memory limits for containers and set a custom DNS domain.

```toml
[container]
cpus = 8
memory = "4g"

[dns]
domain = "test"
```

--------------------------------

### List Available Container Networks

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Run `container network list` to view all existing networks, their state, and their assigned subnets. This helps in managing and understanding network configurations.

```console
% container network list
NETWORK  STATE    SUBNET
default  running  192.168.64.0/24
foo      running  192.168.65.0/24
%
```

--------------------------------

### Build an OCI image using a custom Dockerfile

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Builds an OCI image using a Dockerfile located at a specific path, rather than the default 'Dockerfile'. Useful for managing multiple build configurations.

```bash
container build -f docker/Dockerfile.prod -t my-app:prod .
```

--------------------------------

### List All Containers

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Lists all containers, including stopped ones. Outputs an empty list if no containers have been created.

```bash
container list --all
```

--------------------------------

### View Container Stats (No Stream)

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Displays a static snapshot of resource usage statistics for a container. Useful for scripting or quick checks.

```bash
container stats --no-stream my-web-server
```

--------------------------------

### List containers

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Lists containers, defaulting to only running ones. Output can be formatted as table, JSON, YAML, or TOML. Use `--all` to include non-running containers and `--quiet` to only output container IDs.

```bash
container list [--all] [--format <format>] [--quiet] [--debug]
```

--------------------------------

### Push Multiplatform Image

Source: https://github.com/apple/container/blob/main/docs/how-to.md

Push a multiplatform image to a registry. The command is the same as for a single-platform image.

```bash
container image push registry.example.com/fido/web-test:latest
```

--------------------------------

### Adding Linux Capabilities

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

You can add or drop specific Linux capabilities for the container using `--cap-add` and `--cap-drop`. Capabilities can be specified by name or number.

```bash
container run --cap-add NET_ADMIN <image>
```

```bash
container run --cap-drop ALL <image>
```

--------------------------------

### List all containers

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Displays all containers, including stopped ones. The output shows that the '--rm' flag removed the web server container after it stopped.

```bash
% container list --all
ID        IMAGE                                               OS     ARCH   STATE    IP
buildkit  ghcr.io/apple/container-builder-shim/builder:0.0.3  linux  arm64  running  192.168.64.2
%
```

--------------------------------

### List Container Machines

Source: https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md

Displays a list of all available container machines, including their state, IP address, and resource allocation. Useful for managing existing environments.

```console
% container machine ls
NAME       CREATED              IP             CPUS  MEMORY  DISK  STATE    DEFAULT
mymachine  2026-06-03 15:56:14  192.168.71.15  8     64G     75M   running  *
```

--------------------------------

### Dockerfile for Web Server

Source: https://github.com/apple/container/blob/main/docs/tutorials/start-here.md

Defines a container image with Python, a web server, and a simple HTML page.

```dockerfile
FROM docker.io/python:alpine
WORKDIR /content
RUN apk add curl
RUN echo '<!DOCTYPE html><html><head><title>Hello</title></head><body><h1>Hello, world!</h1></body></html>' > index.html
CMD ["python3", "-m", "http.server", "80", "--bind", "0.0.0.0"]
```

--------------------------------

### Show Disk Usage for Container Resources

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Displays disk usage statistics for images, containers, and volumes. Supports different output formats.

```bash
container system df [--format <format>] [--debug]
```

--------------------------------

### Setting Container Labels

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Add key-value labels to the container using the `-l` or `--label` flag for metadata and organization.

```bash
container run -l com.example.version=1.0 <image>
```

--------------------------------

### Display real-time container resource usage statistics

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Shows CPU percentage, memory usage, network I/O, block I/O, and process count for containers. By default, it continuously updates statistics interactively. Use `--no-stream` for a single snapshot.

```bash
container stats
```

```bash
container stats web db cache
```

```bash
container stats --no-stream web
```

```bash
container stats --format json --no-stream web
```

--------------------------------

### Compile Protobufs for gRPC

Source: https://github.com/apple/container/blob/main/BUILDING.md

Re-generates gRPC code used for communication with the builder virtual machine. This is necessary if changes are made to the gRPC APIs in the container-builder-shim project.

```bash
make protos
```

--------------------------------

### Setting User and Group IDs

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

You can specify the user and group IDs for the process running inside the container using `--uid`, `--gid`, or the combined `--user` flag.

```bash
container run --uid 1000 --gid 1000 <image>
```

```bash
container run --user myuser:mygroup <image>
```

--------------------------------

### List container machines

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Lists all available container machines. The default machine is indicated in the output. Supports custom output formats and quiet mode.

```bash
container machine list
```

--------------------------------

### List Volumes

Source: https://github.com/apple/container/blob/main/docs/command-reference.md

Lists all available volumes. Can be filtered by format or output only the volume name.

```bash
container volume list [--format <format>] [--quiet] [--debug]
```