Documentation
🚀 Quick Start

🚀 Quick Start

Getting Up and Running with RF Swift

Here we will quickly get started with RF Swift using pre-built binaries and container images.

On Linux, unless you are using Docker Desktop, you may need to use sudo with the rfswift command for operations that require elevated privileges.

To avoid using sudo for every Docker command, add your user to the docker group:

sudo usermod -aG docker $USER
newgrp docker

Podman runs rootless by default — no sudo or group membership required. Just make sure your subordinate UID/GID ranges are configured:

sudo usermod --add-subuids 100000-165535 $USER
sudo usermod --add-subgids 100000-165535 $USER

To install RF Swift, you can either use pre-compiled binaries and existing container images (quickest method) or compile the Go project and/or container images from source. This guide focuses on the fastest way to get up and running.

Install RF Swift

Skip this step if you already did it. This is just a reminder to show that the installation is pretty fast.

Linux and macOS

The easiest way to install RF Swift with this command line:

curl -fsSL "https://raw.githubusercontent.com/PentHertz/RF-Swift/refs/heads/main/get_rfswift.sh" | sh
curl -fsSL "https://raw.githubusercontent.com/PentHertz/RF-Swift/refs/heads/main/get_rfswift.sh" | sh

The installer will prompt you to choose a container engine if none is detected:

📝 Which container engine would you like to install?
1) Docker   2) Podman   3) Both   4) Skip

But if you want to install it securely, we recommend using the installation script after downloading the latest version here:

# Run the installation script
./install.sh

The install.sh script will:

  • Install your chosen container engine (Docker, Podman, or both)
  • Install all required dependencies (BuildX, Go)
  • Configure necessary services (xhost, PulseAudio/PipeWire)
  • Set up proper permissions and rootless configuration
  • Create a system-wide alias for the rfswift command
  • Install the latest RF Swift binary

Alternative: from sources

You can also download the latest (unstable) version from GitHub by cloning the repository, but you will need to build and use install.sh script as follows:

git clone https://github.com/PentHertz/RF-Swift.git
cd RF-Swift

# Step 1 - Building the project requirements
./build_project.sh

# Step 2 - Run the installation script
./install.sh

Then you should have the binary installed as well as all the requirements ;)

Windows or Manual Installation

If you prefer manual installation or are using Windows:

  1. Download the latest binary from the official repository ↗
  2. Rename the binary to rfswift (or rfswift.exe on Windows)
  3. Make the binary executable (on Linux/macOS): chmod +x rfswift

When you run the binary for the first time, it will guide you through configuration:

rfswift 
Config file not found. Would you like to create one with default values? (y/n)

Select y to create a default configuration file or n to configure manually.

RF Swift auto-detects the available container engine (Docker or Podman) at startup. You can override this with rfswift --engine docker or rfswift --engine podman.

Pull a Pre-built Image

RF Swift provides several pre-built images to get you started quickly. For example, let’s pull a complete SDR image:

rfswift images pull -i sdr_full

You can also specify a custom tag for the image:

rfswift images pull -i sdr_full -t my_custom_tag
All RF Swift images are OCI-compatible and work identically with both Docker and Podman. The same rfswift images pull command works regardless of which engine you have installed.

RF Swift Ubuntu Noble (version 24.04) images are in the way, and you can also test them using the penthertz/rfswift_noble:<tag> prefix. In case you want to use Noble images with a short tag name, modify you RF Swift profile config.ini file as follows:

[general]
imagename = myrfswift:latest
repotag = penthertz/rfswift_noble

...

Available Options:

  • -i: Remote image label (required)
  • -t: Local tag to assign to the pulled image (optional)
  • -r: Repository to pull from (defaults to penthertz/rfswift)
You can use the complete image tag penthertz/rfswift_noble:sdr_full if you prefer, or change the default repository in your RF Swift profile.

Run the Container

Once you have an image, you can create and run a container:

rfswift run -i sdr_full -n my_sdr_container

This will start a container using the sdr_full image with the name my_sdr_container.

With some platforms, some default devices may be non-existent. You can use bindings or modify RF Swift’s configuration file to remove the device from the mapped device list.

Advanced features

Run Command Options:

rfswift run -i sdr_full -n my_sdr_container

The run command has numerous options for configuring your container environment:

