Add full support for running in toolbox with containers

[olliewalsh]

Previously running in a toolbox environment set the container engine to None, effectively forcing nocontainer mode. This adds full support for running in a toolbox environment by using flatpak-spawn to access the host podman/docker.

Add engine_cmd() helper that wraps the container engine binary with flatpak-spawn --host when running inside a toolbox.
Use ~/.cache/ramalama/tmp as the default temp directory in toolbox environments since /var/tmp is not shared with the host (required for image builds etc...).
Report toolbox status in ramalama info output via a new Toolbox field
Add e2e-tests-toolbox CI job that creates a Fedora 44 toolbox on Ubuntu 24.04

Tested on fedora44 silverblue host with fedora44 toolbox for AMD ROCm/Vukan and NVIDIA CUDA llama.cpp backends.

Fixes: #2798
Fixes: #1095

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds Fedora Toolbox support by detecting toolbox environments, routing container-engine commands through flatpak-spawn --host, selecting host engines, using toolbox-safe temporary directories, updating tests and documentation, and adding Toolbox end-to-end CI coverage.

Changes

Toolbox support

Layer / File(s)	Summary
Toolbox detection and configuration ramalama/common.py, ramalama/config.py, ramalama/cli.py, docs/*	Adds toolbox detection, host engine selection, toolbox-specific temporary-directory handling, CLI reporting, and updated Toolbox documentation.
Engine command propagation ramalama/engine.py, ramalama/oci_tools.py, ramalama/stack.py, ramalama/transports/*, ramalama/common.py	Routes container-engine invocations through engine_cmd() across runtime, daemon, stack, image, artifact, registry, and model operations.
Toolbox validation and CI test/*, .github/workflows/ci.yml, pyproject.toml	Updates fixtures and assertions for tokenized engine commands, adds toolbox-aware unit coverage, forwards the DBus session into tox, and runs end-to-end tests in Fedora Toolbox.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RamaLama
  participant Toolbox
  participant HostEngine
  participant Container
  RamaLama->>Toolbox: detect toolbox environment
  RamaLama->>Toolbox: invoke flatpak-spawn --host
  Toolbox->>HostEngine: run container-engine command
  HostEngine->>Container: execute container operation

Loading

Possibly related PRs

• containers/ramalama#2728: Both changes modify container-engine command construction in overlapping engine and stack paths.
• containers/ramalama#2827: Both changes update CI end-to-end workflows using a local Hugging Face mirror.

Suggested reviewers: rhatdan, mikebonnet, bmahabirbu, jhjaggars, cgruver

Poem

A rabbit hops through Toolbox bright,
Sending engine calls hostward in flight.
Flatpak opens the guarded door,
Tests run safely, then run some more.
Cache paths bloom where temp files stay—
CI thumps its paws: hooray!

🚥 Pre-merge checks | ✅ 2 | ❌ 3

❌ Failed checks (3 warnings)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The PR does not show the GPU passthrough/device-mapping work required by #2798, such as /dev/dri, /dev/kfd, or device detection.	Add the toolbox GPU passthrough changes and verify the container sees the AMD ROCm devices with the required Podman runtime args.
Out of Scope Changes check	⚠️ Warning	Several docs, CI, tempdir, and info-output changes are broader toolbox-support work and go beyond the linked GPU passthrough issue.	Trim or separate nonessential toolbox/docs/CI changes so the PR focuses on the #2798 GPU passthrough fix.
Docstring Coverage	⚠️ Warning	Docstring coverage is 16.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: toolbox support for container execution.
Description check	✅ Passed	The description is directly aligned with the changeset, covering toolbox support, engine_cmd, tempdir behavior, info output, and CI.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[olliewalsh]

@rhatdan @bmahabirbu @mikebonnet PTAL

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 665-670: The toolbox E2E job and registry fixture must use a
host-shared temporary directory. In .github/workflows/ci.yml lines 665-670,
create and export TMPDIR="$HOME/.cache/ramalama/tmp" inside the toolbox before
make e2e-tests; in test/e2e/conftest.py lines 75-88, update the registry
fixture’s TemporaryDirectory usage to explicitly use that shared directory so
local toolbox runs do not depend on workflow setup.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: bd97b77b-6d07-4945-b336-509fcce0e588

📥 Commits

Reviewing files that changed from the base of the PR and between 79fe20f and 27db8ec.

📒 Files selected for processing (23)

• .github/workflows/ci.yml
• docs/ramalama-info.1.md
• docs/ramalama.1.md
• pyproject.toml
• ramalama/cli.py
• ramalama/common.py
• ramalama/config.py
• ramalama/engine.py
• ramalama/oci_tools.py
• ramalama/stack.py
• ramalama/transports/oci/oci.py
• ramalama/transports/oci/resolver.py
• ramalama/transports/oci/strategies.py
• ramalama/transports/rlcr.py
• test/conftest.py
• test/e2e/conftest.py
• test/e2e/test_pull.py
• test/e2e/test_rag.py
• test/e2e/test_run.py
• test/e2e/test_serve.py
• test/unit/conftest.py
• test/unit/test_common.py
• test/unit/test_config.py

🚧 Files skipped from review as they are similar to previous changes (16)

• test/conftest.py
• test/e2e/test_pull.py
• test/unit/conftest.py
• ramalama/cli.py
• ramalama/transports/oci/resolver.py
• docs/ramalama-info.1.md
• test/e2e/test_rag.py
• pyproject.toml
• test/unit/test_config.py
• docs/ramalama.1.md
• ramalama/stack.py
• test/unit/test_common.py
• ramalama/oci_tools.py
• ramalama/transports/rlcr.py
• ramalama/common.py
• ramalama/engine.py

[bmahabirbu]

Cool! Ill give it a shot on my fedora system soon!

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.github/workflows/ci.yml:
- Around line 599-611: Add a job-level least-privilege permissions block to
e2e-tests-toolbox, granting only contents read access, positioned before its
steps while preserving the existing job condition, dependencies, and test
execution.
- Around line 647-651: Update the “Install dependencies in toolbox” workflow
step to run uv venv inside the project directory before uv pip install '.[dev]'.
Keep pip install uv and uv tool install tox --with tox-uv before creating the
project environment, as requested.
- Around line 620-651: Install Ollama inside the ramalama-test Toolbox during
the “Install dependencies in toolbox” workflow step, using the existing toolbox
run mechanism, and ensure the installed ollama executable is available on PATH
for subsequent make e2e-tests execution. Keep the installation scoped to the
toolbox environment alongside the other E2E dependencies.
- Line 611: Update the actions/checkout step to disable credential persistence
by configuring its persist-credentials option to false, while preserving the
existing checkout behavior.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: df1138af-64fb-4930-aa69-b88075826d5e

📥 Commits

Reviewing files that changed from the base of the PR and between 27db8ec and 042e52d.

📒 Files selected for processing (9)

• .github/workflows/ci.yml
• pyproject.toml
• test/conftest.py
• test/e2e/conftest.py
• test/e2e/test_pull.py
• test/e2e/test_rag.py
• test/e2e/test_run.py
• test/e2e/test_serve.py
• test/unit/conftest.py

🚧 Files skipped from review as they are similar to previous changes (5)

• test/conftest.py
• test/unit/conftest.py
• test/e2e/test_pull.py
• pyproject.toml
• test/e2e/test_rag.py

[olliewalsh]

Cool! Ill give it a shot on my fedora system soon!

If you want to use CUDA then need to run all of the CDI etc... setup on both the host and inside the toolbox. I expect this can be improved to just require the host to be configured, but will leave it for a follow-up PR as this PR is already big enough.

[rhatdan]

@debarshiray PTAL