Add --engine-args flag for custom container engine arguments

Implement a new --engine-args flag that allows users to pass
additional arguments directly to the container engine (podman/docker).
This provides flexibility for advanced users who need to customize
container behavior beyond what RamaLama's built-in flags offer.

The flag is named --engine-args (not --container-args) to clarify
that arguments are passed to the container engine, not the container itself.

Changes:
- Add --engine-args CLI argument in runtime_options()
- Can be specified multiple times to add multiple arguments
- Implement add_engine_args() method in Engine class
- Arguments are appended directly to exec_args before execution
- Add validation to conflict with --nocontainer flag
- Add engine_args to BaseConfig for ramalama.conf support
- Document flag in ramalama-run and ramalama-serve man pages
- Include usage examples, config file examples, and conflict documentation

Configuration file support:
Users can set default engine args in ramalama.conf:
```toml
[ramalama]
engine_args = ["--read-only", "--tmpfs /tmp"]
```

Use cases enabled:
- Custom mounts: --engine-args '--mount type=bind,src=/data,dst=/data'
- Additional env vars: --engine-args '--env CUSTOM_VAR=value'
- Security options: --engine-args '--security-opt label=disable'
- Read-only containers: --engine-args '--read-only'
- Any other podman/docker run flags

Tests:
- Unit tests verify arguments are added to exec_args correctly
- E2E dryrun tests verify arguments appear in engine command
- Conflict tests verify --engine-args raises error with --nocontainer
- All tests passing (5 new unit tests, 2 e2e tests)

The arguments are passed directly to the container engine, allowing
users to leverage the full power of podman/docker without RamaLama
needing to explicitly support every possible container option.

Fixes #2440

*This PR was created with the assistance of Cursor AI.*

Co-authored-by: Cursor <[email protected]>
Signed-off-by: Daniel J Walsh <[email protected]>

Author: rhatdan

docs/ramalama-bench.1.md

@@ -42,6 +42,24 @@ The device specification is passed directly to the underlying container engine.
 Pass '--device=none' explicitly add no device to the container, eg for
 running a CPU-only performance comparison.
 
+#### **--engine-args**=*ARG*
+Additional arguments to pass to the container engine (Podman or Docker).
+This option can be specified multiple times to add multiple arguments.
+
+This is useful for passing custom container options like additional mounts,
+environment variables, or other container-specific flags that RamaLama doesn't
+directly expose.
+
+**Note**: This option conflicts with `--nocontainer` and can only be used when
+running with a container engine.
+
+The default can be overridden in the `ramalama.conf` file:
+
+```toml
+[ramalama]
+engine_args = ["--read-only", "--tmpfs /tmp"]
+```
+
 #### **--env**=
 
 Set environment variables inside of the container.

docs/ramalama-perplexity.1.md

@@ -45,6 +45,24 @@ Example: --device=/dev/dri/renderD128:/dev/xvdc:rwm
 
 The device specification is passed directly to the underlying container engine. See documentation of the supported container engine for more information.
 
+#### **--engine-args**=*ARG*
+Additional arguments to pass to the container engine (Podman or Docker).
+This option can be specified multiple times to add multiple arguments.
+
+This is useful for passing custom container options like additional mounts,
+environment variables, or other container-specific flags that RamaLama doesn't
+directly expose.
+
+**Note**: This option conflicts with `--nocontainer` and can only be used when
+running with a container engine.
+
+The default can be overridden in the `ramalama.conf` file:
+
+```toml
+[ramalama]
+engine_args = ["--read-only", "--tmpfs /tmp"]
+```
+
 #### **--env**=
 
 Set environment variables inside of the container.

docs/ramalama-run.1.md

@@ -60,6 +60,41 @@ The device specification is passed directly to the underlying container engine.
 Pass '--device=none' explicitly add no device to the container, eg for
 running a CPU-only performance comparison.
 
+#### **--engine-args**=*ARG*
+Additional arguments to pass to the container engine (Podman or Docker).
+This option can be specified multiple times to add multiple arguments.
+
+This is useful for passing custom container options like additional mounts,
+environment variables, or other container-specific flags that RamaLama doesn't
+directly expose.
+
+**Note**: This option conflicts with `--nocontainer` and can only be used when
+running with a container engine.
+
+The default can be overridden in the `ramalama.conf` file:
+
+```toml
+[ramalama]
+engine_args = ["--read-only", "--tmpfs /tmp"]
+```
+
+Examples:
+```bash
+# Add a custom mount
+ramalama run --engine-args '--mount type=bind,src=/data,dst=/data' granite
+
+# Add multiple environment variables
+ramalama run --engine-args '--env CUSTOM_VAR=value' \
+             --engine-args '--env ANOTHER_VAR=test' granite
+
+# Combine multiple options
+ramalama run --engine-args '--read-only' \
+             --engine-args '--tmpfs /tmp' granite
+```
+
+Note: These arguments are passed directly to the container engine, so they must
+use the syntax expected by podman or docker.
+
 #### **--env**=
 
 Set environment variables inside of the container.

docs/ramalama-serve.1.md

@@ -85,6 +85,36 @@ running a CPU-only performance comparison.
 #### **--dri**=*on* | *off*
 Enable or disable mounting `/dev/dri` into the container when running with `--api=llama-stack` (enabled by default). Use to prevent access to the host device when not required, or avoid errors in environments where `/dev/dri` is not available.
 
