---
title: 🚀 Quick Start
weight: 2
next: /docs/guide
prev: /docs/getting-started
cascade:
  type: docs
---

# Getting Up and Running with RF Swift

This guide will help you quickly get started with RF Swift using pre-built binaries and container images.

{{< callout type="warning" >}}
**On Linux**, unless you are using Docker Desktop, you may need to use `sudo` with the `rfswift` command for operations that require elevated privileges.
{{< /callout >}}

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

{{% steps %}}

### Install RF Swift

#### Linux and macOS

The easiest way to install RF Swift on Linux or macOS is to use the installation script after downloading [the latest version here](https://github.com/PentHertz/RF-Swift/tags):
  
```bash
# Run the installation script
./install.sh
```

The `install.sh` script will:
- Install all required dependencies (Docker, BuildX, Go)
- Configure necessary services (xhost, PulseAudio)
- Set up proper permissions
- 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:

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

# Step 1 - Building the project
./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 ↗](https://github.com/PentHertz/RF-Swift/releases)
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:

```bash
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.

### 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:

```bash
rfswift images pull -i sdr_full
```

You can also specify a custom tag for the image:

```bash
rfswift images pull -i sdr_full -t my_custom_tag
```

**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)

{{< callout type="info" >}}
You can use the complete image tag `penthertz/rfswift:sdr_full` if you prefer, or change the default repository in your RF Swift profile.
{{< /callout >}}

### Run the Container

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

```bash
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`.

{{< callout type="warning" >}}
With some plateforms, some default devices may be non-existant. Your can use `bindings` or modify RF Swift's configuration file to remove the device from the mapped device list.
{{< /callout >}}

**Run Command Options:**

```bash
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') |

**Share Files with the Container:**

To share files between your host system and the container:

```bash
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:

```bash
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:

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

Multiple devices can be shared by separating them with commas:

```bash
rfswift run -i sdr_full -n my_sdr_container -s /dev/ttyUSB0:/dev/ttyUSB0,/dev/ttyACM0:/dev/ttyACM0
```


{{< callout type="info" >}}
If you plug the device after the container has started, or replug it later, you will have to stop it with command `rswift stop -c <container name>`. You can avoid this manipulation by mounting `/dev/bus/usb:/dev/bus/usb` as a volum instead with option `-b` when creating and running the container. This last manipulation may degrade the container's isolation, especially if you disable X11 manually too.
{{< /callout >}}

**Add Linux Capabilities:**

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

```bash
rfswift run -i wifi_tools -n my_wifi_container -a NET_ADMIN
```

For multiple capabilities:

```bash
rfswift run -i advanced_tools -n my_container -a NET_ADMIN,SYS_ADMIN
```

{{< callout type="warning" >}}
**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.
{{< /callout >}}

**Network Configuration:**

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

```bash
rfswift run -i sdr_full -n my_sdr_container -t bridge
```

**Privilege Levels:**

Control container privilege level:

```bash
# 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
```

**Custom Commands:**

Run a specific command instead of the default shell:

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

{{< callout type="info" >}}
Using a named container with the `-n` flag makes it much easier to restart or access the container later.
{{< /callout >}}

### 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`

{{< callout type="warning" >}}
If you encounter audio issues, you can enable audio forwarding with: `rfswift host audio enable`
This requires `pulseaudio` to be properly configured on your host system.
{{< /callout >}}

### 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:

```bash
# 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:
   ```bash
   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:
   ```bash
   # 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 some 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.

{{% /steps %}}

## Managing Existing Containers

### Restart an Existing Container

To return to a previously created container:

```bash
rfswift exec -c my_sdr_container
```

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

```bash
rfswift exec
```

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

### List Running Containers

View all RF Swift containers:

```bash
rfswift last
```

### Save Container State

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

```bash
rfswift commit -c my_sdr_container -i my_custom_image
```

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

## Creating an Alias (Linux/macOS)

For convenience, you can create an alias to run RF Swift from anywhere. If you didn't use the `install.sh` script (which creates this automatically), you can add an alias manually:

```bash
echo "alias rfswift='$(pwd)/rfswift'" >> "$HOME/.$(basename $SHELL)rc"
source "$HOME/.$(basename $SHELL)rc"
```

Replace `$(pwd)/rfswift` with the full path to your RF Swift binary.

## 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 host video enable` | Enable video forwarding |

## Next Steps

Dive right into the following section to learn more:

{{< cards >}}
  {{< card link="/docs/guide" title="Follow the Guide" icon="document-text" subtitle="Read the complete guide and learn how to use RF Swift for your daily assessments." >}}
{{< /cards >}}