containerization
Containerization is a Swift package for running Linux containers on macOS.
File Explorer
- 01-bug.yml
- 02-feature.yml
- config.yml
- build-test-images.yml
- containerization-build-template.yml
- containerization-build.yml
- docs-release.yaml
- linux-build.yml
- release.yml
- Containerization-Logo.png
- single-file-mounts.md
- x86_64-build.md
- main.swift
- ctr-example.entitlements
- lab.md
- Makefile
- Package.resolved
- Package.swift
- README.md
- Int+Formatted.swift
- Int64+Formatted.swift
- ProgressBar+Add.swift
- ProgressBar+State.swift
- ProgressBar+Terminal.swift
- ProgressBar.swift
- ProgressConfig.swift
- ProgressTaskCoordinator.swift
- ProgressTheme.swift
- ProgressUpdate.swift
- StandardError.swift
- AgentDefinition.swift
- CacheCommand.swift
- ConfigCommand.swift
- EditCommand.swift
- HostProxy.swift
- InstanceState.swift
- KernelManager.swift
- ListCommand.swift
- OutputCapture.swift
- ProgressUI.swift
- RemoveCommand.swift
- RunAgentCommand.swift
- Sandboxy.swift
- SandboxyConfig.swift
- SandboxyError.swift
- Makefile
- Package.resolved
- Package.swift
- README.md
- sandboxy.entitlements
- README.md
- x86_64-linux-gnu-ar
- x86_64-linux-gnu-g++
- x86_64-linux-gnu-gcc
- x86_64-linux-gnu-ld
- x86_64-linux-gnu-ranlib
- x86_64-linux-gnu-strip
- x86_64-linux-musl-ar
- x86_64-linux-musl-g++
- x86_64-linux-musl-gcc
- x86_64-linux-musl-ranlib
- x86_64-linux-musl-strip
- Dockerfile
- Dockerfile
- sources.list
- build.sh
- config-arm64
- config-x86_64
- Makefile
- README.md
- virtiofsd-skip-cap-drop-with-sandbox-none.patch
- build-dist-x86_64.sh
- build-glibc-x86_64-deps.sh
- build-initfs.sh
- build-musl-x86_64-deps.sh
- check-integration-test-vm-panics.sh
- cz-header-style.toml
- ensure-hawkeye-exists.sh
- install-hawkeye.sh
- license-header.txt
- make-docs.sh
- pre-commit.fmt
- vz.entitlements
- BridgeCommand.swift
- cctl+Utils.swift
- cctl.swift
- ImageCommand.swift
- KernelCommand.swift
- LoginCommand.swift
- RootfsCommand.swift
- RunCommand.swift
- Client+Hotplug.swift
- Client+VM.swift
- Client+VMM.swift
- DeviceConfigs.swift
- VmConfig.swift
- VmInfo.swift
- CloudHypervisor+Client.swift
- CloudHypervisor+Error.swift
- CloudHypervisor.swift
- HTTPOverUDS.swift
- README.md
- ImageStore+Export.swift
- ImageStore+Import.swift
- ImageStore+OCILayout.swift
- ImageStore+ReferenceManager.swift
- ImageStore.swift
- EXT4Unpacker.swift
- Unpacker.swift
- Image.swift
- InitImage.swift
- KernelImage.swift
- ReaderStream.swift
- Terminal+ReaderStream.swift
- Writer.swift
- SandboxContext.grpc.swift
- SandboxContext.pb.swift
- SandboxContext.proto
- AttachedFilesystem.swift
- BridgeManager.swift
- BridgeStateFile.swift
- CHHotplugProvider.swift
- CHInstanceExtension.swift
- CHInterface.swift
- CHProcess.swift
- CHVirtualMachineInstance.swift
- CHVirtualMachineManager.swift
- Container.swift
- ContainerManager.swift
- ContainerStatistics.swift
- DNSConfiguration.swift
- ExitStatus.swift
- FileMount.swift
- Hash.swift
- HostDefaultRoute.swift
- HostsConfiguration.swift
- HotplugProvider.swift
- Interface.swift
- IptablesRules.swift
- Kernel+Commandline.swift
- Kernel.swift
- LinuxBridgedNetwork.swift
- LinuxContainer.swift
- LinuxPod.swift
- LinuxProcess.swift
- LinuxProcessConfiguration.swift
- Mount+CH.swift
- Mount.swift
- NATInterface.swift
- NATNetworkInterface.swift
- Network.swift
- SandboxOverrides.swift
- Signal.swift
- SystemPlatform.swift
- TAPDevice.swift
- TimeSyncer.swift
- UnixSocketConfiguration.swift
- UnixSocketRelay.swift
- UnixSocketRelayManager.swift
- VirtiofsdProcess.swift
- VirtualMachineAgent+Additions.swift
- VirtualMachineAgent+Interface.swift
- VirtualMachineAgent.swift
- VirtualMachineInstance.swift
- VirtualMachineManager.swift
- VMConfiguration.swift
- Vminitd+Rosetta.swift
- Vminitd+SocketRelay.swift
- Vminitd.swift
- VmnetNetwork.swift
- Vsock+Linux.swift
- VsockListener.swift
- VZVirtualMachine+Helpers.swift
- VZVirtualMachineInstance.swift
- VZVirtualMachineManager.swift
- archive.h
- archive_bridge.h
- archive_entry.h
- archive_swift_bridge.c
- COPYING
- ArchiveError.swift
- ArchiveReader.swift
- ArchiveWriter.swift
- ArchiveWriterConfiguration.swift
- TempDir.swift
- WriteEntry.swift
- ContainerizationError.swift
- ext4.md
- EXT4+Extensions.swift
- EXT4+FileTree.swift
- EXT4+Formatter.swift
- EXT4+Journal.swift
- EXT4+Ptr.swift
- EXT4+Reader.swift
- EXT4+Types.swift
- EXT4+Xattrs.swift
- EXT4.swift
- EXT4Reader+Export.swift
- EXT4Reader+IO.swift
- FilePath+Extensions.swift
- FileTimestamps.swift
- Formatter+Unpack.swift
- Integer+Extensions.swift
- README.md
- UnsafeLittleEndianBytes.swift
- AddressAllocator.swift
- AddressError.swift
- AsyncLock.swift
- AsyncMutex.swift
- CIDR.swift
- CIDRv4.swift
- CIDRv6.swift
- FileManager+Temporary.swift
- IndexedAddressAllocator.swift
- IPAddress.swift
- IPv4Address.swift
- IPv6Address+Parse.swift
- IPv6Address.swift
- MACAddress.swift
- NetworkAddress+Allocator.swift
- NetworkConfiguration.swift
- Prefix.swift
- ProgressEvent.swift
- ProxyUtils.swift
- RotatingAddressAllocator.swift
- Timeout.swift
- TLSUtils.swift
- UInt8+DataBinding.swift
- ReadStream.swift
- NetlinkSession.swift
- NetlinkSocket.swift
- Types.swift
- Authentication.swift
- KeychainHelper.swift
- LocalOCILayoutClient.swift
- RegistryClient+Catalog.swift
- RegistryClient+Error.swift
- RegistryClient+Fetch.swift
- RegistryClient+Push.swift
- RegistryClient+Referrers.swift
- RegistryClient+Token.swift
- RegistryClient.swift
- AsyncTypes.swift
- Content.swift
- ContentStoreProtocol.swift
- ContentWriter.swift
- LocalContent.swift
- LocalContentStore.swift
- SHA256+Extensions.swift
- String+Extension.swift
- URL+Extensions.swift
- AnnotationKeys.swift
- Bundle.swift
- Descriptor.swift
- FileManager+Size.swift
- ImageConfig.swift
- Index.swift
- Manifest.swift
- MediaType.swift
- Platform.swift
- Reference.swift
- Spec+Redaction.swift
- Spec.swift
- State.swift
- Version.swift
- KeychainQuery.swift
- RegistryInfo.swift
- Binfmt.swift
- Capabilities.swift
- Epoll.swift
- Mount.swift
- BidirectionalRelay.swift
- Socket.swift
- SocketType.swift
- UnixType.swift
- VsockType.swift
- AsyncSignalHandler.swift
- BinaryInteger+Extensions.swift
- Command.swift
- File.swift
- FileDescriptorOps.swift
- FilePathOps.swift
- Path.swift
- Pipe+Close.swift
- POSIXError+Helpers.swift
- README.md
- Reaper.swift
- Stat.swift
- Syscall.swift
- Sysctl.swift
- Terminal.swift
- URL+Extensions.swift
- User.swift
- capability.h
- cz_tap.h
- exec_command.h
- linux_shim.h
- openat2.h
- prctl.h
- socket_helpers.h
- vsock.h
- capability.c
- cz_tap.c
- exec_command.c
- openat2.c
- prctl.c
- socket_helpers.c
- vsock.c
- ContainerTests.swift
- NBDServer.swift
- PodTests.swift
- PodVolumeTests.swift
- Suite.swift
- ClientTests.swift
- ErrorsTests.swift
- StubHTTPServer.swift
- TypesTests.swift
- test.tar.zst
- ArchiveReaderTests.swift
- ArchiveTests.swift
- 48a06049d3738991b011ca8b12473d712b7c40666a1462118dae3c403676afc2
- 4f4fb700ef54461cfa02571ae0db9a0dc1e0cdb5577484a6d75e68dc38e8acc1
- 8e2eb240a6cd7be1a0d308125afe0060b020e89275ced2e729eda7d4eeff62a2
- ad59e9f71edceca7b1ac7c642410858489b743c97233b0a26a5e2098b1443762
- c6b39de5b33961661dc939b997cc1d30cda01e38005a6c6625fd9c7e748bab44
- TestEXT4ExtendedAttributes.swift
- TestEXT4Format+Create.swift
- TestEXT4Format+Link.swift
- TestEXT4Format+Unlink.swift
- TestEXT4Format.swift
- TestEXT4Journal.swift
- TestEXT4Reader+IO.swift
- TestEXT4Unpacker.swift
- TestFormatterUnpack.swift
- AsyncLockTests.swift
- AsyncMutexTests.swift
- ProxyUtilsTests.swift
- TestCIDR.swift
- TestIPAddress.swift
- TestIPv4Address.swift
- TestIPv6Address+Parse.swift
- TestIPv6Address.swift
- TestIPv6IPv4Parsing.swift
- TestMACAddress.swift
- TestNetworkAddress+Allocator.swift
- TestPrefix.swift
- TestTimeout.swift
- UInt8+DataBindingTest.swift
- MockNetlinkSocket.swift
- NetlinkSessionTest.swift
- TypesTest.swift
- AuthChallengeTests.swift
- ContentWriterTests.swift
- LocalContentStoreTests.swift
- OCIImageTests.swift
- OCIPlatformTests.swift
- OCISpecTests.swift
- ReferenceTests.swift
- RegistryClientTests.swift
- SpecRedactionTests.swift
- BidirectionalRelayTests.swift
- EpollTests.swift
- FileDescriptorOpsTests.swift
- FilePathOpsTests.swift
- IgnoreSIGPIPE.swift
- KeychainQueryTests.swift
- SocketTests.swift
- UserTests.swift
- scratch.tar
- scratch_no_annotations.tar
- ContainsAuth.swift
- ExportOperationTests.swift
- EXT4UnpackerJournalTests.swift
- HeaderScanTimingTests.swift
- ImageStoreImagePullTests.swift
- ImageStoreTests.swift
- AllocatorTests.swift
- BridgeStateFileTests.swift
- CHInterfaceTests.swift
- ContainerManagerTests.swift
- DNSTests.swift
- HashTests.swift
- HostDefaultRouteTests.swift
- HostsTests.swift
- ImageTests.swift
- InterfaceTests.swift
- KernelTests.swift
- LinuxContainerTests.swift
- MountCHTests.swift
- MountTests.swift
- TAPNameDerivationTests.swift
- Dockerfile
- Dockerfile
- devcontainer.json
- Dockerfile
- Cgroup2Manager.swift
- version.h
- version.c
- syscall.h
- syscall.c
- Console.swift
- ExecCommand.swift
- Mount.swift
- RunCommand.swift
- vmexec.swift
- Application.swift
- ConsoleSocket.swift
- Runc.swift
- AgentCommand.swift
- CommandRunner.swift
- ContainerProcess.swift
- HostStdio.swift
- InitCommand.swift
- IOCloser+Extensions.swift
- IOCloser.swift
- IOPair.swift
- Logging.swift
- ManagedContainer.swift
- ManagedProcess.swift
- MemoryMonitor.swift
- OSFile+Splice.swift
- OSFile.swift
- PauseCommand.swift
- ProcessSupervisor.swift
- RuncProcess.swift
- Server+GRPC.swift
- Server.swift
- StandardIO.swift
- TerminalIO.swift
- VsockProxy.swift
- Makefile
- Package.resolved
- Package.swift
- .gitignore
- .spi.yml
- .swift-format
- .swift-format-nolint
- .swift-version
- CLAUDE.md
- CONTRIBUTING.md
- LICENSE
- licenserc.toml
- MAINTAINERS.txt
- Makefile
- Package.resolved
- Package.swift
- Protobuf.Makefile
- README.md
- SECURITY.md
# Installation Guide
swift- macOS 26
- Xcode 26
- Apple container CLI latest
- KVM (Linux Backend)
- cloud-hypervisor & virtiofsd (Linux Backend)
Setup Steps
sudo xcode-select -s <PATH_TO_XCODE>
Set the active developer directory to Xcode.
container --version
Verify that the Apple container CLI is installed on PATH.
make fetch-default-kernel
Fetch the default Linux kernel required for testing.
make all
Build Containerization from sources.
make test integration
Run basic and integration tests.
Key Commands
make all
Builds all project sources.
make test
Runs the unit tests.
make integration
Runs the integration tests.
make fetch-default-kernel
Fetches the default VM kernel.
make protos
Regenerates RPC interfaces from protobuf files.
make docs
Generates API documentation.
make serve-docs
Serves the generated documentation locally.
make pre-commit
Installs the pre-commit hook for formatting and license headers.
# Use via CDN
jsDelivrjsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.
Command Glossary
Commands referenced in this DOCs, explained below.
git commit
View Details ▼
git commit
Commit files to the repository.
git commit
Open an editor to write a message and commit staged files to the repository:
git commit {{[-m|--message]}} "{{message}}"
Commit staged files to the repository with the specified message:
git commit {{[-F|--file]}} {{path/to/commit_message_file}}
Commit staged files with a message read from a file:
container
View Details ▼
container
Create and run Linux containers as lightweight virtual machines on macOS.
container system start
Start the container services (required before running containers):
container run --rm {{[-it|--interactive --tty]}} {{image}} {{sh}}
Run a container from an image interactively and remove it after it exits:
container run {{[-d|--detach]}} --name {{container_name}} {{[-p|--publish]}} {{8080:80}} {{image}}
Run a container in the background with a name and a published port:
xcode-select
View Details ▼
xcode-select
Switch between different versions of Xcode and the included developer tools.
Also used to update the path to Xcode if it is moved after installation.
xcode-select --install
Install Xcode's command-line tools:
xcode-select --switch {{path/to/Xcode.app/Contents/Developer}}
Select a given path as the active developer directory:
xcode-select --switch {{path/to/Xcode_file.app}}
Select a given Xcode instance and use its developer directory as the active one:
