[containers]: add system-start flag for auto-start of containers by saehejkang · Pull Request #1201 · apple/container

saehejkang · 2026-02-12T05:52:26Z

Type of Change

Bug fix
New feature
Breaking change
Documentation update

Motivation and Context

Relates to #158

Adds a simple flag that can be set on container create and container run to auto-start any container that is stopped after container system stop.

Testing

Create a container or run a container with the --system-start flag set
Run container ls to see that the flag is enabled
Run container system stop
Run container system start and the logs should output the containers that were started up again
Run container ls to see that the container is running

Tested locally
Added/updated tests
Added/updated docs

saehejkang · 2026-02-12T06:05:44Z

Sources/Services/ContainerAPIService/Client/Flags.swift

+            name: .customLong("systemstart"),
+            help: "Automatically start the container when the container system starts"
+        )
+        public var systemStart: Bool = false


I neglected to use autoStart because containers are automatically spun up with run and create. It will cause confusion, as that is a totally different process from what this flag should inherently be doing.

JaewonHur · 2026-02-13T02:06:22Z

Sources/Services/ContainerAPIService/Server/Containers/ContainersService.swift

            // is also a very simple check and faster than doing an rpc to get the same result.
-            if state.client != nil {
+            // However, if it marked for system-start, continue with bootstrap.
+            if state.client != nil && state.snapshot.createOptions?.systemStart != true {


Could you explain rationale behind this?

Whoops. That was a check I added just in case to test something and I forgot to remove it.

JaewonHur · 2026-02-13T02:08:26Z

Sources/ContainerCommands/System/SystemStart.swift


+            // Start all the containers that have system-start enabled
+            log.info("starting containers", metadata: ["startTimeoutSeconds": "\(Self.startTimeoutSeconds)"])
+            try await startContainers()


This might be invoked before the API server finishes bootstrapping.

Hmmm. Interestingly enough, I tested it by waiting until the API server was bootstrapped/kernel install and the function never got invoked. The logic will need to be updated a tiny bit so this function is invoked correctly.

JaewonHur · 2026-02-13T02:10:09Z

Sources/ContainerCommands/System/SystemStart.swift

+        private func startContainers() async throws {
+            let client = ContainerClient()
+            let containers = try await client.list()
+            let systemStartContainers = containers.filter { $0.createOptions?.systemStart == true && $0.status != .running }


Should be $0.status == .stopped?

either or in this case

JaewonHur · 2026-02-13T02:16:55Z

Sources/ContainerCommands/Container/ContainerList.swift


        private func createHeader() -> [[String]] {
-            [["ID", "IMAGE", "OS", "ARCH", "STATE", "ADDR", "CPUS", "MEMORY", "STARTED"]]
+            [["ID", "IMAGE", "OS", "ARCH", "STATE", "ADDR", "CPUS", "MEMORY", "STARTED", "SYSTEM-START"]]


I'm not sure it's the best to print "SYSTEM-START" here..

I was mulling on the idea of adding this to the print output. I feel users should have the ability to know if a container will be started automatically on system startup. It might be worthwhile adding a --verbose option (like image list), where this field will be added to the output (default output will not included it).

JaewonHur · 2026-02-13T02:25:11Z

Sources/ContainerCommands/System/SystemStart.swift

+        /// Starts all containers that are configured to automatically start on system start.
+        ///
+        /// - Throws: `AggregateError` containing all errors encountered during container startup.
+        private func startContainers() async throws {


We might be able to move starting containers to the API server, near loadAtBoot? Then, we can avoid changing ContainerSnapshot.

I can take a look at this but ContainerSnapshot was changed just so the SYSTEM-START field could be outputted.

Oh got it. We need to change ContainerSnapshot anyway.

NVM this comment, I was testing AI based PR review yesterday and it corrupted my brain :)

saehejkang · 2026-02-13T05:56:00Z

Because these changes need to sort of "simulate" a system stop/start, I am thinking of making the following changes to the Makefile for tests. Thought about this for a while and tried different things, but below is the only solution that I makes sense.

exit_code=0; \
# Run setup tests (create containers with --system-start)
echo "Running setup tests..." ; \
$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestCLICreateCommand || exit_code=1 ; \

# Stop the system
echo "Stopping container system..." ; \
bin/container system stop && sleep 3 && scripts/ensure-container-stopped.sh ; \

# Start the system again
echo "Starting container system..." ; \
bin/container system start $(SYSTEM_START_OPTS) ; \

# Run verification tests (check containers are running)
echo "Running verification tests..." ; \
$(SWIFT) test -c $(BUILD_CONFIGURATION) $(SWIFT_CONFIGURATION) --filter TestSystemStart || exit_code=1 ; \

# Rest of the tests below (omitted for readability)

JaewonHur · 2026-02-13T21:24:37Z

Sources/ContainerResource/Container/ContainerCreateOptions.swift

@@ -16,11 +16,13 @@

 public struct ContainerCreateOptions: Codable, Sendable {


@jglogan @dcantah How do you think merging this into ContainerConfiguration.label?

For now, there's no way to inform the users of this create options.
label might be a good choice to expose it without drastic changing?

JaewonHur · 2026-02-13T21:25:06Z

docs/command-reference.md

 *   `-v, --volume <volume>`: Bind mount a volume into the container
 *   `--virtualization`: Expose virtualization capabilities to the container (requires host and guest support)
 *   `--runtime`: Set the runtime handler for the container (default: container-runtime-linux)
+*   `--systemstart`: Automatically start the container when the container system starts


--system-start would be better.

Agreed. Will make that change before this gets merged.

JaewonHur · 2026-02-13T21:26:08Z

Sources/ContainerCommands/System/SystemStart.swift

+        /// Starts all containers that are configured to automatically start on system start.
+        ///
+        /// - Throws: `AggregateError` containing all errors encountered during container startup.
+        private func startContainers() async throws {


NVM this comment, I was testing AI based PR review yesterday and it corrupted my brain :)

saehejkang · 2026-02-18T02:35:29Z

@JaewonHur Take a look at the comment above and let me know if you see a better way to handle this. I would love to get your input!

JaewonHur · 2026-02-18T06:51:30Z

Sorry for the delay! We are still thinking about how ContainerConfiguration.labels should be used versus ContainerCreateOptions.

Regarding the test, it feels somewhat unusual to me if a single test case is performed by multiple subsequent commands.

How about adding a new (self-contained) test case under Tests/CLITests/Subcommands/System?
There, we can start API server, create system-start container, stop API server, and restart again.

saehejkang · 2026-02-18T07:25:53Z

Sorry for the delay! We are still thinking about how ContainerConfiguration.labels should be used versus ContainerCreateOptions.

All good and no worries.

How about adding a new (self-contained) test case under Tests/CLITests/Subcommands/System?
There, we can start API server, create system-start container, stop API server, and restart again.

That was my initial thought, but I think I was having issues with executing container system start and container system stop there. I don't think the test suites are configured to properly start/stop the system, as that seems to be handled by the install/uninstall scripts (used in the makefile when running integration tests).

I was thinking that since this is the first "feature" that relies on the system, we build out a single new test suite. This test suite will be ran after an intentional system stop/start (using the scripts again in the makefile). Maybe I am not being clear enough, but it is also hard to explain my thought process in a text box lol.

initial passthrough of system start flag for containers

5287d50

saehejkang commented Feb 12, 2026

View reviewed changes

JaewonHur reviewed Feb 13, 2026

View reviewed changes

updates to system start and containers service

7fc8fdc

JaewonHur reviewed Feb 17, 2026

View reviewed changes

		@@ -16,11 +16,13 @@

		public struct ContainerCreateOptions: Codable, Sendable {

Conversation

saehejkang commented Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Type of Change

Motivation and Context

Testing

Uh oh!

saehejkang Feb 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

saehejkang Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

saehejkang Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

saehejkang commented Feb 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

saehejkang commented Feb 18, 2026

Uh oh!

JaewonHur commented Feb 18, 2026

Uh oh!

saehejkang commented Feb 18, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

saehejkang commented Feb 12, 2026 •

edited

Loading

saehejkang Feb 12, 2026 •

edited

Loading

saehejkang Feb 13, 2026 •

edited

Loading

saehejkang Feb 13, 2026 •

edited

Loading

saehejkang commented Feb 13, 2026 •

edited

Loading