engine

rfswift –engine

Select the container engine used by RF Swift.

Synopsis

rfswift --engine ENGINE [command] [options]

The --engine flag is a global flag that overrides RF Swift’s auto-detection and forces a specific container engine for the current command. It must be placed before any subcommand.

Options

Auto-Detection Behavior

When --engine is not specified, RF Swift automatically detects the available container engine at startup using the following priority:

1. Is Podman installed?        → check podman binary + fallback paths
2. Is Docker installed?        → check docker binary
3. Is podman-docker shim active? → detect via `docker --version` containing "podman"
4. Is Docker daemon running?   → verify daemon connectivity

# Force Docker
rfswift --engine docker run -i sdr_full -n my_container

# Force Podman
rfswift --engine podman run -i sdr_full -n my_container

rfswift run -i sdr_full -n my_container
# → uses Docker

rfswift run -i sdr_full -n my_container
# → uses Podman

❌ No container engine found. Please install Docker or Podman.
 Run ./scripts/install.sh or visit https://rfswift.io/docs/getting-started/

Examples

Force Docker

# Pull image with Docker
rfswift --engine docker images pull -i sdr_full

# Run container with Docker
rfswift --engine docker run -i sdr_full -n my_sdr

# List containers managed by Docker
rfswift --engine docker last

Force Podman

# Pull image with Podman
rfswift --engine podman images pull -i sdr_full

# Run rootless container with Podman
rfswift --engine podman run -i sdr_full -n rootless_sdr

# List containers managed by Podman
rfswift --engine podman last

Force Lima (macOS USB passthrough)

# Attach USB device to Lima VM first
rfswift macusb attach --vid 0x1d50 --pid 0x604b

# Run container via Lima's Docker (USB devices visible)
rfswift --engine lima run -i sdr_full -n usb_sdr

# List containers in Lima
rfswift --engine lima last

# When done, detach device
rfswift macusb detach --vid 0x1d50 --pid 0x604b

Mixed Workflows

If both engines are installed, you can maintain separate environments:

# Docker for privileged hardware work
rfswift --engine docker run -i sdr_full -n docker_sdr \
  -u 1 \
  -s /dev/bus/usb:/dev/bus/usb

# Podman for rootless analysis
rfswift --engine podman run -i reversing -n podman_analysis \
  -u 0 \
  -t none \
  -b ~/samples:/root/samples:ro

Engine Comparison

Podman-Specific Notes

Rootless Configuration

Podman runs rootless by default. Ensure your system is configured:

# Check subordinate UID/GID ranges
grep $USER /etc/subuid /etc/subgid

# If empty, configure them
sudo usermod --add-subuids 100000-165535 $USER
sudo usermod --add-subgids 100000-165535 $USER

# Enable lingering (containers survive logout)
sudo loginctl enable-linger $USER

# Enable Podman socket (Docker API compatibility)
systemctl --user enable --now podman.socket

Image Registry

Podman may prompt for a registry when using short image names:

# Full name (no prompt)
rfswift --engine podman images pull -i docker.io/penthertz/rfswift_noble:sdr_full

# Short name (may prompt for registry selection)
rfswift --engine podman images pull -i sdr_full

To avoid prompts, configure default registries in /etc/containers/registries.conf:

unqualified-search-registries = ["docker.io"]

Privileged Mode Differences

In rootless Podman, -u 1 (privileged) grants privileges within the user namespace, which is still more restricted than Docker’s privileged mode:

# Docker privileged = full host root access
rfswift --engine docker run -i sdr_full -n docker_priv -u 1

# Podman privileged = root within user namespace (safer)
rfswift --engine podman run -i sdr_full -n podman_priv -u 1

Cgroup Compatibility

RF Swift auto-detects cgroup v1 and v2 and configures device access rules accordingly. No manual configuration is needed.

Docker-Specific Notes

Daemon Requirement

Docker requires its daemon to be running:

# Check daemon status
sudo systemctl status docker

# Start if stopped
sudo systemctl start docker

# Enable at boot
sudo systemctl enable docker

Group Membership

To run Docker without sudo:

sudo usermod -aG docker $USER
newgrp docker

Troubleshooting

Engine Not Found

Error: No container engine found

Solution:

# Install via RF Swift installer
curl -fsSL "https://get.rfswift.io/" | sh

# Or install manually
sudo apt install podman     # Debian/Ubuntu
sudo dnf install podman     # Fedora
curl -fsSL https://get.docker.com | sudo sh  # Docker

Wrong Engine Detected

Problem: RF Swift picks Docker when you want Podman (or vice versa)

Solution:

# Explicit override
rfswift --engine podman run -i sdr_full -n my_container

