Skip to main content

​
Quick start

This guide will get you up and running with Container CLI by building a simple web server image and running it as a container.

​
Prerequisites

Before you begin, make sure you have installed Container CLI on your Mac with Apple silicon.

​
Start the container service

First, start the services that container uses: 
container system start
If you have not installed a Linux kernel yet, the command will prompt you to install one. Type y and press Enter to proceed.
You only need to start the container service once after each system restart. The service will continue running in the background.

​
Build your first image

1

Create a project directory

Create a directory for your first container project:
mkdir web-test
cd web-test
2

Create a Dockerfile

In 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"]
This Dockerfile:
  • Starts with a Python 3 base image
  • Creates a /content directory
  • Adds the curl command
  • Creates a simple HTML landing page
  • Configures the container to run a Python web server on port 80
3

Build the image

Run the container build command to create an image named web-test:
container build --tag web-test --file Dockerfile .
The . at the end tells the builder to use the current directory as the build context.
4

Verify the image

List your images to verify the build succeeded:
container image list
You should see both the base image and your newly built image:
% container image list
NAME      TAG     DIGEST
python    alpine  b4d299311845147e7e47c970...
web-test  latest  25b99501f174803e21c58f9c...
%

​
Run your first container

1

Start the container

Use container run to start a container named my-web-server:
container run --name my-web-server --detach --rm web-test
The --detach flag runs the container in the background, and the --rm flag removes the container automatically after it stops.
2

Check container status

List running containers:
container list
You should see your web server container running:
% 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
%
The buildkit container was automatically started to build your image. It remains running to speed up future builds.
3

Access the web server

Open the website using the container’s IP address from the ADDR column:
open http://192.168.64.3
You should see “Hello, world!” in your browser.

​
Interact with your container

​
Execute commands in the container

Run commands inside your running container using container exec: 
container exec my-web-server ls /content
Output: 
% container exec my-web-server ls /content
index.html
%

​
Open an interactive shell

You can also run an interactive shell to explore the container: 
container exec --tty --interactive my-web-server sh
This opens a shell prompt inside the container: 
% 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 flags (often abbreviated as -ti or -it) allow you to interact with the shell from your terminal.

​
Monitor resource usage

Monitor your container’s resource usage with the container stats command: 
container stats --no-stream my-web-server
This displays CPU usage, memory consumption, network traffic, and more: 
% container stats --no-stream my-web-server
Container ID    Cpu %   Memory Usage          Net Rx/Tx            Block I/O            Pids
my-web-server   0.23%   12.45 MiB / 1.00 GiB  856.00 KiB / 1.2 KiB 2.10 MiB / 512 KiB   2
%

​
Clean up

When you’re done, stop the container: 
container stop my-web-server
Since you used the --rm flag when starting the container, it will be automatically removed after stopping.
To completely shut down Container CLI, run container system stop. This stops all containers and the container service.

​
Useful commands and abbreviations

You can save keystrokes by abbreviating commands and options: 
# Full command
container list --all

# Abbreviated
container ls -a

​
Optional: Set up local DNS

container includes an embedded DNS service that simplifies access to your containerized applications. To configure a local DNS domain named test:
1

Create the DNS domain

Run this command (requires administrator password):
sudo container system dns create test
2

Set default domain

Make test the default domain:
container system property set dns.domain test
3

Use DNS names

Now you can access containers by name. For example, if you start a container with --name my-web-server, you can access it at:
open http://my-web-server.test

​
Next steps

Now that you’ve built and run your first container, explore more features:

Build docs developers (and LLMs) love

Get started for freeTalk to us