Flag Description
-i, --image string Image name/tag to use (default: ‘myrfswift:latest’)
-n, --name string Name for the container (makes it easier to reference later)
-b, --bind string Extra bind mounts, separated by commas (e.g., /host/path:/container/path,/another/path:/in/container)
-s, --devices string Extra device mappings in unprivileged mode, separated by commas (e.g., /dev/ttyUSB0:/dev/ttyUSB0)
-a, --capabilities string Extra Linux capabilities, separated by commas (e.g., NET_ADMIN,SYS_ADMIN)
-t, --network string Network mode (default: ‘host’)
-u, --privileged int Set privilege level (1: privileged, 0: unprivileged)
-e, --command string Command to execute (default: ‘/bin/bash’)
-d, --display string Set X Display (duplicates host’s env by default) (default “DISPLAY=:0”)
-p, --pulseserver string PulseAudio server TCP address (default: “tcp:127.0.0.1:34567”)
-w, --bindedports string Ports to bind (between container and host)
-z, --exposedports string Ports to expose
-x, --extrahosts string Set extra hosts (default: ‘pluto.local:192.168.1.2’), separated by commas
-g, --cgroups string Extra cgroup rules, separated by commas
-m, --seccomp string Set Seccomp profile (default: ‘default’)
--no-x11 Disable X11 forwarding
--record Record the container session
--record-output string Custom output filename for recording (default: auto-generated)

Share Files with the Container:

To share files between your host system and the container:

rfswift run -i sdr_full -n my_sdr_container -b ~/sdr_projects:/home/user/projects

You can bind multiple directories by separating them with commas:

rfswift run -i sdr_full -n my_sdr_container -b ~/sdr_projects:/home/user/projects,~/datasets:/home/user/data

Share Specific Devices:

When running in unprivileged mode, you can share specific devices:

rfswift run -i sdr_full -n my_sdr_container -s /dev/ttyUSB0:/dev/ttyUSB0

Multiple devices can be shared by separating them with commas:

rfswift run -i sdr_full -n my_sdr_container -s /dev/ttyUSB0:/dev/ttyUSB0,/dev/ttyACM0:/dev/ttyACM0
If you plug the device after the container has started, or replug it later, you will have to stop it with command rfswift stop -c <container name>. You can avoid this manipulation by mounting /dev/bus/usb:/dev/bus/usb as a volume instead with option -b when creating and running the container. This last manipulation may degrade the container’s isolation.
Device passthrough works natively with Docker. When running in privileged mode (-u 1), all host devices are accessible inside the container.

With Podman in rootless mode, device passthrough may require additional steps:

  • Use --device flags explicitly via the -s option
  • For USB SDR devices, binding /dev/bus/usb as a volume (-b /dev/bus/usb:/dev/bus/usb) is often the simplest approach
  • RF Swift auto-detects cgroup v1/v2 and configures device access rules accordingly

Add Linux Capabilities:

For Wi-Fi and Bluetooth tools, you may need additional Linux capabilities:

rfswift run -i wifi_tools -n my_wifi_container -a NET_ADMIN

For multiple capabilities:

rfswift run -i advanced_tools -n my_container -a NET_ADMIN,SYS_ADMIN
Security Consideration: Be cautious when adding capabilities like NET_ADMIN. If the container becomes compromised, malicious programs could capture or manipulate network interfaces! Only add capabilities that are strictly necessary for your work.
If your container is already running, you will be able to configure bindings, exposed ports, capabilities, cgroups later with bindings, cgroups, and capabilities (maybe more properties later ;))

Network Configuration:

By default, containers use the host network mode. To use a different network:

rfswift run -i sdr_full -n my_sdr_container -t bridge
Docker uses its built-in bridge, host, and overlay networks. Host mode is the default for RF Swift.
Podman supports the same network modes. In rootless mode, slirp4netns or pasta handles networking. Host mode works identically when running as root or with sufficient privileges.

Privilege Levels:

Control container privilege level:

# Run in unprivileged mode
rfswift run -i sdr_full -n my_sdr_container -u 0

# Run in privileged mode (use with caution)
rfswift run -i sdr_full -n my_sdr_container -u 1
With Podman in rootless mode, privileged mode (-u 1) grants privileges within the user namespace, which is still more restricted than Docker’s privileged mode. This provides an extra layer of safety.

