Docker Images

GR-MCP uses Docker images for running flowgraphs in isolation with headless GUI support.

Base Images

gnuradio-runtime:latest

The base runtime image for running flowgraphs.

Includes:

• GNU Radio 3.10.x
• Xvfb (virtual framebuffer for headless X11)
• VNC server (optional visual debugging)
• ImageMagick (screenshot capture)
• 12 preinstalled OOT modules (osmosdr, satellites, gsm, etc.)

Build:

docker build -f docker/Dockerfile.gnuradio-runtime \
  -t gnuradio-runtime:latest docker/

gnuradio-coverage:latest

Extended runtime image with Python coverage support.

Includes:

• Everything in gnuradio-runtime
• python3-coverage package

Build:

docker build -f docker/Dockerfile.gnuradio-coverage \
  -t gnuradio-coverage:latest docker/

OOT Module Images

When you install an OOT module via install_oot_module(), GR-MCP creates a new image.

Naming Convention

gnuradio-{module_name}-runtime:latest

Examples:

• gnuradio-lora_sdr-runtime:latest
• gnuradio-adsb-runtime:latest
• gnuradio-ieee802_11-runtime:latest

Build Process

1. Clones the git repository
2. Builds with cmake in a multi-stage Docker build
3. Installs into the runtime image
4. Tags with the module name

Combo Images

For flowgraphs requiring multiple OOT modules, GR-MCP creates combo images.

Naming Convention

gr-combo-{module1}-{module2}-...:latest

Modules are sorted alphabetically in the name.

Examples:

• gr-combo-adsb-lora_sdr:latest
• gr-combo-adsb-ieee802_11-lora_sdr:latest

Combo Keys

Combo images are tracked by a combo_key:

combo:{module1}+{module2}+...

Examples:

• combo:adsb+lora_sdr
• combo:adsb+ieee802_11+lora_sdr

Container Configuration

When launching a flowgraph, containers are configured with:

Feature	Configuration
Display	DISPLAY=:99 (Xvfb)
X11	Xvfb runs on :99
VNC	Port 5900 (if enabled)
XML-RPC	Dynamic port mapping
ControlPort	Port 9090 (if enabled)
Workdir	/flowgraph
Network	Host network mode

Labels

GR-MCP containers are tagged with labels for management:

gr-mcp=true
gr-mcp-name={container_name}
gr-mcp-xmlrpc-port={port}
gr-mcp-vnc={enabled}
gr-mcp-controlport={enabled}
gr-mcp-controlport-port={port}
gr-mcp-coverage={enabled}

Volume Mounts

Host Path	Container Path	Purpose
Flowgraph file	/flowgraph/{name}.py	Flowgraph script
Coverage dir	/coverage	Coverage data output

Hardware Access

To access SDR hardware inside containers, pass device paths:

USB Devices

launch_flowgraph(
    flowgraph_path="...",
    device_paths=["/dev/bus/usb"]
)

Grants access to all USB devices (RTL-SDR, HackRF, Airspy, etc.)

Serial Devices

launch_flowgraph(
    flowgraph_path="...",
    device_paths=["/dev/ttyUSB0"]
)

Grants access to specific serial ports (USRP, etc.)

Multiple Devices

launch_flowgraph(
    flowgraph_path="...",
    device_paths=["/dev/bus/usb", "/dev/ttyUSB0"]
)

Caution

The container runs with privileged access when device paths are specified. Ensure you trust the flowgraph code.

Image Management

List Images

# List OOT images
list_oot_images()

# List combo images
list_combo_images()

Remove Images

# Remove single-module image
remove_oot_image(module_name="lora_sdr")

# Remove combo image
remove_combo_image(combo_key="combo:adsb+lora_sdr")

Docker Commands

# List all GR-MCP images
docker images | grep -E "gnuradio-|gr-combo"

# Remove all GR-MCP images
docker images --format '{{.Repository}}:{{.Tag}}' | \
  grep -E "gnuradio-|gr-combo" | xargs docker rmi

# List all GR-MCP containers
docker ps -a --filter "label=gr-mcp=true"

# Remove all stopped GR-MCP containers
docker container prune --filter "label=gr-mcp=true"