maqet 0.0.10

M4x0n's QEMU Tool - A Python-based QEMU automation framework for VM running

MAQET

Warning: Most of the code was written using AI. This product is a work in progress and should not be used in production environments under any circumstances.

MAQET (M4x0n's QEMU Tool) is a VM management system that implements unified API generation. Methods decorated with @api_method automatically become CLI commands, Python API methods, and configuration-driven calls.

Quick Start

Installation

pip install maqet

Optional Dependencies:

• psutil - Enhanced process management and validation (recommended)

  pip install psutil
  

  Without psutil, basic PID tracking still works but ownership validation is skipped.

Core Concept

Write once, use everywhere. A single method becomes a CLI command, Python API, and configuration option:

@api_method(cli_name="start", description="Start a virtual machine", category="vm")
def start(self, vm_id: str, detach: bool = False):
    """Start a virtual machine."""
    # Single implementation

This automatically creates:

• CLI: maqet start myvm --detach
• Python API: maqet.start("myvm", detach=True)
• Config: VM settings only (no commands in YAML)

Usage

Command Line Interface

# Create a VM
maqet add --config config.yaml --name myvm

# Start VM
maqet start myvm

# List all VMs
maqet ls

# Check VM status
maqet status myvm

# Execute QMP command
maqet qmp myvm system_powerdown

# Remove VM
maqet rm myvm --force

Python API

from maqet import Maqet

maqet = Maqet()

# Create and start VM
vm_id = maqet.add(name='myvm', memory='4G', cpu=2)
maqet.start(vm_id)

# Manage VM
status = maqet.status(vm_id)
maqet.qmp(vm_id, 'system_powerdown')
maqet.rm(vm_id, force=True)

Configuration Files

# config.yaml - VM configuration only
name: myvm
binary: /usr/bin/qemu-system-x86_64
memory: 4G
cpu: 2
storage:
  - name: hdd
    size: 20G
    type: qcow2
    interface: virtio

# Use configuration file
maqet add --config config.yaml
maqet start myvm --detach

Configuration Features:

• Deep-merge multiple config files
• Lists are concatenated (storage, network)
• Command-line args override config values
• Full QEMU argument support

See Configuration Guide for details.

Core Commands

Command	Description	Example
add	Create new VM	maqet add --config config.yaml --name myvm
start	Start VM	maqet start myvm
stop	Stop VM	maqet stop myvm --force
rm	Remove VM	maqet rm myvm --force
ls	List VMs	maqet ls --status running
status	Show VM status	maqet status myvm
apply	Apply configuration	maqet apply myvm --memory 8G
snapshot	Manage snapshots	maqet snapshot myvm create hdd snap1

QMP Commands

Command	Description	Example
qmp keys	Send key combination	maqet qmp keys myvm ctrl alt f2
qmp type	Type text to VM	maqet qmp type myvm "hello world"
qmp screendump	Take screenshot	maqet qmp screendump myvm screenshot.ppm
qmp pause	Pause VM	maqet qmp pause myvm
qmp resume	Resume VM	maqet qmp resume myvm
qmp device-add	Hot-plug device	maqet qmp device-add myvm usb-storage
qmp device-del	Hot-unplug device	maqet qmp device-del myvm usb1

Global Options

Option	Description
-v, --verbose	Increase verbosity (-v, -vv, -vvv)
-q, --quiet	Suppress non-error output
--data-dir	Override data directory
--log-file	Enable file logging

Documentation

Full Documentation

• Documentation Index - Complete documentation portal
• Architecture - Internal architecture and design
• Development - Contributing and development guides
• Deployment - Production deployment
• Reference - Technical references

Architecture

• Unified API System - Single methods generate CLI, Python API, and config
• State Management - SQLite backend with XDG compliance
• QEMU Integration - Full QMP protocol support
• Storage System - QCOW2, Raw, VirtFS support with snapshots

See QEMU Internal Architecture for details.

Development

# Run tests
python tests/run_tests.py

# Run pre-commit checks
pre-commit run --all-files

See Testing Guide for details on running tests and contributing.

Roadmap

See Roadmap and Future Features for planned improvements.

Features

• Write Once, Use Everywhere - Single method for CLI, API, and config
• XDG Compliant - Follows Linux directory standards
• Production Ready - Security hardened, tested, robust error handling
• Full QMP Support - Complete QEMU Machine Protocol integration
• Snapshot Management - Create, load, list, and delete snapshots
• Hot-plug Support - Add/remove devices while VM is running

Contributing

Contributions welcome! See Development Guide for contributing guidelines.

License

MIT License - see LICENSE file for details.