Host connection#1078

JaewonHur · 2026-01-22T23:06:59Z

This PR enables connecting host's localhost port from container (#346).

It adds an option --localhost <localhost> to DNS create command, after which the packets heading ip address in container are redirected to localhost in host machine. Packet filter rule is added and deleted along with the creation and deletion of localhost domain.

Type of Change

Bug fix
New feature
Breaking change
Documentation update

Motivation and Context

Now users can access host's localhost services from container.

Testing

Tested locally
Added/updated tests
Added/updated docs

Realhost DNS resolver returns (fake) host ip address, packets to which are redirected to localhost (in the host). This enables the containers to access host services running on an internal port.

Updating packet filter rule requires sudo. However, running this command in sudo change UserDefaults of root, not original user's. Thus, I apply hacky way to revert uid to original one after updating packet filter rule.

When localhost is geven, new packet filter rule is created.

Create one new line of pf rule for each DNS create (which is commented by domain name), and remove each line on DNS deletion.

Localhost DNS handler monitors resolvers directory and sync internal DNS on every update.

Would be better to refactor resolver.deleteDomain later. Maybe move PacketFilter under the HostDNSResolver?

jglogan · 2026-01-23T19:54:54Z

Sources/ContainerCommands/System/DNS/DNSCreate.swift

+                    throw error
+                }
+            }
+            print(domainName)


Suggested change

print(domainName)

// Output the created resource ID after domain (and optional packet filter) configurations exist.

// Just provide diagnostic messages for failed service restarts.

print(domainName)

What do you mean by resource ID? Is it in the context of ManagedResource?

Yes but you suggest an interesting point. When we implement the ManagedResource stuff and if we did make domains a managed resource, the domain name property might be independent of its resource ID.

That's something for another PR though, the comment will be helpful to someone who's looking at the code for the first time.

Yes, once we use resource ID, we should update this to use resource ID also.

jglogan · 2026-01-23T19:57:30Z

