Examples of Using Apple Container: CLI Workflows, Code Snippets, and Tutorials
Apple Container provides ready-to-run examples for building OCI-compatible images and managing persistent Linux VMs via the container CLI, including a complete web server tutorial and VS Code integration workflow.
The apple/container repository is a Swift-based command-line tool that enables you to build, run, and manage OCI-compatible containers on macOS Apple silicon. Whether you are containerizing a web application or setting up a persistent development environment, the repository includes comprehensive examples in docs/tutorials/start-here.md and examples/container-machine-vscode/README.md that demonstrate production-ready workflows.
Starting the Container Service
Before executing any examples, you must initialize the system service that manages the hypervisor and networking back-end.
container system start
This command starts the underlying virtualization framework using Apple's Hypervisor.framework and initializes the embedded DNS service for local hostname resolution, as documented in the repository's README installation instructions.
Standard Container Workflow Examples
The standard workflow demonstrates how to build an image from a Dockerfile, run it as an isolated container, and publish it to a registry.
Building a Python Web Server Image
Create a directory for your project and define a Dockerfile that installs Python and serves static content:
# ./web-test/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"]
Build the image using the CLI, which delegates to a builder shim running a lightweight buildkit daemon:
container build --tag web-test --file Dockerfile .
As noted in docs/tutorials/start-here.md, the builder shim handles the actual execution of Dockerfile instructions while the CLI displays progress via the Sources/TerminalProgress/*.swift UI components.
Running and Inspecting Containers
Start the container in detached mode with automatic cleanup:
container run --name my-web-server --detach --rm web-test
Verify the running instance and retrieve its IP address:
container ls
# Output shows IP address, e.g., 192.168.64.3
Access the service through the browser using either the IP address or the local DNS domain if configured:
open http://192.168.64.3
# Or using the embedded DNS service:
open http://my-web-server.test
The embedded DNS service, configured automatically by the CLI, eliminates the need to remember IP addresses by mapping container names to local hostnames.
Executing Commands Inside Containers
You can inspect the filesystem of a running container without stopping it:
container exec my-web-server ls /content
# Returns: index.html
This pattern is useful for debugging or performing administrative tasks inside the sandboxed environment.
Monitoring Resource Usage
Check CPU and memory consumption for any running container:
container stats --no-stream my-web-server
The --no-stream flag returns a single snapshot rather than a continuous stream, making it suitable for scripting and logging.
Publishing Images to a Registry
Authenticate with your registry and push the built image:
container registry login my-registry.example.com
container image tag web-test my-registry.example.com/fido/web-test:latest
container image push my-registry.example.com/fido/web-test:latest
These commands follow the standard OCI distribution specification, ensuring compatibility with Docker Hub, GitHub Container Registry, and private registries.
Container Machine Workflow Examples
The container-machine subsystem provides persistent Linux VMs that function like remote servers, ideal for development workflows requiring stable IP addresses and SSH access.
Creating Persistent Development VMs
Create a machine named "ubuntu" that persists across reboots:
container machine create --set-default --name ubuntu ubuntu-machine:latest
container machine run
This workflow, detailed in examples/container-machine-vscode/README.md, creates a VM with a stable DNS name and IP address that you can access via SSH.
VS Code Integration
Connect your editor to the container machine using the Remote-SSH extension:
# Ensure the machine is running
container machine run
# Then connect VS Code to the displayed SSH address
This enables you to develop inside a Linux environment while maintaining the performance benefits of macOS Apple silicon virtualization.
Cleaning Up Resources
Stop and remove machines when finished, then shut down the system service:
container machine stop ubuntu
container machine rm ubuntu
container system stop
These commands ensure proper cleanup of the underlying Hypervisor.framework resources and virtual network interfaces.
Key Source Files and Architecture
Understanding the repository structure helps you navigate the codebase when extending functionality:
README.md— Contains high-level descriptions, installation instructions, and quick-start links for the CLI front-end.docs/tutorials/start-here.md— Provides the full tutorial covering build, run, stats, DNS, and registry operations.examples/container-machine-vscode/README.md— Demonstrates end-to-end container machine setup for development environments.Sources/TerminalProgress/*.swift— Implements the progress bar UI displayed during image builds.docs/command-reference.md— Exhaustive documentation of all CLI sub-commands and flags.
The architecture separates concerns between the CLI front-end (parsing sub-commands like run, build, and machine), the Containerization Swift package (handling VM isolation and virtual networking), and the builder shim (managing the buildkit daemon).
Summary
- Apple Container supports two primary workflows: standard ephemeral containers and persistent container machines.
- The
container buildcommand delegates to a builder shim runningbuildkit, whileSources/TerminalProgress/*.swiftprovides the build UI. - You can access containers via IP address or local DNS domains (
*.test) provided by the embedded DNS service. - The
container machinesubsystem creates persistent Linux VMs suitable for VS Code Remote-SSH development. - All examples are fully documented in
docs/tutorials/start-here.mdandexamples/container-machine-vscode/README.md.
Frequently Asked Questions
What is Apple Container and how does it differ from Docker?
Apple Container is a Swift-native CLI tool that builds and runs OCI-compatible containers using macOS-native virtualization technologies like Hypervisor.framework. Unlike Docker Desktop, it integrates deeply with macOS Apple silicon and provides an embedded DNS service and container-machine workflows for persistent development environments.
How does the local DNS service work in Apple Container?
The embedded DNS service automatically assigns local hostnames (e.g., my-web-server.test) to running containers without requiring manual /etc/hosts configuration. This is implemented in the networking layer and documented in the "local DNS domain" section of docs/tutorials/start-here.md.
Can I use Apple Container with VS Code Remote Development?
Yes, the container-machine workflow creates persistent VMs with stable SSH endpoints. You can configure VS Code's Remote-SSH extension to connect to these machines using the container machine run command, as demonstrated in examples/container-machine-vscode/README.md.
Where can I find the command reference for all available flags?
The complete CLI documentation is located in docs/command-reference.md, which lists all sub-commands including system, build, run, exec, stats, and machine with their specific parameters and usage patterns.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →