Take a guided tour of container by building, running, and publishing a simple web server image.
Start the application, and try out some basic commands to familiarize yourself with the command line interface (CLI) tool.
Start the services that container uses:
container system startIf you have not installed a Linux kernel yet, the command will prompt you to install one:
% container system start Verifying apiserver is running... Installing base container filesystem... No default kernel configured. Install the recommended default kernel from [https://github.com/kata-containers/kata-containers/releases/download/3.17.0/kata-static-3.17.0-arm64.tar.xz]? [Y/n]: y Installing kernel... %
Then, verify that the application is working by running a command to list all containers:
container list --allIf you haven't created any containers yet, the command outputs an empty list:
% container list --all ID IMAGE OS ARCH STATE ADDR %
You can get help for any container CLI command by appending the --help option:
% container --help OVERVIEW: A container platform for macOS USAGE: container [--debug] OPTIONS: --debug Enable debug output [environment: CONTAINER_DEBUG] --version Show the version. -h, --help Show help information. CONTAINER SUBCOMMANDS: create Create a new container delete, rm Delete one or more containers exec Run a new command in a running container inspect Display information about one or more containers kill Kill one or more running containers list, ls List containers logs Fetch container stdio or boot logs run Run a container start Start a container stop Stop one or more running containers IMAGE SUBCOMMANDS: build Build an image from a Dockerfile image, i Manage images registry, r Manage registry configurations SYSTEM SUBCOMMANDS: builder Manage an image builder instance system, s Manage system components %
You can save keystrokes by abbreviating commands and options. For example, abbreviate the container list command to container ls, and the --all option to -a:
% container ls -a ID IMAGE OS ARCH STATE ADDR %
Use the --help flag to see which abbreviations exist.
container includes an embedded DNS service that simplifies access to your containerized applications. If you want to configure a local DNS domain named test for this tutorial, run:
sudo container system dns create test
container system property set dns.domain testEnter your administrator password when prompted. The first command requires administrator privileges to create a file containing the domain configuration under the /etc/resolver directory, and to tell the macOS DNS resolver to reload its configuration files.
The second command makes test the default domain to use when running a container with an unqualified name. For example, if the default domain is test and you use --name my-web-server to start a container, queries to my-web-server.test will respond with that container's IP address.
Set up a Dockerfile for a basic Python web server, and use it to build a container image named web-test.
Start a terminal, create a directory named web-test for the files needed to create the container image:
mkdir web-test
cd web-testIn the web-test directory, create a file named Dockerfile with this content:
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"]The FROM line instructs the container builder to start with a base image containing the latest production version of Python 3.
The WORKDIR line creates a directory /content in the image, and makes it the current directory.
The first RUN line adds the curl command to your image, and the second RUN line creates a simple HTML landing page named /content/index.html.
The CMD line configures the container to run a simple web server in Python on port 80. Since the working directory is /content, the web server runs in that directory and delivers the content of the file /content/index.html when a user requests the index page URL.
The server listens on the wildcard address 0.0.0.0 to allow connections from the host and other containers. You can safely use the listen address 0.0.0.0 inside the container, because external systems have no access to the virtual network to which the container attaches.
Run the container build command to create an image with the name web-test from your Dockerfile:
container build --tag web-test --file Dockerfile .The last argument . tells the builder to use the current directory (web-test) as the root of the build context. You can copy files within the build context into your image using the COPY command in your Dockerfile.
After the build completes, list the images. You should see both the base image and the image that you built in the results:
% container image list NAME TAG DIGEST python alpine b4d299311845147e7e47c970... web-test latest 25b99501f174803e21c58f9c... %
Using your container image, run a web server and try out different ways of interacting with it.
Use container run to start a container named my-web-server that runs your webserver:
container run --name my-web-server --detach --rm web-testThe --detach flag runs the container in the background, so that you can continue running commands in the same terminal. The --rm flag causes the container to be removed automatically after it stops.
When you list containers now, my-web-server is present, along with the container that container started to build your image. Note that its IP address, shown in the ADDR column, is 192.168.64.3:
% container ls ID IMAGE OS ARCH STATE ADDR buildkit ghcr.io/apple/container-builder-shim/builder:0.0.3 linux arm64 running 192.168.64.2 my-web-server web-test:latest linux arm64 running 192.168.64.3 %
Open the website, using the container's IP address in the URL:
open http://192.168.64.3If you configured the local domain test earlier in the tutorial, you can also open the page with the full hostname for the container:
open http://my-web-server.testYou can run other commands in my-web-server by using the container exec command. To list the files under the content directory, run an ls command:
% container exec my-web-server ls /content index.html %
If you want to poke around in the container, run a shell and issue one or more commands:
% 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 %
The --tty and --interactive flag allow you to interact with the shell from your host terminal. The --tty flag tells the shell in the container that its input is a terminal device, and the --interactive flag connects what you input in your host terminal to the input of the shell in the container.
You will often see these two options abbreviated and specified together as -ti or -it.
Your web server is accessible from other containers as well as from your host. Launch a second container using your web-test image, and this time, specify a curl command to retrieve the index.html content from the first container.
Note
Container relies on the new features and enhancements present in macOS 26. As a result, the functionality of accessing the web server from another container will not work on macOS 15. See https://github.com/apple/container/blob/main/docs/technical-overview.md#macos-15-limitations for more details.
container run -it --rm web-test curl http://192.168.64.3The output should appear as:
% container run -it --rm web-test curl http://192.168.64.3 <!DOCTYPE html><html><head><title>Hello</title></head><body><h1>Hello, world!</h1></body></html> %
If you set up the test domain earlier, you can achieve the same result with:
container run -it --rm web-test curl http://my-web-server.testPush your image to a container registry, publishing it so that you and others can use it.
To publish your image, you need push images to a registry service that stores the image for future use. Typically, you need to authenticate with a registry to push an image. This example assumes that you have an account at a hypothetical registry named some-registry.example.com with username fido and a password or token my-secret, and that your personal repository name is the same as your username.
To sign into a secure registry with your login credentials, enter your username and password at the prompts after running:
container registry login some-registry.example.comCreate another name for your image that includes the registry name, your repository name, and the image name, with the tag latest:
container image tag web-test some-registry.example.com/fido/web-test:latestThen, push the image:
container image push some-registry.example.com/fido/web-test:latestNote
By default container is configured to use Docker Hub.
You can change the default registry to another value by running container system property set registry.domain some-registry.example.com.
See the other sub commands under container registry for more options.
To validate your published image, stop your current web server container, remove the image that you built, and then run using the remote image:
container stop my-web-server
container image delete web-test some-registry.example.com/fido/web-test:latest
container run --name my-web-server --detach --rm some-registry.example.com/fido/web-test:latestStop your container and shut down the application.
Stop your web server container with:
container stop my-web-serverIf you list all running and stopped containers, you will see that the --rm flag you supplied with the container run command caused the container to be removed:
% container list --all ID IMAGE OS ARCH STATE ADDR buildkit ghcr.io/apple/container-builder-shim/builder:0.0.3 linux arm64 running 192.168.64.2 %
When you want to stop container completely, run:
container system stop