# Examples of Using Apple Container: CLI Workflows, Code Snippets, and Tutorials
> Explore Apple Container examples for OCI images and Linux VMs. Discover CLI workflows, code snippets, and tutorials for web servers and VS Code integration with the apple/container repo.
- Repository: [Apple/container](https://github.com/apple/container)
- Tags: getting-started
- Published: 2026-06-30
---
**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`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) and [`examples/container-machine-vscode/README.md`](https://github.com/apple/container/blob/main/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.
```bash
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:
```Dockerfile
# ./web-test/Dockerfile
FROM docker.io/python:alpine
WORKDIR /content
RUN apk add curl
RUN echo 'HelloHello, world!
' > 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:
```bash
container build --tag web-test --file Dockerfile .
```
As noted in [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/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:
```bash
container run --name my-web-server --detach --rm web-test
```
Verify the running instance and retrieve its IP address:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
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:
```bash
container machine create --set-default --name ubuntu ubuntu-machine:latest
container machine run
```
This workflow, detailed in [`examples/container-machine-vscode/README.md`](https://github.com/apple/container/blob/main/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:
```bash
# 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:
```bash
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`](https://github.com/apple/container/blob/main/README.md)** — Contains high-level descriptions, installation instructions, and quick-start links for the CLI front-end.
- **[`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md)** — Provides the full tutorial covering build, run, stats, DNS, and registry operations.
- **[`examples/container-machine-vscode/README.md`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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 build`** command delegates to a builder shim running `buildkit`, while `Sources/TerminalProgress/*.swift` provides the build UI.
- You can access containers via IP address or local DNS domains (`*.test`) provided by the embedded DNS service.
- The **`container machine`** subsystem creates persistent Linux VMs suitable for VS Code Remote-SSH development.
- All examples are fully documented in [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) and [`examples/container-machine-vscode/README.md`](https://github.com/apple/container/blob/main/examples/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/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`](https://github.com/apple/container/blob/main/docs/command-reference.md), which lists all sub-commands including `system`, `build`, `run`, `exec`, `stats`, and `machine` with their specific parameters and usage patterns.