+#### **--engine-args**=*ARG*
+Additional arguments to pass to the container engine (podman or docker).
+This option can be specified multiple times to add multiple arguments.
+
+This is useful for passing custom container options like additional mounts,
+environment variables, or other container-specific flags that RamaLama doesn't
+directly expose.
+
+**Note**: This option conflicts with `--nocontainer` and can only be used when
+running with a container engine.
+
+The default can be overridden in the `ramalama.conf` file:
+
+```toml
+[ramalama]
+engine_args = ["--read-only", "--tmpfs /tmp"]
+```
+
+Examples:
+```bash
+# Add a custom mount
+ramalama serve --engine-args '--mount type=bind,src=/data,dst=/data' granite
+
+# Add security options
+ramalama serve --engine-args '--security-opt label=disable' granite
+```
+
+Note: These arguments are passed directly to the container engine, so they must
+use the syntax expected by podman or docker.
+
 #### **--env**=
 
 Set environment variables inside of the container.

docs/ramalama.conf

@@ -57,6 +57,16 @@
 # Valid options (Podman, Docker)
 #engine = "podman"
 
+# Additional arguments to pass directly to the container engine (Podman or Docker)
+# This allows specifying custom container engine flags that RamaLama doesn't
+# directly expose. Only valid when using containers (conflicts with --nocontainer)
+#
+# Examples:
+#   engine_args = ["--read-only", "--tmpfs /tmp"]
+#   engine_args = ["--mount type=bind,src=/data,dst=/data", "--env CUSTOM_VAR=value"]
+#
+#engine_args = []
+
 # Environment variables to be added when running model within a container
 #
 #env = []

docs/ramalama.conf.5.md

@@ -106,6 +106,26 @@ Run RamaLama using the specified container engine.
 Valid options are: Podman and Docker
 This field can be overridden by the RAMALAMA_CONTAINER_ENGINE environment variable.
 
+**engine_args**=[]
+
+Additional arguments to pass directly to the container engine (Podman or Docker).
+This option allows specifying custom container engine flags that RamaLama doesn't
+directly expose as CLI options. Multiple arguments can be specified as an array.
+Only valid when using containers (conflicts with --nocontainer).
+
+Examples:
+```toml
+engine_args = ["--read-only", "--tmpfs /tmp"]
+```
+
+Or:
+```toml
+engine_args = [
+    "--mount type=bind,src=/data,dst=/data",
+    "--env CUSTOM_VAR=value"
+]
+```
+
 **env**=[]
 
 Environment variables to be added to the environment used when running in a container engine (e.g., Podman, Docker). For example "LLAMA_ARG_THREADS=10".

ramalama/cli.py

@@ -351,6 +351,10 @@ def post_parse_setup(args):
     if getattr(args, "subcommand", None) == "benchmark":
         args.subcommand = "bench"
 
+    # Validate that --engine-args is only used with containers
+    if getattr(args, "engine_args", None) and not getattr(args, "container", True):
+        raise ValueError("--engine-args can only be used with container mode (conflicts with --nocontainer)")
+
     def map_https_to_transport(input: str) -> str:
         if input.startswith("https://") or input.startswith("http://"):
             url = urlparse(input)
@@ -1060,6 +1064,16 @@ def runtime_options(parser, command):
         action="store_true",
         help="""pass `--group-add keep-groups` to podman.
 If GPU device on host is accessible to via group access, this option leaks the user groups into the container.""",
+    )
+    parser.add_argument(
+        "--engine-args",
+        dest="engine_args",
+        action='append',
+        type=str,
+        default=config.engine_args,
+        help="""additional arguments to pass to the container engine
+(e.g., '--mount type=bind,src=/path,dst=/path' or '--env VAR=value').
+Only valid when using containers (conflicts with --nocontainer)""",
     )
     if command == "run":
         parser.add_argument(

ramalama/config.py

@@ -250,6 +250,7 @@ class BaseConfig:
     default_rag_image: str = DEFAULT_RAG_IMAGE
     dryrun: bool = False
     engine: SUPPORTED_ENGINES | None = field(default_factory=get_default_engine)
+    engine_args: list[str] = field(default_factory=list)
     env: list[str] = field(default_factory=list)
     gguf_quantization_mode: GGUF_QUANTIZATION_MODES = DEFAULT_GGUF_QUANTIZATION_MODE
     host: str = "0.0.0.0"

ramalama/engine.py

@@ -116,6 +116,15 @@ def handle_podman_specifics(self):
         if getattr(self.args, "podman_keep_groups", None):
             self.exec_args += ["--group-add", "keep-groups"]
 
+    def add_engine_args(self):
+        """Add custom engine arguments specified by the user."""
+        engine_args = getattr(self.args, "engine_args", None)
+        if engine_args:
+            import shlex
+
+            for arg in engine_args:
+                self.exec_args.extend(shlex.split(arg))
+
     def add(self, newargs: Sequence[str]):
         self.exec_args.extend(newargs)
 
@@ -152,6 +161,7 @@ def __init__(self, args: BaseEngineArgsType) -> None:
         self.add_detach_option()
         self.add_device_options()
         self.add_env_options()
+        self.add_engine_args()
         self.add_port_option()
         self.add_tty_option()
 

test/e2e/test_run.py

@@ -224,6 +224,14 @@ def test_basic_dry_run():
         pytest.param(
             ["--device", "none", "--pull", "never"], r".*--device.*", None, None, False, None,
             id="check --device with unsupported value", marks=skip_if_no_container),
+        pytest.param(
+            ["--engine-args", "--read-only"], r".*--read-only.*", None, None, True, None,
+            id="check --engine-args with single arg", marks=skip_if_no_container),
+        pytest.param(
+            ["--engine-args", "--mount type=bind,src=/data,dst=/data",
+             "--engine-args", "--env CUSTOM_VAR=value"],
+            r".*--mount type=bind,src=/data,dst=/data.*--env CUSTOM_VAR=value.*", None, None, True, None,
+            id="check --engine-args with multiple args", marks=skip_if_no_container),
     ],
 )
 # fmt: on