القائمة
Create, enter, and manage Distrobox containers for mutable package installation on Bluefin.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/castrojo/bluefin-skills --skill distroboxيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
استنادا إلى تصنيف SOC المهني
عرض SKILL.md
| name | distrobox |
| description | Create, enter, and manage Distrobox containers for mutable package installation on Bluefin. |
| domain | sysadmin |
| tags | ["distrobox","containers","packages","linux"] |
| version | 2.0 |
Distrobox runs Linux distribution containers that integrate seamlessly with the host OS — sharing the home directory, display server, audio, DBus, and hardware devices. Use it to install RPM/DEB packages, run distribution-specific toolchains, or export apps/binaries to the host without touching the immutable base image.
dnf, apt, yum, pacman) without altering the hostroot-level package managementdistrobox-assemble)flatpak install (better sandboxing, auto-updates)brew install (lighter weight, no container overhead)podman run --rm# 1. Create a Fedora container (recommended on Bluefin)
distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest
# 2. Enter and install packages
distrobox enter mybox
sudo dnf install git vim golang
# 3. Export an app so it appears in the GNOME app grid
distrobox-export --app code # GUI app
distrobox-export --bin /usr/bin/go --export-path ~/.local/bin # CLI binary
# 4. Exit the container
exit
# Other lifecycle commands
distrobox list # show all containers
distrobox stop mybox # stop a running container
distrobox rm mybox # delete a container (data in home is preserved)
distrobox-assemble lets you define containers as code in an INI file and recreate them
idempotently. Commit distrobox.ini to your dotfiles for reproducible environments.
distrobox.ini:
[fedora-dev]
image=registry.fedoraproject.org/fedora:latest
pull=true
root=false
replace=false
init=false
additional_packages=git vim curl golang nodejs
[ubuntu-tools]
image=docker.io/library/ubuntu:22.04
pull=true
root=false
additional_packages=build-essential python3-pip
# Create all containers defined in the file
distrobox-assemble create --file distrobox.ini
# Destroy all containers defined in the file
distrobox-assemble rm --file distrobox.ini
# Dry-run to preview what would happen
distrobox-assemble create --file distrobox.ini --dry-run
Key INI options:
| Option | Effect |
|---|---|
image | OCI image reference |
pull=true | Always pull the latest image before creating |
replace=false | Don't destroy and recreate if container already exists |
init=false | Skip running the init script (faster; set true for systemd-based images) |
additional_packages | Space-separated list installed during first boot |
home | Override the container home directory path |
volume | Extra volume mounts (/host/path:/container/path) |
pre_init_hook | Shell command run before package installation |
post_init_hook | Shell command run after package installation |
When you need to run custom setup logic (dotfiles, config, tool downloads) the first time a
container is created, pass a script via --init-hooks or the init_hooks INI key.
distrobox create \
--name dev \
--image registry.fedoraproject.org/fedora:latest \
--init-hooks "curl -fsSL https://raw.githubusercontent.com/you/dotfiles/main/setup.sh | bash"
Or in distrobox.ini:
[dev]
image=registry.fedoraproject.org/fedora:latest
additional_packages=git curl
post_init_hook=curl -fsSL https://example.com/setup.sh | bash
The hook runs once on first enter. Destroying and recreating the container reruns it.
distrobox-export --app <name> handles most cases, but sometimes the app name doesn't match
the .desktop file, or the app isn't installed to a standard location.
Use distrobox-generate-entry to create the entry manually.
# Find the .desktop file inside the container
find /usr/share/applications -name "*.desktop" | grep -i myapp
# Generate a .desktop entry pointing to this container
distrobox-generate-entry myapp --container mybox --export-label " (mybox)"
# Remove a previously generated entry
distrobox-generate-entry myapp --container mybox --delete
distrobox enter | distrobox run | |
|---|---|---|
| Use case | Interactive shell session | Run a single command non-interactively |
| Allocates TTY | Yes | No (unless -- passes -t) |
| Shell | Login shell (reads .bashrc, etc.) | Direct exec, minimal environment |
| Exit code | Shell's exit code | Command's exit code (propagated cleanly) |
| Typical use | Development work, exploration | Scripting, CI one-shots, cron jobs |
Run a single command non-interactively: distrobox run --name mybox -- go test ./...
By default, Distrobox bind-mounts the host's $HOME into the container at the same path —
files created in either environment are immediately visible in both.
--homeUse --home to give a container its own private home directory (no host dotfiles):
distrobox create \
--name clean-box \
--image registry.fedoraproject.org/fedora:latest \
--home /home/jorge/containers/clean-box
--volumeMount additional host directories into the container with Docker-style syntax:
distrobox create \
--name dev \
--image registry.fedoraproject.org/fedora:latest \
--volume /mnt/data:/data:ro \ # read-only data share
--volume /run/docker.sock:/run/docker.sock # Docker socket passthrough
In distrobox.ini:
[dev]
image=registry.fedoraproject.org/fedora:latest
volume=/mnt/data:/data:ro /run/docker.sock:/run/docker.sock
Mount options (ro, rw, z, Z) follow OCI/Podman conventions.
registry.fedoraproject.org/fedora:latest
Why Fedora is preferred:
dnf is familiardocker.io/library/ubuntu:22.04 # LTS
docker.io/library/ubuntu:24.04
Use when a tool/SDK is only officially supported on Ubuntu, you need .deb builds,
or your project's CI is Ubuntu-based.
docker.io/library/archlinux:latest
Use when you need bleeding-edge package versions or AUR packages
(paru/yay work inside the container).
For reproducible environments, pin to a specific tag rather than latest:
[fedora-dev]
image=registry.fedoraproject.org/fedora:41
pull=false
Export a service running inside a container so the host systemd manages it.
# Inside the container: install and enable the service
distrobox enter mybox
sudo dnf install syncthing
systemctl --user enable syncthing.service
# Export to host
distrobox-export --service syncthing.service
exit
# On the host
systemctl --user start syncthing.service
systemctl --user enable syncthing.service
The exported .service file lands in ~/.config/systemd/user/ and wraps the in-container
process transparently. To remove: distrobox-export --service syncthing.service --delete && systemctl --user daemon-reload
Users on bluefin-nvidia can pass the GPU into a container for CUDA workloads, ML
training, or GPU-accelerated rendering.
distrobox create \
--name nvidia-box \
--image registry.fedoraproject.org/fedora:latest \
--nvidia
distrobox enter nvidia-box
nvidia-smi # verify GPU is visible
nvcc --version # if CUDA toolkit installed
python3 -c "import torch; print(torch.cuda.is_available())"
Requirements:
bluefin-nvidia (NVIDIA drivers pre-installed)--nvidia also sets NVIDIA_VISIBLE_DEVICES and NVIDIA_DRIVER_CAPABILITIESInstall CUDA inside the container (Fedora):
sudo dnf install cuda-toolkit
# PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Ptyxis (default terminal on Bluefin) has first-class Distrobox support — all running containers appear as selectable shell profiles in the sidebar. No CLI needed.
flatpak install flathub io.github.ranfdev.DistroShelf
GNOME GUI for creating, starting, stopping, and deleting containers, and opening terminals into them with one click. Changes are reflected in the CLI immediately.
distrobox-upgrade --all # upgrade all containers
distrobox-upgrade mybox ubuntu-tools # upgrade specific containers
distrobox-upgrade --all --pull # pull latest images first, then upgrade
Runs the appropriate package manager (dnf upgrade, apt upgrade, pacman -Syu, etc.)
inside each container non-interactively. Schedule with a systemd timer for automated maintenance.
distrobox list # check status
podman ps -a | grep mybox # Podman's view
podman logs mybox # inspect logs
# Force-remove stuck container and recreate
podman stop mybox && podman rm mybox
distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest
Corrupted image? Force re-pull:
podman pull registry.fedoraproject.org/fedora:latest
distrobox rm mybox && distrobox create --name mybox --image registry.fedoraproject.org/fedora:latest
ls ~/.local/share/applications/ | grep myapp # verify .desktop was created
update-desktop-database ~/.local/share/applications/ # refresh database
If the app name is wrong, use distrobox-generate-entry manually (see above).
Log out and back in if GNOME Shell still doesn't pick it up.
ls ~/.local/bin/ # confirm binary is there
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
| Container base | Install command |
|---|---|
| Fedora / RHEL | sudo dnf install <pkg> |
| Ubuntu / Debian | sudo apt update && sudo apt install <pkg> |
| Arch | sudo pacman -Syu <pkg> |
Distrobox grants passwordless sudo inside the container by default. If sudo is absent,
check /etc/sudoers.d/ or run su - with an empty root password.
Add :z (shared) or :Z (private) to volume mounts:
distrobox create --name dev --image fedora:latest --volume /mydata:/data:Z