podman-docker Shim Detected as Docker

Problem: podman-docker package makes docker command available but it’s actually Podman

Solution: RF Swift handles this automatically. It checks docker --version output for the word “podman” and correctly identifies the engine. No action needed.

Containers Not Visible Across Engines

Problem: Created a container with Docker but can’t see it with Podman

Solution: This is expected behavior. Each engine manages its own containers and images independently. Use the same --engine flag you used to create the container:

# If created with Docker
rfswift --engine docker exec -c my_container

# If created with Podman
rfswift --engine podman exec -c my_container

Environment Variables

# Use Lima engine via environment variable
export RFSWIFT_ENGINE=lima
rfswift run -i sdr_full -n my_sdr

# Use a custom Lima instance name
export RFSWIFT_LIMA_INSTANCE=my_custom_vm
rfswift macusb status

rfswift engine

Running rfswift engine without subcommands displays information about the currently active container engine, including detection results and socket paths.

rfswift engine

rfswift engine lima

Manage the Lima QEMU VM lifecycle on macOS. These commands give you direct control over the Lima VM without resorting to raw limactl commands.

Automatic VM Lifecycle Management

RF Swift now automatically manages the Lima VM — no manual limactl commands required. When you run any command with --engine lima, RF Swift transparently handles the full VM lifecycle:

1. Instance detection: Checks if the Lima instance exists
2. Auto-creation: If the instance doesn’t exist, creates it from the best available template (searches standard paths, falls back to a built-in inline template)
3. Auto-start: If the instance exists but is stopped, starts it automatically
4. Docker readiness: Waits (up to 60 seconds) for Docker to become available inside the VM before proceeding
5. Socket routing: Sets DOCKER_HOST to the Lima Docker socket so all container operations work transparently

# First run — RF Swift creates the VM, installs Docker + USB tools, starts everything
rfswift --engine lima run -i sdr_full -n my_sdr
# → "Lima instance 'rfswift' not found. Creating it..."
# → "Lima instance 'rfswift' created and started"
# → Container runs normally

# Second run — VM already exists, RF Swift just starts it if stopped
rfswift --engine lima run -i sdr_full -n another_sdr
# → "Starting Lima instance 'rfswift'..."
# → Container runs normally

# VM already running — no extra steps, runs immediately
rfswift --engine lima exec -c my_sdr

The auto-created VM is fully provisioned with:

• Docker engine
• USB libraries (libusb, libhidapi, libftdi)
• Kernel modules for USB serial devices (cp210x, ftdi_sio, ch341)
• Bluetooth stack (bluez, btusb, rfcomm, vhci-hcd)
• Udev rules for 100+ RF/USB devices (HackRF, RTL-SDR, USRP, BladeRF, Airspy, PlutoSDR, LimeSDR, etc.)

engine lima status

Display the Lima VM instance details: running status, configuration file path, template source, QMP socket, and Docker socket.

rfswift engine lima status
rfswift engine lima status --instance my_custom_vm

Options:

Output includes:

• Instance name and running/stopped status
• Configuration file path (~/.lima/<instance>/lima.yaml)
• Template source location (or “inline fallback” if none found)
• QMP socket path (required for USB passthrough)
• Docker socket path (for container engine routing)

engine lima reconfig

Apply an updated YAML template to the VM. By default this is non-destructive — the VM is stopped, the template is applied, and the VM is restarted. The VM filesystem (Docker images, containers, etc.) is preserved.

# Non-destructive: stop → apply template → restart
rfswift engine lima reconfig

# Use a specific template
rfswift engine lima reconfig --template ~/my-custom-lima.yaml

# Destructive: delete and recreate the VM (all VM data lost)
rfswift engine lima reconfig --force

Options:

Template search order (when --template is not specified):

1. <binary_dir>/lima/rfswift.yaml
2. ~/.config/rfswift/lima.yaml
3. ~/.rfswift/lima.yaml

Use cases:

• Changed CPU, memory, or disk allocation in the YAML
• Added new port forwards or host directory mounts
• Updated provisioning scripts (udev rules, kernel modules)
• With --force: changed base OS image or disk size (requires full recreation)

engine lima reset

Delete and recreate the Lima VM from scratch. All data inside the VM is lost. This is equivalent to reconfig --force, but also works when no instance exists yet.

rfswift engine lima reset
rfswift engine lima reset --template ~/my-custom-lima.yaml

Options:

Related

• run - Create and run containers
• exec - Enter existing containers
• images - Manage container images
• macusb - Manage USB devices on macOS via Lima
• network - Manage container networks
• Getting Started - Installation and engine setup
• Container Engine Support - Requirements and platform support