Skip to content

Getting Started

This guide will get you from zero to a running 5G testbed in under 30 minutes.

Prerequisites

  • VirtualBox >= 6.1.0
  • Vagrant >= 2.3.0
  • gum (recommended): interactive TUI for testbed-config
  • Host resources: 16 GB RAM, 4+ CPU cores recommended
  • OS: Ubuntu 24.04 LTS, tested on Server and Desktop (macOS and Windows are a v1 target, currently untested)
# VirtualBox
sudo apt install -y virtualbox virtualbox-ext-pack

# Vagrant
wget -O- https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" \
  | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install -y vagrant

# gum — interactive TUI for testbed-config (recommended)
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://repo.charm.sh/apt/gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/charm.gpg
echo "deb [signed-by=/etc/apt/keyrings/charm.gpg] https://repo.charm.sh/apt/ * *" | sudo tee /etc/apt/sources.list.d/charm.list
sudo apt update && sudo apt install gum

macOS and Windows are a v1 target and currently untested; see Requirements for their planned setup.

Quick Start

git clone https://github.com/Jacobbista/kelt.git
cd kelt

# Configure the testbed (profile, edge, RAN, deploy mode)
./testbed-config

# Deploy (or 'testbed up' once the alias is installed)
./testbed-config up

testbed-config opens an interactive menu (powered by gum) where you choose:

  • Deployment profile: laptop (4 VMs, edge included) or server (3 VMs, no edge, for NUC/server)
  • Edge VM: on/off, controls whether the edge node is created and KubeEdge EdgeCore is deployed
  • Deploy mode: core_only (5G core + observability + dashboard) or full (also deploys UERANSIM on the edge)
  • Physical RAN: bridge a host NIC for a real gNB

Configuration is saved to .testbed.env and picked up automatically by vagrant up. See testbed-config for the full CLI reference.

Without gum: the tool falls back to basic terminal prompts. You can also use it non-interactively: ./testbed-config set-profile server && ./testbed-config edge off.

Server / NUC Deployment

For headless servers or Intel NUCs, see Server / NUC Deployment for hardware requirements, resource profiles, and remote access setup (reverse proxy).

What Gets Deployed

graph LR
    subgraph Master["Master  192.168.56.10"]
        M1["K3s Server"]
    end
    subgraph Worker["Worker  192.168.56.11"]
        W1["K3s Agent"]
        W2["CloudCore (KubeEdge)"]
        W3["5G Core NFs"]
        W4["MongoDB · UPF-Cloud"]
    end
    subgraph Edge["Edge  192.168.56.12 (optional)"]
        E1["EdgeCore (KubeEdge)"]
        E2["gNB + UEs (UERANSIM)"]
    end
    Worker <-->|"VXLAN N2/N3/N4/N6"| Edge
    Master --- Worker

Edge is optional. In the server profile, only master, worker, and ansible VMs are created. The edge VM is added when enabled via testbed-config edge on. Without edge, phases 3 (EdgeCore) and 6 (UERANSIM) are skipped, and OVS bridges run locally on the worker without VXLAN tunnels.

Components deployed: - K3s cluster (master + worker, optionally edge) - KubeEdge (CloudCore on worker, EdgeCore on edge if enabled) - OVS overlay networks (VXLAN tunnels when edge is present) - Open5GS 5G Core (AMF, SMF, UPF, NRF, etc.) - Observability stack (Prometheus, Loki, Grafana) - Dashboard (cluster baseline on the worker NodePort; optional dev frontend on the ansible VM)

Verify Deployment

Check Nodes

vagrant ssh master
sudo k3s kubectl get nodes

Expected output (with edge enabled): 

NAME     STATUS   ROLES                  AGE   VERSION
master   Ready    control-plane,master   10m   v1.30.6+k3s1
worker   Ready    <none>                 8m    v1.30.6+k3s1
edge     Ready    agent,edge             6m    v1.30.6+k3s1

Without edge, only master and worker appear.

kubectl on K3s VMs: K3s does not create a standalone kubectl binary, so the cluster is managed via sudo k3s kubectl. All in-VM kubectl commands throughout these docs use this form.

Check 5G Core

sudo k3s kubectl get pods -n 5g

All pods should be Running.

Check UERANSIM (if edge is enabled and deploy mode is full)

sudo k3s kubectl get pods -n 5g -l app=gnb-1
sudo k3s kubectl get pods -n 5g -l app=ue

Access the Cluster

From Host Machine

# Copy kubeconfig
vagrant ssh master -c "cat /home/vagrant/kubeconfig" > kubeconfig
export KUBECONFIG=$(pwd)/kubeconfig
kubectl get nodes

From Ansible VM

The ansible VM does not have kubectl installed. To run kubectl commands, SSH into master:

vagrant ssh master
sudo k3s kubectl get nodes

Deploy UERANSIM Manually

UERANSIM (simulated RAN) is an optional addon, off by default and requiring the edge VM. To add it later:

testbed run-phase 06-ueransim-mec

See Phase 6 for details.

Access the Dashboard

The dashboard is deployed automatically in Phase 9. Open it in your browser once provisioning completes:

Service URL
Dashboard UI (cluster baseline) http://192.168.56.11:31573
Dashboard UI (dev frontend, opt-in) http://192.168.56.13:31573
Dashboard API docs http://192.168.56.13:31880/docs
Grafana http://192.168.56.11:30300 (admin / admin5g)

See Dashboard Overview for full documentation.

Optional: 5G UE Probe (Physical UE Dongle)

If you have a physical 5G UE dongle (USB modem) and want to run experiments on your Linux host, use the 5g-probe web app. It isolates the dongle into a Linux network namespace and lets you benchmark throughput and latency with a live chart UI.

cd 5g-probe
python3 -m venv venv
./venv/bin/pip install -r requirements.txt
./run-probe.sh
# Open http://localhost:5000

run-probe.sh runs sudo with the venv interpreter by absolute path (sudo does not keep the activated venv on PATH) and starts python -m probe (code under 5g-probe/probe/).

See docs/tools/5g-probe.md for the full guide including host requirements and API reference.

Next Steps

Cleanup

# Destroy all VMs
vagrant destroy -f

# Or just stop them
vagrant halt