Sources/ContainerCommands/System/DNS/DNSDelete.swift

            do {
-                try resolver.deleteDomain(name: domainName)
-                print(domainName)
+                localhostIP = try resolver.deleteDomain(name: domainName)


As we do the managed resource refactoring, let's plan to update the domain code to use the managed resource protocol, and then we'll use more conventional semantics for DELETE.

No need for changes in this PR.

jglogan · 2026-01-23T19:59:33Z

Sources/ContainerCommands/System/DNS/DNSDelete.swift

+            let pf = PacketFilter()
+            try pf.removeRedirectRule(from: localhostIP, to: try! IPAddress("127.0.0.1"), domain: domainName)
+
+            do {


The DNS manager makes it the responsibility of the caller to perform the reinitialize side effects for both create and delete.

For the packet filter, which is it the responsibility of the caller for create, and the callee for delete?

Packet filter the same, it is the responsibility of caller to reinitialize for both create and delete.

jglogan · 2026-01-23T20:04:33Z

Tests/ContainerAPIClientTests/HostDNSResolverTest.swift

        let resolver = HostDNSResolver(configURL: tempURL)
        try resolver.createDomain(name: "foo.bar")
-        try resolver.deleteDomain(name: "foo.bar")
+        _ = try resolver.deleteDomain(name: "foo.bar")


Why not check the output (did you check it in at least one test?)

Added test.

jglogan · 2026-01-23T20:08:04Z

Tests/ContainerAPIClientTests/PacketFilterTest.swift

use #expect(throws: Error) { ... } or

expect { ... } throws: { error in ... }

docs/how-to.md

jglogan · 2026-01-23T20:17:09Z

Sources/Helpers/APIServer/LocalhostDNSHandler.swift

Look at the corresponding code in the ContainerDNSHandler regarding AAAA requests. Should we reply with NODATA if we there's an IPv4 address but no IPv6 address?

jglogan · 2026-01-23T20:20:09Z

Sources/Services/ContainerAPIService/Client/PacketFilter.swift

+        try lines.joined(separator: "\n").write(toFile: anchorURL.path, atomically: true, encoding: .utf8)
+    }
+
+    public func removeRedirectRule(from: IPAddress, to: IPAddress, domain: String) throws {


What happens if I create two localhost domains that use the same IP address?

Do we maintain the rules separately?

If so, does the packet filtering work ok with the redundant rules?

If we use one rule, what happens if we delete one of the domains?

One pf rule pairs with one domain.

If two localhost domains with the same IP address are created, two pf rules are created as well.
PF follows the last one if it encounters multiple conflicting rules.
However, in this case, two pf rules are same, so I guess no problem.

If we delete one of the domain then, still the pf rule for other one remains.

Co-authored-by: J Logan <sgtbakerrahulnet@yahoo.com>

JaewonHur · 2026-01-23T21:54:23Z

Tests/ContainerAPIClientTests/PacketFilterTest.swift

-        let isAdmin = getuid() == 0
        let pf = PacketFilter()
-        do {
+        #expect(throws: ContainerizationError.self) {


Not sure it's correct update..

- Closes apple#346. - This PR enables connecting host's localhost ports from containers. - It adds an option `--localhost <localhost>` to DNS create command, after which the packets heading ip address in container are redirected to localhost in host machine. Packet filter rule is added and deleted along with the creation and deletion of localhost domain.

commit a65c6f4 Merge: 9d32bc5 ce1b629 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Tue Feb 3 20:08:38 2026 -0800 Merge branch 'apple:main' into main commit ce1b629 Author: Manoj Mahapatra <mahaplipsa@gmail.com> Date: Tue Feb 3 13:43:07 2026 -0800 [Docs] Fix typo in BUILDING.md: launchd -> launchctl (apple#1146) ## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Breaking change - [x] Documentation update ## Motivation and Context The debug instructions in `BUILDING.md` incorrectly reference launchd list instead of `launchctl` list. `launchd` is the daemon itself and cannot be invoked directly. ## Testing - [ ] Tested locally - [ ] Added/updated tests - [x] Added/updated docs commit 3e49dce Author: Danny Canter <danny_canter@apple.com> Date: Tue Feb 3 00:45:01 2026 -0800 Add in missing rlimits (apple#1140) Containerization didn't have these defined until a recent tag. commit c4c2e85 Author: J Logan <john_logan@apple.com> Date: Tue Feb 3 00:27:09 2026 -0800 Upgrade kernel to Kata 3.26.0. (apple#1134) - Upgrade to containerization 0.24.5 to pick up zstd decompression enhancement. - Closes apple#767. - Closes apple#988. - Closes apple#1132. - Requires apple/containerization#508. commit 5c86337 Author: William Laverty <developer@william-laverty.com> Date: Mon Feb 2 13:57:59 2026 -0800 Add explanatory message before admin password prompt in uninstall script (apple#1118) - Added message: "This script requires an administrator password to remove the application files from system directories." - Fixes apple#1111 commit 7da25e1 Author: Danny Canter <danny_canter@apple.com> Date: Mon Feb 2 13:35:02 2026 -0800 Deps: Bump Containerization to 0.24.0 (apple#1127) Brings in some rlimit bumps/adjustments commit 7dfe27d Author: Danny Canter <danny_canter@apple.com> Date: Mon Feb 2 13:30:19 2026 -0800 CLI: Add support for rlimits (apple#1129) Closes apple#1097. commit b3b5c3e Author: J Logan <john_logan@apple.com> Date: Mon Feb 2 12:24:27 2026 -0800 Use labels instead of id to discriminate the builtin network. (apple#1123) - Closes apple#1122. - Adds placeholder ManagedResource and unit tests. Nothing is using these yet. - Adds system-defined resource labels for owning plugin and resource role. The system discriminates the builtin network using role "builtin". - Adds builtin role when creating builtin network at startup, and ensures that a preexisting network with ID "default" gets updated with the role label. - Replace all network ID checks for "default" with the builtin role check. - Adds "builder" role to builder VM. ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Role and owner labels should make cross-cutting resource policy easier to implement. ## Testing - [x] Tested locally - [x] Added/updated tests - [ ] Added/updated docs commit 1dae1cd Author: w-ferg <43309695+w-ferg@users.noreply.github.com> Date: Sun Feb 1 18:14:41 2026 -0500 Fix pfctl executable path in PacketFilter DNS reload (apple#1128) ## Summary The `reload()` method in `PacketFilter.swift` references `/sbin/reloadProcess` (the local variable name) instead of `/sbin/pfctl`. This causes all DNS create and delete operations to fail: ``` Error: internalError: "pfctl reload exec failed: "Error Domain=NSCocoaErrorDomain Code=4 "The file "reloadProcess" doesn't exist."" ``` ## Fix One-line change: `/sbin/reloadProcess` → `/sbin/pfctl` ## Testing Verified on macOS 26 (Tahoe) with Apple Silicon: - `sudo container system dns create test.sdc.internal --localhost 203.0.113.1` succeeds without error - Container can resolve and reach host services through the DNS redirect commit 113a6ec Author: Ronit Sabhaya <ronitsabhaya75@gmail.com> Date: Fri Jan 30 21:54:57 2026 -0600 Fix file descriptor leak in DirectoryWatcher (apple#1104) - `DirectoryWatcher` opens file descriptors for monitoring directories but never closes them, causing a file descriptor leak. - Adds `setCancelHandler` to properly close file descriptors when the `DispatchSource` is cancelled. Signed-off-by: Ronit Sabhaya <ronitsabhaya75@gmail.com> commit 72f04b6 Author: Saehej Kang <saehej.kang@gmail.com> Date: Fri Jan 30 19:10:03 2026 -0800 [docs]: update steps on building with containerization project (apple#1116) - Closes apple#1095 - Just added a few more details about how to build with the local `containerization` dependency. commit 3a0ad58 Author: Raj <rajaryan_singh@apple.com> Date: Fri Jan 30 16:17:43 2026 -0800 Add resource.role label to builder container (apple#1120) Add resource.role label to builder container commit 1c01d0c Author: J Logan <john_logan@apple.com> Date: Fri Jan 30 11:07:49 2026 -0800 Update to kata 3.20.0 kernel. (apple#1114) - Closes apple#1113. - This is the newest we can do until we address apple#767. - Slight change to PacketFilter error handling so unit tests work more reliably. - Try making CLINetworkTests serialized to see if parallel execution is causing flakes. commit 3f2060e Author: Danny Canter <danny_canter@apple.com> Date: Thu Jan 29 18:25:48 2026 -0800 DirectoryWatcher: Small adjustments (apple#1112) - Have the handler throw - Log the failure at error level commit 0a7fb07 Author: Danny Canter <danny_canter@apple.com> Date: Thu Jan 29 14:21:12 2026 -0800 Set mtu to old Containerization default (apple#1110) The old mtu default in containerization was 1280 to account for some alpine/musl images that have issues with 1500. This changed in the last couple tags to be modifiable, but the new default is the standard 1500. Ideally we eventually allow supplying the mtu to be used when you create a network (or possibly a container creation setting), but for now just default in here back to what CZ used to use. commit 0bceb23 Author: Aditya Ramani <a_ramani@apple.com> Date: Thu Jan 29 12:08:42 2026 +0900 Bump to use containerization 0.23.2 (apple#1106) Updating the package dependency on apple/containerization to pick up bug fixes Signed-off-by: Aditya Ramani <a_ramani@apple.com> Co-authored-by: J Logan <john_logan@apple.com> commit d762fe5 Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Wed Jan 28 18:22:33 2026 -0800 Launch a service with waitForDebugger if specified (apple#1101) This PR enables launching a service with `waitForDebugger` flag if the service label matches a given env variable `CONTAINER_DEBUG`. commit 4f93e3e Author: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed Jan 28 18:21:08 2026 -0800 ci: bump actions/checkout from 6.0.1 to 6.0.2 in the github-actions group (apple#1100) - Updates `actions/checkout` from 6.0.1 to 6.0.2 Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> commit 371db6d Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Wed Jan 28 17:17:08 2026 -0800 Fix testExecOnExitingContainer (apple#1107) Check the container remains only, not its status as the status might not have been updated at the time checking. commit d872270 Author: J Logan <john_logan@apple.com> Date: Wed Jan 28 09:04:58 2026 -0800 Removes ArgumentParser import from NetworkMode. (apple#1102) - ContainerResources shouldn't need to know anything about CLI stuff. - Move ExpressibleByArgument protocol conformance to an extension in the package where it's needed. commit 3abf81f Author: Saehej Kang <saehej.kang@gmail.com> Date: Tue Jan 27 20:00:43 2026 -0800 [image-list]: Add full size field to json output (apple#1098) - Refer to apple#862 - Updated `SIZE` field to `FULL SIZE`, as it seemed more appropriate so it does not get mixed up with the `descriptor size` field - Closes apple#860 commit 24cbed5 Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Wed Jan 28 06:55:49 2026 +0800 Implement container prune (apple#904) - Fixed apple#892. - By contrast with `rm`, `prune` should display the amount of reclaimed storage, so added code to retrieve it. Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com> commit a57527e Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Tue Jan 27 11:15:22 2026 -0800 Refactor container lifecycle functions to perform scoped rollback on failure (apple#1080) - Closes apple#977. - Closes apple#1058. - Prevents unexpected removal of containers on bootstrapping and starting failures, by reorganizing error handling for container `run`, `start`, and `exec` so that error handling only unwinds that which was done in the current scope. - Relies on apple/containerization#495. commit 6244129 Author: c <claudeaceae@icloud.com> Date: Mon Jan 26 23:30:45 2026 -0500 Fix grammar in BUILDING.md (apple#984) - Fixes a grammar error in the local Containerization development instructions. commit 9d4cded Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Mon Jan 26 19:35:41 2026 -0800 Isolated network (apple#1079) - Closes apple#1037. - Adds a `--mode` flag that has `nat` and `hostOnly` options. The host-only option selects the vmnet host-only mode, where containers attached to the network can reach each other and the host, but not external systems. commit 033c999 Author: J Logan <john_logan@apple.com> Date: Mon Jan 26 14:07:00 2026 -0800 Make TerminalProgress a library. (apple#1093) - Closes apple#1092. - Allows 3rd party CLI plugins to use the progress indicator. commit b371aee Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Tue Jan 27 05:07:05 2026 +0800 Feat: container image delete force option (apple#1096) - Fixed apple#1087 Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com> commit ed1185d Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Fri Jan 23 17:59:28 2026 -0800 Container-to-host networking. (apple#1078) - Closes apple#346. - This PR enables connecting host's localhost ports from containers. - It adds an option `--localhost <localhost>` to DNS create command, after which the packets heading ip address in container are redirected to localhost in host machine. Packet filter rule is added and deleted along with the creation and deletion of localhost domain. commit 14c279f Author: Patrick Linnane <patrick@linnane.io> Date: Fri Jan 23 17:56:35 2026 -0800 Add option to stop services in all launchd domains (apple#1077) - Services started from Terminal run in the `gui/$uid` launchd domain. When `ensure-container-stopped.sh` runs from a different context, `launchctl managername` may return a different domain, causing the script to check the wrong domain and miss running services. I noticed this after upgrading `container` via Homebrew. - Introduces a getopt option `-a` that allows booting out all domains explicitly. Also adds `-h` for a usage message. Signed-off-by: Patrick Linnane <patrick@linnane.io> commit 751c1fc Author: Stanislav Antonichev <cympak2@users.noreply.github.com> Date: Fri Jan 23 23:01:26 2026 +0200 Add --dns support to build command for custom DNS resolution (apple#1067) This change adds --dns parameter support to the build command, matching the existing functionality in the run command. This allows users to specify custom DNS nameservers (like Google DNS 8.8.8.8) when building container images, which is essential when the host machine uses a local DNS resolver (e.g., 127.0.0.2) that doesn't work inside containers. Changes: - Added --dns option to BuildCommand to accept DNS nameserver IP addresses - Modified build logic to detect DNS configuration changes and recreate the builder container when DNS settings differ - Passed DNS configuration to BuilderStart.start() method - Updated builder container creation to use specified DNS nameservers or fall back to network gateway ## Type of Change - [ ] Bug fix - [X] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context This change adds --dns parameter support to the build command, matching the existing functionality in the run command. This allows users to specify custom DNS nameservers (like Google DNS 8.8.8.8) when building container images, which is essential when the host machine uses a local DNS resolver (e.g., 127.0.0.2) that doesn't work inside containers. ## Testing - [X] Tested locally - [ ] Added/updated tests - [ ] Added/updated docs --------- Co-authored-by: J Logan <sgtbakerrahulnet@yahoo.com> commit 55f2112 Author: J Logan <john_logan@apple.com> Date: Fri Jan 23 11:35:10 2026 -0800 Place image store data correctly for app-root path. (apple#1085) - Closes apple#1084. commit 5746ec3 Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Sat Jan 24 03:32:59 2026 +0800 Fix: prevent delete default network (apple#1083) - Fixed apple#1073 - Move the conditional check to the front; there's no need to check for a default network after filtering. Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com> commit 9d32bc5 Merge: a2b4486 69445b9 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Mon Jan 19 19:20:12 2026 -0800 Merge branch 'apple:main' into main commit a2b4486 Merge: 27a94a0 bfc5ca9 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Fri Oct 3 23:03:02 2025 -0700 Merge branch 'apple:main' into main commit 27a94a0 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Thu Sep 18 17:07:12 2025 -0700 chore(fmt): auto-format before push commit 4a4d0a9 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Thu Sep 18 17:07:06 2025 -0700 Update PropertySet.swift commit 665d813 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Thu Sep 18 17:02:09 2025 -0700 Update PropertySet.swift commit 01a474e Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Thu Sep 18 16:57:41 2025 -0700 chore(fmt): auto-format before push commit e7c68b5 Author: Morris Richman <81453549+Mcrich23@users.noreply.github.com> Date: Thu Sep 18 16:57:01 2025 -0700 Update SystemProperty.swift

commit c791052 Author: Aditya Ramani <a_ramani@apple.com> Date: Wed Feb 18 07:43:56 2026 +0530 Add init methods for all the members of the Flags type (apple#1203) ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Authors of CLI plugins for container will be able to reuse the container flags defined in the CLI package, instead of having to duplicate them in their project ## Testing - [ ] Tested locally - [ ] Added/updated tests - [ ] Added/updated docs commit dfac83d Author: Danny Canter <danny_canter@apple.com> Date: Tue Feb 17 16:54:44 2026 -0800 ContainerService: Add minimum memory amount validation (apple#1208) Closes apple#1202 Today it's possible to pass a memory amount that very easily will cause the container's VM to not be able to boot. We should protect against this to avoid weird hangs/error messages. I could be convinced that a limit should be in Containerization as well, but I think having one in the daemon is a decent idea regardless. commit 5385a5c Author: Kathryn Baldauf <k_baldauf@apple.com> Date: Tue Feb 17 15:08:32 2026 -0800 Support using multiple different network plugins (apple#1151) ## Type of Change - [x] New feature - [x] Breaking change ## Motivation and Context We want to be able to support using multiple network plugins during `container`'s lifetime. This additionally means needing to pick an interface strategy to interpret a network attachment based on what network plugin was used to create that attachment. This PR will potentially replace apple#1081. Followups: - doc updates to include the ability to specify plugin in the network creation cli ## Testing - [x] Tested locally - [x] Added/updated tests commit 7476743 Author: AJ Emory <239216119+ajemory@users.noreply.github.com> Date: Fri Feb 13 19:27:32 2026 -0800 feat: Moving bundle creation from ContainerService to SandboxService (apple#1076) ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Closes apple#1046 -- Right now we're creating container bundles in ContainersService. Move this to the SandboxService to make it easier to support different container bundle types. ## Testing - [x] Tested locally - [x] Added/updated tests - [ ] Added/updated docs commit 4c800db Author: J Logan <john_logan@apple.com> Date: Fri Feb 13 10:51:27 2026 -0800 Fix persistent CI failures. (apple#1205) ## Type of Change - [x] Bug fix - [ ] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context - CI build is failing because runners don't have an /etc/resolver directory, causing the directory monitor to fail. This occurs while the install-kernel make target is running, so it appears that kernel download is failing when it's just that the API server is dying. Created apple#1207 for the issue. - Fixing the initial scan for the directory just moves the problem to the filesystem watch loop, likely because we're not testing the result of `open()` for errors. - Right now the priority is getting CI running and PRs merged, so just commenting out the realhost DNS server setup. - Also seeing that under some conditions it can take quite a while for launchd to start the helper for the default network (8 seconds or more). With the 10 second health check timeout after API server registration, this means that some CI runs can exhibit this failure mode. Added a `--timeout` option to SystemStart and set a 60 second timeout for install-kernel and integration Makefile targets. - Fixed a bug where `--debug` was being placed in the wrong location in the api server startup args. - Disabled all network CLI tests due to container bootstrap errors when trying to run the container immediately after creating the network. The slow network helper launch could be the reason behind the failures that drove us to serialize these tests. Filed apple#1206 for this issue. ## Testing - [x] Tested locally - [ ] Added/updated tests - [ ] Added/updated docs commit f7d00aa Author: Danny Canter <danny_canter@apple.com> Date: Wed Feb 11 15:09:21 2026 -0800 APIServer: Add support for filtering to list rpc (apple#1175) This is not intended to be used to support `--filter` or similar on the CLIs list yet, it's solely to clean up our rather awkward use of `ContainerClient.list()` today in the CLI. The list RPC simply returns all of the containers we have created. Because of this, for a LOT of our commands we filter to what we need client side, which feels like a waste.. This change introduces a filter struct that we can provide an array of container IDs, labels, and the status of the containers to filter the `list()` output from. This additionally, because it was killing (pun not intended) me and I was already having to change this area for the `list()` additions, changes container kill slightly to return an error if you try and kill a container that doesn't exist. commit c9f81ca Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Wed Feb 11 04:26:33 2026 +0800 Feat: add container registry list (apple#1119) - Requires apple/containerization#502 - Closes apple#1088 --------- Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com> commit cf9b335 Author: Manu Schiller <56154253+manuschillerdev@users.noreply.github.com> Date: Tue Feb 10 03:11:27 2026 +0100 feat: add --init-image flag for specifying custom init filesystem images per VM (apple#937) - Users can now specify an alternate image to use with the `container run ---init-image` flag. commit 474906d Author: Amir Alperin <me@remotecpp.dev> Date: Fri Feb 6 23:38:19 2026 +0200 feat: Add runtime flag to container create and run commands (apple#1049) (apple#1109) ## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Fixes apple#1049 - Add --runtime option for Flags.Management - Apply runtime handler in containerConfigFromFlags - Update command-reference.md doc ## Testing - [x] Tested locally - [ ] Added/updated tests - [ ] Added/updated docs Co-authored-by: J Logan <john_logan@apple.com> commit 40de343 Author: Dmitry Kovba <dkovba@apple.com> Date: Fri Feb 6 00:41:29 2026 -0800 Fix relative path mount tests (apple#1168) `make test` occasionally fails with: ``` ✘ Test testHostDNSReinitialize() recorded an issue at HostDNSResolverTest.swift:132:45: Expectation failed: (error → Error Domain=NSPOSIXErrorDomain Code=2 "No such file or directory") as? (ContainerizationError → NSError) ✘ Suite HostDNSResolverTest failed after 0.119 seconds with 1 issue. ``` commit aa17d46 Author: Poetry Of Code <101225909+poetryofcode@users.noreply.github.com> Date: Fri Feb 6 03:38:21 2026 -0500 Warn user when a named volume is auto-created (apple#1108) - Implemented the TODO at ContainerAPIService/Client/Utility.swift:358 — warn the user when a named volume is auto-created. - This only triggers for named volumes (not anonymous ones), matching Docker's behavior of informing users about implicit resource creation. Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> commit adb3c44 Author: J Logan <john_logan@apple.com> Date: Thu Feb 5 20:19:13 2026 -0800 Don't enable selinux LSM on boot. (apple#1166) - Closes apple#1150. - The problem seems to be that the selinux label attribute enforcement doesn't play well with overlayfs. - Solution is to set the `lsm` boot line argument. The new value corresponds to what one would see in a Lima VM with Colima. The Kata kernel we use doesn't provide any of those modules, so now if you run `dmesg | grep -i lsm` in a container you will just see: `LSM: initializing lsm=capability` commit fdeb1b1 Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Thu Feb 5 10:59:31 2026 -0800 Add builder tests (apple#1154) - Adds test for apple#1094. - Closes apple#933 (with apple/container-builder-shim#62). - Closes apple#425 (with apple/container-builder-shim#63). commit fabfc55 Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Thu Feb 5 09:53:31 2026 -0800 Send tar hash in the first BuildTransfer packet (apple#1149) Send the hash of entire tar file in the first BuildTransfer packet to prevent container-builder-shim from using stale cached contents. This PR resolves apple#1143. This PR relies on apple/container-builder-shim#64. ## Type of Change - [X] Bug fix - [ ] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Current container-builder-shim uses only first few bytes of tar file as checksum, which leads to the usage of stale cached contents if the change of build context is not included in the first bytes of tar file. ## Testing - [X] Tested locally - [ ] Added/updated tests - [ ] Added/updated docs --------- Co-authored-by: Ronit Sabhaya <ronitsabhaya75@gmail.com> Co-authored-by: J Logan <john_logan@apple.com> commit 6e9b8d7 Author: Danny Canter <danny_canter@apple.com> Date: Thu Feb 5 09:47:20 2026 -0800 CLI: Forego logging errors on multi-container operations (apple#1163) Instead of logging errors, and then additionally throwing an error stating what containers couldn't be stopped/killed/deleted, let's just concatenate the errors and throw the single error. commit d79bc0d Author: Manoj Mahapatra <mahapatra.manoj@hotmail.com> Date: Thu Feb 5 01:16:30 2026 -0800 chore: Replace force-unwrapped String(data:encoding:) with String(decoding:as:) (apple#1164) Use the non-optional String(decoding:as:) initializer for converting JSON-encoded Data to String. This is safe for UTF-8 and eliminates force commit 21dabb7 Author: Saehej Kang <saehej.kang@gmail.com> Date: Thu Feb 5 03:13:36 2026 -0500 [build-command]: Add --pull option for fetching latest image (apple#844) - Closes apple#733. commit 6553f9c Author: Saehej Kang <saehej.kang@gmail.com> Date: Thu Feb 5 01:16:08 2026 -0500 [deps]: bump containerization to 0.25.0 (apple#1161) Co-authored-by: saehejkang <saehej.kang@gmail.com> Co-authored-by: Anthony DePasquale <anthony@depasquale.org> - Bump `containerization` to `0.25.0` - Updates for parameter changes on containerization registry access API. - Updates for change to containerization `cleanUpOrphanedBlobs` function. commit 2d1dd6b Author: Kathryn Baldauf <k_baldauf@apple.com> Date: Wed Feb 4 15:42:29 2026 -0800 Fix file path for the PR number in the PR labeler workflow (apple#1158) ## Type of Change - [x] Bug fix ## Motivation and Context The PR label applier GitHub workflow has been failing for a while. This PR fixes that by correcting the file path we look for when trying to read the PR number. See example failure here https://github.com/apple/container/actions/runs/21691766538/job/62552959972#step:4:23 commit 6451e07 Author: Kathryn Baldauf <k_baldauf@apple.com> Date: Wed Feb 4 14:44:53 2026 -0800 Add debugging to the PR labeler CI flow (apple#1155) ## Type of Change - [x] Bug fix ## Motivation and Context The PR labeler workflow has been failing for a while but it's difficult to know how to fix it since the PR labeler workflow is run from main (aka NOT the current PR branch) for security reasons. Example at https://github.com/apple/container/actions/runs/21690229300/workflow commit 8fdfa29 Author: Danny Canter <danny_canter@apple.com> Date: Wed Feb 4 09:52:09 2026 -0800 CLI: Rework ClientContainer (apple#1139) ClientContainer was honestly extremely awkward. It could only be created by passing either a ContainerConfiguration, or a Snapshot that had to be obtained from calling a static method on the type itself. The type also did not store a connection, so every single method got a new xpc connection to the APIServer. This change aims to rework this type to be just a generic client, that is *not* a client for one specific container, but for any. - Rename to ContainerClient - Have list() return [ContainerSnapshot] - Create a connection in the constructor - Change all the callsites to use the new API - Small, somewhat related, change to logs API in the APIServer. Now that we don't need to call get() to grab a client anymore which was typically what did "does this container exist" logic and gave a nice error message, I added a small check in the APIServer to see if the container exists and return mostly the same error message. commit 23c0ece Author: Danny Canter <danny_canter@apple.com> Date: Wed Feb 4 09:19:50 2026 -0800 CI: Add signed commit check (apple#1152) This requirement of ours often goes unnoticed because nothing yells at you openly about it. Lets fail CI to make it more obvious. commit ce1b629 Author: Manoj Mahapatra <mahaplipsa@gmail.com> Date: Tue Feb 3 13:43:07 2026 -0800 [Docs] Fix typo in BUILDING.md: launchd -> launchctl (apple#1146) ## Type of Change - [ ] Bug fix - [ ] New feature - [ ] Breaking change - [x] Documentation update ## Motivation and Context The debug instructions in `BUILDING.md` incorrectly reference launchd list instead of `launchctl` list. `launchd` is the daemon itself and cannot be invoked directly. ## Testing - [ ] Tested locally - [ ] Added/updated tests - [x] Added/updated docs commit 3e49dce Author: Danny Canter <danny_canter@apple.com> Date: Tue Feb 3 00:45:01 2026 -0800 Add in missing rlimits (apple#1140) Containerization didn't have these defined until a recent tag. commit c4c2e85 Author: J Logan <john_logan@apple.com> Date: Tue Feb 3 00:27:09 2026 -0800 Upgrade kernel to Kata 3.26.0. (apple#1134) - Upgrade to containerization 0.24.5 to pick up zstd decompression enhancement. - Closes apple#767. - Closes apple#988. - Closes apple#1132. - Requires apple/containerization#508. commit 5c86337 Author: William Laverty <developer@william-laverty.com> Date: Mon Feb 2 13:57:59 2026 -0800 Add explanatory message before admin password prompt in uninstall script (apple#1118) - Added message: "This script requires an administrator password to remove the application files from system directories." - Fixes apple#1111 commit 7da25e1 Author: Danny Canter <danny_canter@apple.com> Date: Mon Feb 2 13:35:02 2026 -0800 Deps: Bump Containerization to 0.24.0 (apple#1127) Brings in some rlimit bumps/adjustments commit 7dfe27d Author: Danny Canter <danny_canter@apple.com> Date: Mon Feb 2 13:30:19 2026 -0800 CLI: Add support for rlimits (apple#1129) Closes apple#1097. commit b3b5c3e Author: J Logan <john_logan@apple.com> Date: Mon Feb 2 12:24:27 2026 -0800 Use labels instead of id to discriminate the builtin network. (apple#1123) - Closes apple#1122. - Adds placeholder ManagedResource and unit tests. Nothing is using these yet. - Adds system-defined resource labels for owning plugin and resource role. The system discriminates the builtin network using role "builtin". - Adds builtin role when creating builtin network at startup, and ensures that a preexisting network with ID "default" gets updated with the role label. - Replace all network ID checks for "default" with the builtin role check. - Adds "builder" role to builder VM. ## Type of Change - [ ] Bug fix - [x] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context Role and owner labels should make cross-cutting resource policy easier to implement. ## Testing - [x] Tested locally - [x] Added/updated tests - [ ] Added/updated docs commit 1dae1cd Author: w-ferg <43309695+w-ferg@users.noreply.github.com> Date: Sun Feb 1 18:14:41 2026 -0500 Fix pfctl executable path in PacketFilter DNS reload (apple#1128) ## Summary The `reload()` method in `PacketFilter.swift` references `/sbin/reloadProcess` (the local variable name) instead of `/sbin/pfctl`. This causes all DNS create and delete operations to fail: ``` Error: internalError: "pfctl reload exec failed: "Error Domain=NSCocoaErrorDomain Code=4 "The file "reloadProcess" doesn't exist."" ``` ## Fix One-line change: `/sbin/reloadProcess` → `/sbin/pfctl` ## Testing Verified on macOS 26 (Tahoe) with Apple Silicon: - `sudo container system dns create test.sdc.internal --localhost 203.0.113.1` succeeds without error - Container can resolve and reach host services through the DNS redirect commit 113a6ec Author: Ronit Sabhaya <ronitsabhaya75@gmail.com> Date: Fri Jan 30 21:54:57 2026 -0600 Fix file descriptor leak in DirectoryWatcher (apple#1104) - `DirectoryWatcher` opens file descriptors for monitoring directories but never closes them, causing a file descriptor leak. - Adds `setCancelHandler` to properly close file descriptors when the `DispatchSource` is cancelled. Signed-off-by: Ronit Sabhaya <ronitsabhaya75@gmail.com> commit 72f04b6 Author: Saehej Kang <saehej.kang@gmail.com> Date: Fri Jan 30 19:10:03 2026 -0800 [docs]: update steps on building with containerization project (apple#1116) - Closes apple#1095 - Just added a few more details about how to build with the local `containerization` dependency. commit 3a0ad58 Author: Raj <rajaryan_singh@apple.com> Date: Fri Jan 30 16:17:43 2026 -0800 Add resource.role label to builder container (apple#1120) Add resource.role label to builder container commit 1c01d0c Author: J Logan <john_logan@apple.com> Date: Fri Jan 30 11:07:49 2026 -0800 Update to kata 3.20.0 kernel. (apple#1114) - Closes apple#1113. - This is the newest we can do until we address apple#767. - Slight change to PacketFilter error handling so unit tests work more reliably. - Try making CLINetworkTests serialized to see if parallel execution is causing flakes. commit 3f2060e Author: Danny Canter <danny_canter@apple.com> Date: Thu Jan 29 18:25:48 2026 -0800 DirectoryWatcher: Small adjustments (apple#1112) - Have the handler throw - Log the failure at error level commit 0a7fb07 Author: Danny Canter <danny_canter@apple.com> Date: Thu Jan 29 14:21:12 2026 -0800 Set mtu to old Containerization default (apple#1110) The old mtu default in containerization was 1280 to account for some alpine/musl images that have issues with 1500. This changed in the last couple tags to be modifiable, but the new default is the standard 1500. Ideally we eventually allow supplying the mtu to be used when you create a network (or possibly a container creation setting), but for now just default in here back to what CZ used to use. commit 0bceb23 Author: Aditya Ramani <a_ramani@apple.com> Date: Thu Jan 29 12:08:42 2026 +0900 Bump to use containerization 0.23.2 (apple#1106) Updating the package dependency on apple/containerization to pick up bug fixes Signed-off-by: Aditya Ramani <a_ramani@apple.com> Co-authored-by: J Logan <john_logan@apple.com> commit d762fe5 Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Wed Jan 28 18:22:33 2026 -0800 Launch a service with waitForDebugger if specified (apple#1101) This PR enables launching a service with `waitForDebugger` flag if the service label matches a given env variable `CONTAINER_DEBUG`. commit 4f93e3e Author: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed Jan 28 18:21:08 2026 -0800 ci: bump actions/checkout from 6.0.1 to 6.0.2 in the github-actions group (apple#1100) - Updates `actions/checkout` from 6.0.1 to 6.0.2 Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> commit 371db6d Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Wed Jan 28 17:17:08 2026 -0800 Fix testExecOnExitingContainer (apple#1107) Check the container remains only, not its status as the status might not have been updated at the time checking. commit d872270 Author: J Logan <john_logan@apple.com> Date: Wed Jan 28 09:04:58 2026 -0800 Removes ArgumentParser import from NetworkMode. (apple#1102) - ContainerResources shouldn't need to know anything about CLI stuff. - Move ExpressibleByArgument protocol conformance to an extension in the package where it's needed. commit 3abf81f Author: Saehej Kang <saehej.kang@gmail.com> Date: Tue Jan 27 20:00:43 2026 -0800 [image-list]: Add full size field to json output (apple#1098) - Refer to apple#862 - Updated `SIZE` field to `FULL SIZE`, as it seemed more appropriate so it does not get mixed up with the `descriptor size` field - Closes apple#860 commit 24cbed5 Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Wed Jan 28 06:55:49 2026 +0800 Implement container prune (apple#904) - Fixed apple#892. - By contrast with `rm`, `prune` should display the amount of reclaimed storage, so added code to retrieve it. Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com> commit a57527e Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Tue Jan 27 11:15:22 2026 -0800 Refactor container lifecycle functions to perform scoped rollback on failure (apple#1080) - Closes apple#977. - Closes apple#1058. - Prevents unexpected removal of containers on bootstrapping and starting failures, by reorganizing error handling for container `run`, `start`, and `exec` so that error handling only unwinds that which was done in the current scope. - Relies on apple/containerization#495. commit 6244129 Author: c <claudeaceae@icloud.com> Date: Mon Jan 26 23:30:45 2026 -0500 Fix grammar in BUILDING.md (apple#984) - Fixes a grammar error in the local Containerization development instructions. commit 9d4cded Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Mon Jan 26 19:35:41 2026 -0800 Isolated network (apple#1079) - Closes apple#1037. - Adds a `--mode` flag that has `nat` and `hostOnly` options. The host-only option selects the vmnet host-only mode, where containers attached to the network can reach each other and the host, but not external systems. commit 033c999 Author: J Logan <john_logan@apple.com> Date: Mon Jan 26 14:07:00 2026 -0800 Make TerminalProgress a library. (apple#1093) - Closes apple#1092. - Allows 3rd party CLI plugins to use the progress indicator. commit b371aee Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Tue Jan 27 05:07:05 2026 +0800 Feat: container image delete force option (apple#1096) - Fixed apple#1087 Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com> commit ed1185d Author: jwhur <57657645+JaewonHur@users.noreply.github.com> Date: Fri Jan 23 17:59:28 2026 -0800 Container-to-host networking. (apple#1078) - Closes apple#346. - This PR enables connecting host's localhost ports from containers. - It adds an option `--localhost <localhost>` to DNS create command, after which the packets heading ip address in container are redirected to localhost in host machine. Packet filter rule is added and deleted along with the creation and deletion of localhost domain. commit 14c279f Author: Patrick Linnane <patrick@linnane.io> Date: Fri Jan 23 17:56:35 2026 -0800 Add option to stop services in all launchd domains (apple#1077) - Services started from Terminal run in the `gui/$uid` launchd domain. When `ensure-container-stopped.sh` runs from a different context, `launchctl managername` may return a different domain, causing the script to check the wrong domain and miss running services. I noticed this after upgrading `container` via Homebrew. - Introduces a getopt option `-a` that allows booting out all domains explicitly. Also adds `-h` for a usage message. Signed-off-by: Patrick Linnane <patrick@linnane.io> commit 751c1fc Author: Stanislav Antonichev <cympak2@users.noreply.github.com> Date: Fri Jan 23 23:01:26 2026 +0200 Add --dns support to build command for custom DNS resolution (apple#1067) This change adds --dns parameter support to the build command, matching the existing functionality in the run command. This allows users to specify custom DNS nameservers (like Google DNS 8.8.8.8) when building container images, which is essential when the host machine uses a local DNS resolver (e.g., 127.0.0.2) that doesn't work inside containers. Changes: - Added --dns option to BuildCommand to accept DNS nameserver IP addresses - Modified build logic to detect DNS configuration changes and recreate the builder container when DNS settings differ - Passed DNS configuration to BuilderStart.start() method - Updated builder container creation to use specified DNS nameservers or fall back to network gateway ## Type of Change - [ ] Bug fix - [X] New feature - [ ] Breaking change - [ ] Documentation update ## Motivation and Context This change adds --dns parameter support to the build command, matching the existing functionality in the run command. This allows users to specify custom DNS nameservers (like Google DNS 8.8.8.8) when building container images, which is essential when the host machine uses a local DNS resolver (e.g., 127.0.0.2) that doesn't work inside containers. ## Testing - [X] Tested locally - [ ] Added/updated tests - [ ] Added/updated docs --------- Co-authored-by: J Logan <sgtbakerrahulnet@yahoo.com> commit 55f2112 Author: J Logan <john_logan@apple.com> Date: Fri Jan 23 11:35:10 2026 -0800 Place image store data correctly for app-root path. (apple#1085) - Closes apple#1084. commit 5746ec3 Author: ChengHao Yang <17496418+tico88612@users.noreply.github.com> Date: Sat Jan 24 03:32:59 2026 +0800 Fix: prevent delete default network (apple#1083) - Fixed apple#1073 - Move the conditional check to the front; there's no need to check for a default network after filtering. Signed-off-by: ChengHao Yang <17496418+tico88612@users.noreply.github.com>

JaewonHur added 12 commits January 15, 2026 14:36

Add realhost DNS resolver

c227fd3

Realhost DNS resolver returns (fake) host ip address, packets to which are redirected to localhost (in the host). This enables the containers to access host services running on an internal port.

Update packet filter rule on realhost setting

e15fa7a

Updating packet filter rule requires sudo. However, running this command in sudo change UserDefaults of root, not original user's. Thus, I apply hacky way to revert uid to original one after updating packet filter rule.

Add localhost option to DNS create

098f18c

When localhost is geven, new packet filter rule is created.

Resolve minor comments

8af9d63

Remove realhost from system property

2994e48

Use different localhost ip for DNS create

0b264d7

Delete packet filter rule on DNS delete

08110c7

Create one new line of pf rule for each DNS create (which is commented by domain name), and remove each line on DNS deletion.

Implement LocalhostDNSHandler with DirectoryWatcher

5aff090

Localhost DNS handler monitors resolvers directory and sync internal DNS on every update.

Add PacketFilterTest

ad4cf92

Fix minor issue

83d430e

Move DNS resolver reload above

08d2dc3

Would be better to refactor resolver.deleteDomain later. Maybe move PacketFilter under the HostDNSResolver?

Move stopWatching to deinit

d8291cb

JaewonHur force-pushed the host-connection branch 2 times, most recently from 18fd490 to bd38791 Compare January 23, 2026 17:51

Update documentation

67394aa

JaewonHur force-pushed the host-connection branch from bd38791 to 67394aa Compare January 23, 2026 17:52

jglogan requested changes Jan 23, 2026

View reviewed changes

jglogan reviewed Jan 23, 2026

View reviewed changes

JaewonHur and others added 2 commits January 23, 2026 13:15

Update docs/how-to.md

cbbe91e

Co-authored-by: J Logan <sgtbakerrahulnet@yahoo.com>

Resolve comments

04a7eb0

JaewonHur commented Jan 23, 2026

View reviewed changes

jglogan approved these changes Jan 24, 2026

View reviewed changes

JaewonHur and others added 2 commits January 23, 2026 16:34

Fix testHostDNSCreate

c239480

Merge branch 'main' into host-connection

297ec66

jglogan approved these changes Jan 24, 2026

View reviewed changes

jglogan merged commit ed1185d into apple:main Jan 24, 2026
2 checks passed

jglogan mentioned this pull request Jan 24, 2026

GUI? #1069

Closed

jglogan mentioned this pull request Jan 28, 2026

Fix file descriptor leak in DirectoryWatcher #1104

Merged

7 tasks

BrewTestBot mentioned this pull request Feb 3, 2026

container 0.9.0 Homebrew/homebrew-core#265636

Closed

Conversation

JaewonHur commented Jan 22, 2026

Type of Change

Motivation and Context

Testing

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Comments