Adding apple-container as a new executor

Author: Joon-Klaps

docs/container.md

@@ -4,6 +4,71 @@
 
 Nextflow supports a variety of container runtimes. Containerization allows you to write self-contained and truly reproducible computational pipelines, by packaging the binary dependencies of a script into a standard and portable format that can be executed on any platform that supports a container runtime. Furthermore, the same pipeline can be transparently executed with any of the supported container runtimes, depending on which runtimes are available in the target compute environment.
 
+(container-apple)=
+
+## Apple containers
+
+:::{versionadded} 26.04.0-edge
+:::
+
+[Apple containers](https://github.com/apple/containerization) is a container runtime for Apple Silicon Macs that runs OCI-compatible container images natively using the macOS Virtualization framework. It provides fast, lightweight container execution without requiring Docker Desktop or any third-party virtualization software.
+
+### Prerequisites
+
+Apple containers requires macOS 26 or later and Apple Silicon (M-series chip). Install the `container` CLI tool from Apple and ensure it is available on your `PATH`.
+
+### How it works
+
+To run your pipeline with Apple containers, use the `-with-apple-container` command line option:
+
+```bash
+nextflow run <your script> -with-apple-container [OCI container image]
+```
+
+Alternatively, enable the engine in your configuration file:
+
+```groovy
+process.container = 'ubuntu:22.04'
+apple.enabled = true
+```
+
+Every time a process is executed, Nextflow will wrap it in a `container run` command using the image specified by the `container` directive.
+
+### Architecture and Rosetta
+
+Apple containers runs `linux/arm64` images by default. To run `linux/amd64` images transparently via [Rosetta](https://developer.apple.com/documentation/apple-silicon/about-the-rosetta-translation-environment), set the `arch` directive on the relevant processes:
+
+```groovy
+process {
+    arch = 'x86_64'
+}
+```
+
+Nextflow will automatically add `--platform linux/amd64 --rosetta` to the `container run` command. For pipelines that ship native arm64 images, no `arch` directive is needed.
+
+### Configuration
+
+```groovy
+process.container = 'ubuntu:22.04'
+
+apple {
+    enabled = true
+}
+```
+
+Or use the dedicated `apple_container` executor to make the engine selection explicit:
+
+```groovy
+process {
+    executor  = 'apple_container'
+    container = 'ubuntu:22.04'
+}
+```
+
+### Advanced settings
+
+Apple container advanced configuration settings are described in {ref}`config-apple` section in the Nextflow configuration page.
+
 :::{note}
 When creating a container image to use with Nextflow, make sure that Bash (3.x or later) and `ps` are installed in the image, along with other tools required for collecting metrics (See {ref}`this section <execution-report-tasks>`). Bash should be available on the path `/bin/bash` and it should be the container entrypoint.
 :::

docs/reference/config.md

@@ -480,6 +480,38 @@ The following settings are available:
 `azure.storage.tokenDuration`
 : The duration of the SAS token generated by Nextflow when the `sasToken` option is *not* specified (default: `48h`).
 
+(config-apple)=
+
+## `apple`
+
+The `apple` scope controls how [Apple containers](https://github.com/apple/containerization) are executed by Nextflow.
+
+The following settings are available:
+
+`apple.enabled`
+: Execute tasks with Apple containers (default: `false`).
+
+`apple.engineOptions`
+: Specify additional options supported by the Apple container engine i.e. `container [OPTIONS]`.
+
+`apple.envWhitelist`
+: Comma separated list of environment variable names to be included in the container environment.
+
+`apple.kill`
+: How the container should be stopped. Use `true` to send a SIGTERM (default), `false` to skip, or a signal name e.g. `'SIGKILL'` to use a specific signal.
+
+`apple.registry`
+: The registry from where container images are pulled. It should be only used to specify a private registry server. It should NOT include the protocol prefix i.e. `http://`.
+
+`apple.remove`
+: Clean-up the container after the execution (default: `true`).
+
+`apple.runOptions`
+: Specify extra command line options supported by the `container run` command.
+
+`apple.temp`
+: Mounts a path of your choice as the `/tmp` directory in the container. Use the special value `'auto'` to create a temporary directory each time a container is created.
+
 (config-charliecloud)=
 
 ## `charliecloud`

modules/nextflow/src/main/groovy/nextflow/Session.groovy

@@ -37,6 +37,7 @@ import nextflow.cache.CacheDB
 import nextflow.cache.CacheFactory
 import nextflow.conda.CondaConfig
 import nextflow.config.Manifest
+import nextflow.container.AppleContainerConfig
 import nextflow.container.ApptainerConfig
 import nextflow.container.CharliecloudConfig
 import nextflow.container.ContainerConfig
@@ -1187,6 +1188,7 @@ class Session implements ISession {
             new SingularityConfig(config.singularity as Map ?: Collections.emptyMap()),
             new ApptainerConfig(config.apptainer as Map ?: Collections.emptyMap()),
             new CharliecloudConfig(config.charliecloud as Map ?: Collections.emptyMap()),
+            new AppleContainerConfig(config.apple as Map ?: Collections.emptyMap()),
         ] as List<ContainerConfig>
 
         if( engine ) {

modules/nextflow/src/main/groovy/nextflow/cli/CmdRun.groovy

@@ -198,6 +198,9 @@ class CmdRun extends CmdBase implements HubOptions {
     @Parameter(names = '-with-charliecloud', description = 'Enable process execution in a Charliecloud container runtime')
     def withCharliecloud
 
+    @Parameter(names = '-with-apple-container', description = 'Enable process execution in an Apple container runtime')
+    def withApple
+
     @Parameter(names = '-with-singularity', description = 'Enable process execution in a Singularity container')
     def withSingularity
 

modules/nextflow/src/main/groovy/nextflow/cli/Launcher.groovy

@@ -294,6 +294,10 @@ class Launcher {
                 normalized << '-'
             }
 
+            else if( current == '-with-apple-container' && (i==args.size() || args[i].startsWith('-'))) {
+                normalized << '-'
+            }
+
             else if( current == '-with-conda' && (i==args.size() || args[i].startsWith('-'))) {
                 normalized << '-'
             }

modules/nextflow/src/main/groovy/nextflow/config/ConfigBuilder.groovy

@@ -778,6 +778,10 @@ class ConfigBuilder {
         if( cmdRun.withCharliecloud ) {
             configContainer(config, 'charliecloud', cmdRun.withCharliecloud)
         }
+
+        if( cmdRun.withApple ) {
+            configContainer(config, 'apple', cmdRun.withApple)
+        }
     }
 
     private void configContainer(ConfigObject config, String engine, def cli) {

modules/nextflow/src/main/groovy/nextflow/container/AppleContainerBuilder.groovy

@@ -0,0 +1,178 @@
+/*
+ * Copyright 2013-2026, Seqera Labs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package nextflow.container
+
+import groovy.transform.CompileStatic
+
+/**
+ * Helper methods to handle Apple containers.
+ *
+ * Wraps tasks in {@code container run} commands using the Apple container CLI,
+ * which runs linux/arm64 images natively on Apple Silicon via the Virtualization
+ * framework. For amd64 images, {@code --rosetta} is added automatically.
+ *
+ * @author Joon-Klaps
+ */
+@CompileStatic
+class AppleContainerBuilder extends ContainerBuilder<AppleContainerBuilder> {
+
+    private boolean remove
+
+    private String registry
+
+    private String name
+
+    private String removeCommand
+
+    private String killCommand
+
+    private Object kill = true
+
+    AppleContainerBuilder(String name, AppleContainerConfig config) {
+        this.image = name
+
+        if( config.engineOptions )
+            addEngineOptions(config.engineOptions)
+
+        this.remove = config.remove
+
+        if( config.registry )
+            this.registry = config.registry
+
+        if( config.runOptions )
+            addRunOptions(config.runOptions)
+
+        if( config.temp )
+            this.temp = config.temp
+    }
+
+    AppleContainerBuilder(String name) {
+        this(name, new AppleContainerConfig([:]))
+    }
+
+    @Override
+    AppleContainerBuilder params( Map params ) {
+        if( !params ) return this
+
+        if( params.containsKey('entry') )
+            this.entryPoint = params.entry
+
+        if( params.containsKey('kill') )
+            this.kill = params.kill
+
+        if( params.containsKey('readOnlyInputs') )
+            this.readOnlyInputs = params.readOnlyInputs?.toString() == 'true'
+
+        return this
+    }
+
+    @Override
+    AppleContainerBuilder setName( String name ) {
+        this.name = name
+        return this
+    }
+
+    @Override
+    AppleContainerBuilder build(StringBuilder result) {
+        assert image
+
+        result << 'container '
+
+        if( engineOptions )
+            result << engineOptions.join(' ') << ' '
+
+        result << 'run -i '
+
+        // add the environment
+        appendEnv(result)
+
+        if( temp )
+            result << "-v $temp:/tmp "
+
+        // mount the input folders
+        result << makeVolumes(mounts)
+        result << '-w "$NXF_TASK_WORKDIR" '
+
+        if( entryPoint )
+            result << '--entrypoint ' << entryPoint << ' '
+
+        if( runOptions )
+            result << runOptions.join(' ') << ' '
+
+        if( cpus )
+            result << "--cpus ${cpus} "
+
+        if( memory )
+            result << "--memory ${memory.toUpperCase()} "
+
+        // --platform selects the image variant; --rosetta enables x86_64 execution via Rosetta.
+        // Both are needed for amd64 images: without --platform the CLI defaults to linux/arm64.
+        if( platform ) {
+            result << "--platform ${platform} "
+            if( !platform.contains("arm64") )
+                result << '--rosetta '
+        }
+
+        // the name is after the user option so it has precedence over any options provided by the user
+        if( name )
+            result << '--name ' << name << ' '
+
+        if( registry )
+            result << registry
+
+        // finally the container image
+        result << image
+
+        // return the run command as result
+        runCommand = result.toString()
+
+        // use an explicit 'container rm' command after the container stops
+        if( remove && name ) {
+            removeCommand = 'container rm ' + name
+        }
+
+        if( kill && name ) {
+            killCommand = 'container stop '
+            // if `kill` is a string it is interpreted as the kill signal
+            if( kill instanceof String ) killCommand = "container kill --signal $kill "
+            killCommand += name
+        }
+
+        return this
+    }
+
+    @Override
+    String getRunCommand(String launcher) {
+        if( !launcher )
+            return getRunCommand()
+        def result = getRunCommand()
+        result += entryPoint ? " -c \"$launcher\"" : " $launcher"
+        return result
+    }
+
+    /**
+     * @return The command string to remove a container
+     */
+    @Override
+    String getRemoveCommand() { removeCommand }
+
+    /**
+     * @return The command string to stop/kill a running container
+     */
+    @Override
+    String getKillCommand() { killCommand }
+
+}