How-to

[!IMPORTANT] This file contains documentation for the CURRENT BRANCH. To find documentation for official releases, find the target release on the Release Page and click the tag corresponding to your release version.

Example: release 0.4.1 tag

container has a lot of surface area beyond the basic tutorial. Each topic below has its own guide — pick the one that matches what you're trying to do.

Topics

• Resource usage — CPU and memory limits for containers and builds, overcommitting resources, monitoring usage with container stats, and reclaiming disk space.
• Mounts and volumes — bind-mount host directories, create named volumes, and mount temporary tmpfs storage.
• Networking — DNS-based container names, container-to-container connectivity, port forwarding, custom MAC addresses, and isolated networks.
• Host integration — forward your SSH agent into a container, and reach a service running on your Mac from inside a container.
• Resource limits (ulimits) — per-process limits like open-file and process-count limits.
• Runtime configuration — Linux capabilities, masked and read-only paths, nested virtualization, and customizing the container's init process.
• Multiplatform images — build, run, and publish images that support both Apple silicon and x86-64.
• Inspecting containers and images — machine-readable inspect and list output for scripting.
• Logs — container output, VM boot logs, and the container system's own logs.
• config.toml reference — every configuration key, its default, and how to view your merged configuration.
• Container machines — persistent Linux environments built from OCI images, with your home directory mounted in and the filesystem surviving stop/start. See container-machine.md for the full guide.
• Shell completions — generate and install completion scripts for zsh, bash, and fish.