Install RF Swift

One installer per system sets up RF Swift and the engine it needs. Pick your system below; it takes about five minutes.

Beginner · 8 min read · Updated September 27, 2026

The recommended way for each system is shown first. You can accept the installer’s defaults, and change any choice later. The current release is v4.0.2.

Before you start

Check that your computer is supported: Will it run on my computer? Unsure what an “engine” is? Key ideas explains it in one paragraph. You can accept the installer’s defaults.

Install

1. Open a terminal and paste this line:

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

2. Answer a few questions. The defaults are fine for most people. The installer asks:

  • which release channel to use: stable (recommended) or the development prerelease;
  • what to install: the rfswift command line, the Workbench desktop app, or both;
  • how to install it: a native package (deb, rpm or pacman) when your system allows it, otherwise a folder of your choice;
  • which engine to install if you have none: Docker, Podman, both, or skip;
  • whether to add Nix for the native engine, and its isolation helper;
  • whether to install the udev rules that let your user open radio hardware, and set up Docker access, display and sound.

Every download is checked against the release’s SHA-256 manifest before it is used.

3. Run rfswift. The first time, it offers to create its configuration file with the default values. Answer y.

Check that it worked

bash
rfswift --version
rfswift doctor

rfswift --version prints the installed version. rfswift doctor checks your system: the engines, USB, display, sound, the configuration file and more. Each failing line names the command that fixes it.

On a Linux desktop

Run rfswift host setup once. It walks you through the optional host steps (udev rules for radio hardware, installing an engine, Nix, Docker access, the Nix isolation jail) and asks before each one.

If Docker says “permission denied”, run rfswift host docker-access: it gives your user access right away, with no logout. Members of the docker group are root-equivalent on the host.

Already on Kali, Parrot, BlackArch or DragonOS?

Keep it. RF Swift installs inside the distribution like on any Linux (Kali gets its own docker.io package). The Nix engine adds pinned per-engagement environments, single tools on demand and the --isolate jail without touching the distribution’s packages: rfswift host setup --engine none --nix yes, then rfswift env run sdr_light sdrpp. See Keep your distribution, add RF Swift.

What’s next

Quick startDownload a toolbox and open your first lab.Beginner Tutorial: your first signalPlug in an SDR and listen to a real transmission.Beginner Tour the WorkbenchThe graphical way to use RF Swift.Beginner

Advanced installation

You don’t need this section for a normal install. It covers unattended installs, native packages, choosing and setting up an engine yourself, and verifying downloads.

Review the script before running it

Piping a script into a shell runs it without review. To stay in control, download get_rfswift.sh from the official repository, read it, and run the local copy; or use the native packages below. See Security for the trust model.

The script also works with wget:

bash
wget -qO- "https://raw.githubusercontent.com/PentHertz/RF-Swift/refs/heads/main/get_rfswift.sh" | sh

On Debian, where the first user is not in sudo, the installer offers the fix or runs from a root shell (su -). With a recent, logged-in GitHub CLI it also offers to check the Sigstore build-provenance attestation.

Unattended installation

Every installer question can be answered up front with an environment variable:

Variable Values
RFSWIFT_CHANNEL stable, dev
RFSWIFT_INSTALL cli, workbench, both
RFSWIFT_PKG_FORMAT native, tarball
RFSWIFT_WORKBENCH_FORMAT native, appimage
RFSWIFT_INSTALL_DIR directory for a tarball install
RFSWIFT_ENGINE docker, podman, both, skip
RFSWIFT_NIX, RFSWIFT_ISOLATE, RFSWIFT_UDEV, RFSWIFT_ATTEST 1 or 0
bash
RFSWIFT_CHANNEL=stable RFSWIFT_INSTALL=both RFSWIFT_ENGINE=podman RFSWIFT_NIX=1 RFSWIFT_UDEV=1 sh get_rfswift.sh

On Linux the Workbench comes as a portable AppImage or a smaller native build. On macOS the script can also install Lima for USB passthrough.

Native Linux packages

Two packages ship with every release on the releases page: rfswift (CLI/TUI, man pages, bash/zsh/fish completions) and rfswift-workbench (desktop GUI). They pull in xhost and pactl, the two host tools every container needs; bubblewrap and a container engine are recommended.

bash
sudo apt install ./rfswift_<version>_amd64.deb            # Debian / Ubuntu
sudo dnf install ./rfswift-<version>-1.x86_64.rpm         # Fedora / RHEL
sudo pacman -U rfswift-<version>-1-x86_64.pkg.tar.zst     # Arch Linux

The packages install rfswift in /usr/bin and leave three host changes to you, asked for rather than applied:

bash
rfswift host setup           # asks each step; --yes takes the defaults
rfswift host udev            # RF Swift's udev rules only (rootless Podman and Nix need them, Docker does not)
rfswift host docker-access   # docker group + socket ACL, effective without logging out
rfswift host isolate         # Nix jail on Ubuntu 24.04+: bubblewrap and its AppArmor profile

The wizard also offers to install Docker and/or Podman from your distribution, or Nix. A packaged rfswift is upgraded with the next package; rfswift update says so instead of overwriting it. The installer removes the copies an earlier tarball install left in /usr/local/bin or ~/.rfswift/bin when you agree. Details: host.

Choosing an engine

Docker Podman Lima Nix
What it is Client-server daemon Daemonless, rootless by default Docker inside a QEMU VM (macOS) Native, pinned tool environments
Root required Daemon runs as root (join the docker group) No No No (udev rules for hardware)
USB hardware Linux; Windows via usbipd Linux (host udev rules); Windows via usbipd macOS hot-plug Direct
Best for Broad ecosystem, Windows and macOS Security-focused, air-gapped, shared machines macOS with RF hardware Laptops without a container engine, lowest latency to hardware, GPU

The benefits and trade-offs of each, in plain words: Choose your engine. RF Swift auto-detects Docker, Podman and Lima. Override with --engine, RFSWIFT_ENGINE, or engine = in config.ini. All engines can coexist and the Workbench lists their targets side by side. See engine, Podman and Nix engine.

Setting up an engine by hand

bash
curl -fsSL https://get.docker.com | sudo sh      # or your distribution's package
rfswift host docker-access                       # docker group + socket ACL, no logout needed
docker run hello-world

Kali installs docker.io from its own repository (Docker’s script refuses it). Docker Desktop on macOS and Windows needs no group setup.

Verifying downloads

bash
gh attestation verify rfswift_Linux_x86_64.tar.gz --repo PentHertz/RF-Swift

Every release asset carries a Sigstore build-provenance attestation proving it was built by the official release workflow from a specific commit. The installer runs this check when a recent, logged-in gh is available and always verifies the SHA-256 manifest.

Troubleshooting the installation

More answers in FAQ & troubleshooting.

  1. Run rfswift doctor; it points at the missing piece.
  2. Check the GitHub issues for known problems, and join the Discord.
  3. Verify the engine: docker run hello-world or podman run hello-world.
  4. Docker “permission denied” on the socket: rfswift host docker-access.
  5. Podman “/ is not a shared mount”: sudo mount --make-rshared /.
  6. Podman short-name resolution: use the full name, docker.io/penthertz/rfswift_resolute:sdr_light, or set unqualified-search-registries = ["docker.io"] in /etc/containers/registries.conf.
  7. Image pull fails with invalid username/password: a stale docker login for Docker Hub; the message names the credential file and the logout command.
  8. rfswift still runs an old copy after a package install: the installer offers to remove /usr/local/bin/rfswift and ~/.rfswift/bin; check which -a rfswift.