Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/markitobonito/cloud_repositorio/llms.txt

Use this file to discover all available pages before exploring further.

VMLauncher builds and executes QEMU command lines on remote worker nodes via SSH. For each VM interface that has a VLAN assignment, it creates a TAP device, connects it to OVS with the correct VLAN tag, and passes it to QEMU as a tap netdev. All network setup and QEMU execution are performed through RemoteExecutor.

​
VMLauncher

​
__init__(remote_executor)

​
remote_executor
RemoteExecutor
required
Used for all SSH commands to worker nodes.
from remote_executor import RemoteExecutor
from vm_launcher import VMLauncher

executor = RemoteExecutor()
launcher = VMLauncher(executor)

​
launch_vm(worker_ip, vm_dict) → (bool, str | None)

Launches a QEMU/KVM VM on the specified worker node.
​
worker_ip
string
required
IP of the worker node where the VM will run.
​
vm_dict
object
required
Serialized VM dict as produced by VM.to_dict(). The following keys are used:
Execution steps
1

TAP setup (per interface with a vlan_id)

For each interface where vlan_id is not None:
sudo ip tuntap add mode tap name tap_{vm_id}_{iface_name}
sudo ip link set dev tap_{vm_id}_{iface_name} up
sudo ovs-vsctl --may-exist add-port br-int tap_{vm_id}_{iface_name} tag={vlan_id}
If TAP creation fails, the interface is skipped (logged as an error) but the launch continues.
2

QEMU command construction

Builds the QEMU command with -enable-kvm, -m {ram_mb}, -smp {cores}, -vnc 0.0.0.0:{vnc_port - 5900}, one -netdev/-device pair per configured TAP, -drive file={qcow_image},format=qcow2, and -daemonize.
3

Launch

Executes the QEMU command over SSH with a 60-second timeout.
4

PID retrieval

Runs pgrep -f 'qemu.*{vm_name}' | head -1 to obtain the process ID.
Returns
  • (True, pid_str) — VM is running; pid_str is the string PID.
  • (False, None) — QEMU failed to start or an exception occurred.
Example QEMU command for a VM named vm1 with vm_id=1001, one interface on VLAN 101, 512 MB RAM, 1 vCPU, and VNC on port 5901: 
sudo qemu-system-x86_64 -enable-kvm -m 512 -smp 1 \
  -vnc 0.0.0.0:1 \
  -netdev tap,id=net0,ifname=tap_1001_eth1,script=no,downscript=no \
  -device e1000,netdev=net0,mac=52:54:00:03:e9:01 \
  -drive file=~/vm_images/vm1_img.qcow2,format=qcow2 \
  -daemonize

success, pid = launcher.launch_vm("10.0.10.1", vm.to_dict())
# success → True
# pid     → "4821"

​
stop_vm(worker_ip, vm_dict) → bool

Stops a running QEMU VM and cleans up its TAP devices.
​
worker_ip
string
required
Worker node where the VM is running.
​
vm_dict
object
required
Serialized VM dict. Keys used: vm_id, name, interfaces.
Steps
  1. Kills the QEMU process: sudo pkill -9 -f 'qemu.*{vm_name}'
  2. For each interface in interfaces:
sudo ovs-vsctl --if-exists del-port br-int tap_{vm_id}_{iface_name}
sudo ip link del tap_{vm_id}_{iface_name} 2>/dev/null
Returns True on success, False on exception. 
launcher.stop_vm("10.0.10.1", vm.to_dict())

​
RemoteExecutor

RemoteExecutor is the SSH transport layer used by all other API classes. It wraps subprocess.run to execute commands on remote nodes.

​
__init__(remote_user="ubuntu")

​
remote_user
string
default:"ubuntu"
SSH username used for all connections.
from remote_executor import RemoteExecutor

executor = RemoteExecutor(remote_user="ubuntu")

​
execute_direct(remote_ip, command, timeout=30) → (bool, str)

Runs an inline command on a remote host via SSH.
​
remote_ip
string
required
Target host IP address.
​
command
string
required
Shell command to execute. May be a multi-line string — each line is run sequentially in the same shell invocation.
​
timeout
integer
default:"30"
Subprocess timeout in seconds. Raises subprocess.TimeoutExpired if exceeded.
Executes ssh -o StrictHostKeyChecking=no ubuntu@{remote_ip} '{command}' via subprocess.run. Returns
  • (True, stdout) — command exited with code 0.
  • (False, stderr) — non-zero exit code or exception.
ok, output = executor.execute_direct("10.0.10.1", "hostname")
# ok     → True
# output → "worker-1\n"

​
execute(remote_ip, script_path, args=None, timeout=30) → (bool, str)

Streams a local script file to the remote shell via stdin. Useful for multi-line scripts stored on disk.
​
remote_ip
string
required
Target host IP address.
​
script_path
string
required
Path to a local script file. The file is passed to the remote shell via < {script_path}.
​
args
array
Optional list of positional arguments passed to the remote bash -s invocation.
​
timeout
integer
default:"30"
Subprocess timeout in seconds.
Executes ssh ubuntu@{remote_ip} 'bash -s [args]' < {script_path}. Returns
  • (True, stdout) on exit code 0.
  • (False, stderr) on non-zero exit code or exception.
ok, output = executor.execute(
    "10.0.10.1",
    "/opt/scripts/setup_network.sh",
    args=["eth1", "101"],
)
StrictHostKeyChecking=no is set only in execute_direct. The execute() method does not disable host key checking, so the manager host’s ~/.ssh/known_hosts must contain entries for all worker and network nodes before execute() is used in production.

Build docs developers (and LLMs) love

Get started for freeTalk to us