Host actions

The few things RF Swift sets up on your own computer: Linux host setup, sound from your labs, and USB devices on Linux, Windows and macOS.

Advanced · 7 min read · Updated September 27, 2026

A few things happen on your own computer (the host), outside any lab: letting your user open radio hardware, bringing the sound of your labs to your speakers, and forwarding USB devices on Windows and macOS. Most of them are one-time steps, and the installer already offers them.

To see where you stand, run:

bash
rfswift doctor

It reports the state of each item below and names the command that fixes it. The Workbench’s Engine doctor has the same actions behind buttons.

In short

I want to… Command
Set up a Linux host, step by step rfswift host setup
Let my user open radio hardware (rootless Podman, Nix) rfswift host udev
Use Docker without sudo rfswift host docker-access
Hear the sound of tools in my labs rfswift host audio enable
Forward a USB radio (Windows, macOS) rfswift usb attach

Host setup on Linux

The Linux packages and the installer leave a few host changes to you on purpose: they ask for them instead of applying them silently. rfswift host setup walks through all of them, and each also exists as a single command:

bash
rfswift host setup             # udev rules, engine install, Nix, Docker access, Nix jail; --yes takes the defaults
rfswift host udev              # RF Swift's udev rules: rootless Podman and Nix environments need them, Docker does not
rfswift host docker-access     # docker group + a socket ACL, works without logging out
rfswift host isolate           # Nix --isolate jail on Ubuntu 24.04+: bubblewrap and its AppArmor profile
rfswift host devclean          # remove empty directories an old container left where a device node belongs

About the udev rules:

  • They grant group plugdev plus the logged-in user’s seat ACL, never world-writable nodes.
  • udev is reloaded on the spot. Log out and in once, then re-plug the device.

rfswift doctor reports the state of each item, and the Workbench’s Engine doctor has the same actions behind a polkit prompt. Full reference: host.

Sound from your labs

Many RF tools, such as GQRX, SDR++ and SDRAngel, play audio. For containers to reach your speakers, the host audio server (PulseAudio or PipeWire) must accept connections from them.

  • Linux and macOS: RF Swift loads the host audio server’s TCP module automatically whenever a container starts. The commands below do it by hand.
  • Windows: containers use WSLg’s audio socket and need nothing.
  • Nix environments play sound natively and don’t need this.

Turn it on

bash
rfswift host audio enable

This command:

  • detects whether PulseAudio or PipeWire is installed;
  • starts the audio server if it isn’t running;
  • loads the PulseAudio/PipeWire TCP module, listening on 127.0.0.1:34567;
  • on macOS with Lima, allows connections from the VM and Docker subnets;
  • does not need sudo or administrator rights.

You should see a confirmation like:

output
[+] Successfully loaded module-native-protocol-tcp with index 29

Turn it off

bash
rfswift host audio unload

This removes the TCP module from PulseAudio/PipeWire and closes the network port.

Use another address

bash
rfswift host audio enable -s 10.0.0.1:34567

This allows audio forwarding across a network, for example for remote connections or VMs.

Security

Opening PulseAudio/PipeWire to network interfaces introduces potential security risks. Only use custom addresses on secure networks, and consider a firewall to restrict access.

The audio commands

bash
rfswift host audio
output
Manage pulseaudio server

Usage:
  rfswift host audio [command]

Available Commands:
  enable      Enable connection
  unload      Unload TCP module from Pulseaudio server

Flags:
  -h, --help   help for audio

When there is no sound

When the audio server isn’t configured, starting a container shows this warning:

output
┌──────────────────────────────────────────────────────────────────────────────────────────────────┐
│ ⚠️  Warning                                                                                       │
├──────────────────────────────────────────────────────────────────────────────────────────────────┤
│ Warning: Unable to connect to Pulse server at 127.0.0.1:34567                                    │
│ To install Pulse server on Linux, follow these steps:                                            │
│ 1. Update your package manager: sudo apt update (for Debian-based) or sudo yum update (for Red   │
│ Hat-based).                                                                                      │
│ 2. Install Pulse server: sudo apt install pulse-server (for Debian-based) or sudo yum install    │
│ pulse-server (for Red Hat-based).                                                                │
│ After installation, enable the module with the following command as unprivileged user:           │
│ ./rfswift host audio enable                                                                      │
└──────────────────────────────────────────────────────────────────────────────────────────────────┘

It means PulseAudio/PipeWire doesn’t accept TCP connections on the default address (127.0.0.1:34567). Run rfswift host audio enable. If the problem remains:

  1. Check that PulseAudio is running:

    bash
    pulseaudio --check

  2. Restart it if needed:

    bash
    pulseaudio -k
pulseaudio --start

  3. Check the container’s PULSE_SERVER variable:

    bash
    rfswift container shell -c my_container
echo $PULSE_SERVER

    It should show tcp:127.0.0.1:34567 (or your custom address).

USB devices

How a USB radio reaches your lab depends on your system: on Linux it is shared directly, while on Windows and macOS containers run inside a VM that must receive the device first.

There is no attach step on Linux: devices are mapped when the container is created.

  • The USB tree (/dev/bus/usb) is mapped by default, so RTL-SDR and HackRF dongles work out of the box.
  • Serial devices (/dev/ttyUSB0, /dev/ttyACM0, …) are added at creation or later:
bash
rfswift container create -i sdr_full -n my_sdr -s /dev/ttyUSB0:/dev/ttyUSB0     # at creation
rfswift config bindings add -c my_sdr -d -t /dev/ttyUSB0                         # later

Serial ports are hot-pluggable on Docker and rootful Podman. Rootless Podman and Nix environments run the tools as your user and need the host udev rules: rfswift host udev. More in Files & devices and Change a container after creation.

Example: an RTL-SDR

bash
lsusb | grep RTL                                     # check the device is recognised
rfswift container create -i sdr_full -n rtlsdr_container   # the default USB mapping covers it

Once the device is attached, run your tools inside the lab, for example SDRAngel:

bash
sdrangel
SDRAngel on Windows
Running SDRAngel on Windows with an RTL-SDR attached

Next steps

Files & devicesExchange files between your computer and your labs Choose your engineWhich engine gives you USB, sound and graphics where host referenceEvery host subcommand and flagAdvanced