API Reference

Top-Level Interface

• create_image(distro, name) - Create or retrieve a VM image from the specified distribution

• with_machine(image, config, f) - Execute an async closure in a virtual machine with automatic resource cleanup

• with_pool(f) - Execute an async closure in a machine pool with automatic resource cleanup

• MachineConfig - Configuration for virtual machine resources (CPU, memory, disk)

  pub struct MachineConfig {
    pub core: u32,              // Number of CPU cores
    pub mem: u32,               // Memory size in MB
    pub disk: Option<u32>,      // Disk size in GB (optional)
    pub clear: bool,            // Clear resources after use
  }

Machine Core Interface

• Machine::new(image, config) - Create a new machine instance
• Machine::init() - Initialize the machine (first boot with cloud-init)
• Machine::spawn() - Start the machine (normal boot)
• Machine::exec(command) - Execute a command in the VM and return the output
• Machine::shutdown() - Gracefully shutdown the virtual machine
• Machine::upload(src, dst) - Upload a file or directory to the VM
• Machine::download(src, dst) - Download a file or directory from the VM
• Machine::get_ip() - Get the IP address of the VM

Machine Pool Interface

• MachinePool::new() - Create a new, empty machine pool
• MachinePool::add(name, image, config) - Add a new machine instance to the pool
• MachinePool::get(name) - Get a machine instance by the name
• MachinePool::init_all() - Initialize all machines in the pool concurrently
• MachinePool::spawn_all() - Spawn all machines in the pool concurrently
• MachinePool::shutdown_all() - Shutdown all machines in the pool concurrently

std::fs Compatible Interface

The following methods provide filesystem operations compatible with std::fs semantics:

• Machine::copy(from, to) - Copy a file within the VM
• Machine::create_dir(path) - Create a directory
• Machine::create_dir_all(path) - Create a directory and all missing parent directories
• Machine::exists(path) - Check if a path exists
• Machine::hard_link(src, dst) - Create a hard link
• Machine::metadata(path) - Get file/directory metadata
• Machine::read(path) - Read file contents as bytes
• Machine::read_dir(path) - Read directory entries
• Machine::read_link(path) - Read symbolic link target
• Machine::read_to_string(path) - Read file contents as string
• Machine::remove_dir_all(path) - Remove a directory after removing all its contents
• Machine::remove_file(path) - Remove a file
• Machine::rename(from, to) - Rename or move a file/directory
• Machine::set_permissions(path, perm) - Set file/directory permissions
• Machine::write(path, contents) - Write bytes to a file