# Where to Find Apple Container Usage Examples: Complete Guide

> Discover Apple container usage examples in the apple/container repository. Find hands-on tutorials for VS Code remote development and container lifecycle management.

- Repository: [Apple/container](https://github.com/apple/container)
- Tags: getting-started
- Published: 2026-06-16

---

**Apple container usage examples are located in the `examples/` and `docs/tutorials/` directories of the apple/container repository, featuring hands-on workflows for VS Code remote development and basic container lifecycle management.**

The `apple/container` repository provides a native macOS containerization solution that bridges Swift development with Linux environments. If you are looking for practical **Apple container usage examples**, the project ships with comprehensive tutorials and working code samples that demonstrate how to create, run, and manage container machines and images on macOS.

## Exploring the Example Repository Structure

The repository organizes learning resources into two primary locations: the `examples/` directory for specific use cases and the `docs/tutorials/` path for guided introductions.

### VS Code Remote Development Workflow

The `examples/container-machine-vscode/` directory contains a complete end-to-end workflow for developing Linux-based Swift applications inside a container machine using VS Code. This example includes:

- [`examples/container-machine-vscode/README.md`](https://github.com/apple/container/blob/main/examples/container-machine-vscode/README.md): Step-by-step instructions for SSH setup, image building, and debugging
- `examples/container-machine-vscode/Dockerfile`: A minimal Ubuntu-based machine image configuration

### Getting Started Tutorial

The [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) file provides an introductory walkthrough covering the entire container lifecycle: starting the service, building a Python web-server image, running containers, and publishing to registries.

## Understanding the Container Architecture

Before running the examples, it helps to understand the three-layer architecture implemented in the source code.

### Container Service

The **Container Service** is a background daemon that manages the VM-based Linux kernel, networking, and DNS. According to [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md), you control this service with `container system start` and `container system stop`.

### Container Builder

The **Container Builder** uses a lightweight build-kit shim (`ghcr.io/apple/container-builder-shim/builder:0.0.3`) to compile Dockerfiles into OCI images. The builder runs as its own container when you execute `container build`.

### Container Machines

**Container Machines** are persistent VM-backed Linux environments created with `container machine create`. As documented in [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md), these machines expose virtual network interfaces and are reachable via embedded DNS services (e.g., `ubuntu.machine.test`).

## Running the VS Code Container Machine Example

The `examples/container-machine-vscode` example demonstrates the full stack. First, build the Ubuntu image referenced in the Dockerfile:

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

```

Then create a persistent machine and set it as the default:

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

```

After configuring your macOS SSH settings (`~/.ssh/config`) as described in the README, connect via SSH to develop inside VS Code using the Remote-SSH extension. Clean up with `container machine stop` and `container machine rm`.

## Complete Workflow: From System Start to Web Server

The [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) provides ready-to-copy commands for a complete workflow. Start the daemon:

```bash
container system start

```

Build a simple Python web-server image:

```bash
cat > Dockerfile <<'EOF'
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"]
EOF
container build --tag web-test --file Dockerfile .

```

Run the image in detached mode:

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

```

Optionally configure DNS access:

```bash
sudo container system dns create test
open http://my-web-server.test

```

## Key Reference Documentation

When extending these examples, consult [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) for detailed information on every `container` sub-command, including `container machine create`, `container build`, and `container run`. For architectural details, see [`docs/container-machine.md`](https://github.com/apple/container/blob/main/docs/container-machine.md) and the project's [`Package.swift`](https://github.com/apple/container/blob/main/Package.swift) for the Swift package definition.

## Summary

- **Apple container usage examples** are primarily located in `examples/container-machine-vscode/` and [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md)
- The VS Code example demonstrates persistent Linux development environments via `container machine create`
- The beginner tutorial covers the full lifecycle from `container system start` through image publishing
- Container machines use embedded DNS (e.g., `*.machine.test`) for networking
- The builder shim runs at `ghcr.io/apple/container-builder-shim/builder:0.0.3`

## Frequently Asked Questions

### Where are the Apple container examples located in the repository?

The primary examples are found in `examples/container-machine-vscode/` for VS Code integration and [`docs/tutorials/start-here.md`](https://github.com/apple/container/blob/main/docs/tutorials/start-here.md) for basic tutorials. The command reference at [`docs/command-reference.md`](https://github.com/apple/container/blob/main/docs/command-reference.md) supports these examples with detailed CLI documentation.

### How do I create a persistent Linux development environment with Apple Container?

Use `container machine create --set-default --name ubuntu ubuntu-machine:latest` after building your image. This creates a VM-backed Linux environment accessible via SSH at `ubuntu.machine.test` that persists until you run `container machine rm`.

### What is the difference between container run and container machine?

`container run` executes ephemeral containers similar to Docker, while `container machine create` provisions persistent VM-backed Linux environments with dedicated networking and DNS entries like `ubuntu.machine.test`.

### How do I start the Apple Container service before running examples?

Execute `container system start` to initialize the background daemon that manages the VM-based Linux kernel, networking, and DNS services required by all other container operations.