docs / getting-started

Getting Started

Everything you need to deploy your first cyber range from scratch.

Prerequisites

Operator workstation

▸OS: Ubuntu 22.04 LTS+ or Debian 13+ (Desktop or Server)
▸Python: 3.10 or higher
▸Packages: python3-venv, git
▸SSH access to the Proxmox host (key-based recommended)

Proxmox host

▸Proxmox VE 8.x (tested on 8.1+)
▸Storage: At least one storage pool configured (local-lvm or similar)
▸Network: Management interface reachable from the operator workstation
▸Resources: Minimum 32 GB RAM and 200 GB storage for demo_lab

Quick Start

Install the Python virtual environment dependency, clone the repository, and launch the interactive setup wizard.

sudo apt-get update && sudo apt-get install -y python3-venv git
mkdir -p $HOME/range42 && cd $HOME/range42
git clone https://github.com/range42/range42.git
cd range42
./range42-init.py

The wizard will open a terminal UI and walk you through every step. No manual ansible.cfg or inventory editing required.

Setup Wizard

The wizard (range42-init.py) is a Textual TUI that guides you through the complete bootstrap process.

Preflight checks

Verifies Python version, required packages, and SSH connectivity to your Proxmox host.

Proxmox connection

Enter your Proxmox host IP, API credentials, and select your storage pool and network bridge.

Codename & scenario

Assign a codename to your deployment (e.g. alpha) and select a scenario (e.g. demo_lab).

Deploy

The wizard generates the Ansible inventory and vault, then runs the full deployment pipeline. Grab a coffee.

Daily Operations

After deployment, the range42-context shell function on the deployer host manages your workspaces.

# Switch to a workspace
range42-context use alpha

# List all workspaces
range42-context list

# Deploy a scenario
range42-context deploy demo_lab

# Check status
range42-context status

# SSH into a VM
range42-context ssh vuln-01

Troubleshooting

Wizard fails at preflight

Ensure python3-venv is installed and your SSH key is authorised on the Proxmox host.

Ansible playbook times out

Check network connectivity between the operator workstation and the Proxmox host. Verify the Proxmox API token has sufficient permissions.

VM cloning fails

Confirm your storage pool has enough free space and that the required base templates exist on the Proxmox host.

Found a bug or need help?

Open an issue on github.com/range42/range42. For catalog-specific issues (missing CVE, vulnerable service), use range42-catalog.