Custom Commands:

Run a specific command instead of the default shell:

rfswift run -i gnuradio -n signal_processor -e "gnuradio-companion"

Recording Sessions:

You can record your container sessions for documentation or debugging purposes:

# Record with auto-generated filename
rfswift run -i sdr_full -n my_sdr_container --record

# Record with custom filename
rfswift run -i sdr_full -n my_sdr_container --record --record-output my-session.cast

Session recordings are saved as .cast files (asciinema format) that can be replayed later.

Using a named container with the -n flag makes it much easier to restart or access the container later.

Use RF Tools in the Container

Once the container is running, you can use any of the pre-installed RF tools. For example, to run SDR++:

  1. Connect your SDR device to your computer
  2. Inside the container, run: sdrpp
If you encounter audio issues, you can enable audio forwarding with: rfswift host audio enable This requires pulseaudio or pipewire-pulse to be properly configured on your host system.

USB Device Management

USB device handling varies by platform:

Windows USB Forwarding

On Windows, you’ll need to explicitly forward USB devices to your container using the winusb commands in Administrator mode:

# List available USB devices on Windows
rfswift winusb list

# Attach a specific device on Windows
rfswift winusb attach -i <USB ID>

Linux USB Device Access

On Linux, you can access USB devices in two ways:

  1. During container creation - use the -s option to bind specific devices:

    rfswift run -i sdr_full -n my_container -s /dev/ttyUSB0:/dev/ttyUSB0

  2. After container creation - use the powerful bindings feature to add devices to an existing container:

    # Add a new USB device to an existing container
rfswift bindings add -c my_container -d -s /dev/ttyUSB0 -t /dev/ttyUSB0

# Same but shorter: Add a new USB device to an existing container with same destination
rfswift bindings add -c my_container -t /dev/ttyUSB0

# Add a new volume to an existing container
rfswift bindings add -c my_container -s /home/user/data -t /root/data

# Remove a binding
rfswift bindings rm -c my_container -s /dev/ttyUSB0

Note that to rebind a device, you need the -d switch.

macOS USB Device Access

For the moment Docker and Podman on macOS do not have a proper way to forward USB accesses. USB devices cannot be used without using complex virtualization.

Managing Existing Containers

Stop a Running Container

Running containers can be stopped using the stop command as follows:

rfswift stop -c my_sdr_container

Restart an Existing Container

To return to a previously created container:

rfswift exec -c my_sdr_container

You can also use the short command if you want to recall the last container:

rfswift exec

This restarts the container if it’s stopped and gives you a shell inside it.

Recording Run and Exec sessions:

With run and exec, you can record exec sessions with --record argument:

# Record a new container session
rfswift run -i sdr_full -n my_container --record

# Record with auto-generated filename
rfswift exec -c my_sdr_container --record

# Record with custom filename and working directory
rfswift exec -c my_sdr_container -w /root/projects --record --record-output debug-session.cast

List Running Containers

View all RF Swift containers:

rfswift last

Save Container State

If you’ve made changes to a container that you want to preserve:

rfswift commit -c my_sdr_container -i my_custom_image

This saves the current state of the container as a new image.

Session Playback

Replaying Recordings

Play back recorded sessions:

# Normal speed playback
rfswift log replay -i rfswift-exec-mycontainer-20260112-134651.cast

# 2x speed playback
rfswift log replay -i session.cast -s 2.0

Managing Recordings 

# List all recordings in current directory
rfswift log list

# List recordings in specific directory
rfswift log list --dir ~/recordings
Session recordings are stored as .cast files in asciinema format, which can be uploaded to asciinema.org for sharing or embedded in documentation.

Common Commands Reference

Command Description
rfswift run -i IMAGE -n NAME Create and run a new container
rfswift exec -c CONTAINER Enter an existing container
rfswift images local List available local images
rfswift last List all containers
rfswift host audio enable Enable audio forwarding
rfswift bindings add Add device or volume binding to existing container
rfswift log replay -i FILE Replay a recorded session
rfswift log list List all recorded sessions
rfswift --engine docker ... Force Docker engine
rfswift --engine podman ... Force Podman engine

Next Steps

Dive right into the following section to learn more:

Follow the Guide
Read the complete guide and learn how to use RF Swift for your daily assessments.
Last updated on
Getting Started📖 Guide