{"id":50659771,"url":"https://github.com/tsirysndr/vmx","last_synced_at":"2026-06-08T01:31:50.718Z","repository":{"id":324704965,"uuid":"1091840694","full_name":"tsirysndr/vmx","owner":"tsirysndr","description":"A Docker-like CLI and HTTP API for managing headless QEMU VMs","archived":false,"fork":false,"pushed_at":"2025-11-30T19:05:35.000Z","size":1442,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-06T01:28:18.080Z","etag":null,"topics":["alpine","cloud-init","coreos","coreos-container-linux","fedora-coreos","gentoo","nixos","oci","qemu","qemu-kvm","ubuntu","virtualization","vm"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tsirysndr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-07T15:44:48.000Z","updated_at":"2025-11-28T14:44:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tsirysndr/vmx","commit_stats":null,"previous_names":["tsirysndr/vmx"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/tsirysndr/vmx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fvmx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fvmx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fvmx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fvmx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tsirysndr","download_url":"https://codeload.github.com/tsirysndr/vmx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tsirysndr%2Fvmx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34044919,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-07T02:00:07.652Z","response_time":124,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alpine","cloud-init","coreos","coreos-container-linux","fedora-coreos","gentoo","nixos","oci","qemu","qemu-kvm","ubuntu","virtualization","vm"],"created_at":"2026-06-08T01:31:47.478Z","updated_at":"2026-06-08T01:31:50.710Z","avatar_url":"https://github.com/tsirysndr.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vmx\n\n[![ci](https://github.com/tsirysndr/vmx/actions/workflows/ci.yml/badge.svg)](https://github.com/tsirysndr/vmx/actions/workflows/ci.yml)\n[![JSR](https://jsr.io/badges/@tsiry/vmx)](https://jsr.io/@tsiry/vmx)\n\nA powerful command-line tool and HTTP API for managing and running headless\nvirtual machines using QEMU. Built with Deno and TypeScript, vmx provides a\nDocker-like experience for VM management with OCI registry support.\n\n![Preview](./.github/assets/preview.png)\n\n## Features\n\n### 🚀 Core Functionality\n\n- **Headless VM Management** - Run VMs in the background without GUI overhead\n- **QEMU Integration** - Leverages QEMU for robust virtualization on both x86_64\n  and ARM64 architectures\n- **Docker-like CLI** - Familiar commands for VM lifecycle management (`run`,\n  `start`, `stop`, `ps`, `rm`, `logs`, `inspect`, etc.)\n- **Configuration Files** - TOML-based configuration for reproducible VM setups\n- **Multiple Input Sources** - Boot from local ISOs, remote URLs, or OCI\n  registry images\n\n### 📦 OCI Registry Support\n\n- **Pull \u0026 Push** - Store and retrieve VM images from OCI-compliant registries\n  (GitHub Container Registry, Docker Hub, etc.)\n- **Image Management** - List, tag, and remove local VM images\n- **Authentication** - Secure login/logout for private registries with password\n  from stdin or interactive prompt\n- **Cross-platform** - Automatic architecture detection and handling\n  (amd64/arm64)\n\n### 🐧 Quick Start Linux Distributions\n\n- **Ubuntu** - Quick shortcuts like `vmx ubuntu` with automatic download\n- **Debian** - Support for `vmx debian` with cloud-init ready images\n- **Fedora** - Run `vmx fedora:43` with CoreOS and Server editions\n- **Alpine Linux** - Lightweight `vmx alpine` for minimal setups\n- **AlmaLinux** - Enterprise-ready with `vmx alma`\n- **Rocky Linux** - RHEL-compatible via `vmx rocky`\n- **NixOS** - Declarative systems with `vmx nixos`\n- **Gentoo** - Source-based distributions with `vmx gentoo`\n- **Fedora CoreOS** - Container-optimized OS with automatic version detection\n\nAll distributions automatically download the appropriate image for your\narchitecture (ARM64/x86_64) and cache for subsequent runs.\n\n### 🌐 Networking\n\n- **Bridge Networking** - Create and manage network bridges for VM connectivity\n- **Port Forwarding** - Easy SSH and service access with flexible port mapping\n  (e.g., `-p 2222:22,8080:80`)\n- **Multiple Network Modes** - Support for various QEMU networking\n  configurations\n- **Automatic Bridge Setup** - Creates network bridges automatically when needed\n\n### 💾 Storage \u0026 Volumes\n\n- **Volume Management** - Create, list, inspect, and delete persistent volumes\n- **Multiple Disk Formats** - Support for qcow2 and raw disk images\n- **Automatic Provisioning** - Volumes are created automatically from base\n  images or attached to VMs\n- **Flexible Sizing** - Configurable disk sizes for different workloads (e.g.,\n  `-s 40G`)\n- **Volume Attachment** - Attach volumes to VMs with `-v` flag\n\n### ☁️ Cloud-Init Support\n\n- **Seed Image Creation** - Interactive `vmx seed` command to generate\n  cloud-init configuration\n- **User Data \u0026 Meta Data** - Full support for cloud-init user-data and\n  meta-data\n- **SSH Key Injection** - Automatically configure SSH authorized keys\n- **Custom User Setup** - Define default user, shell, and sudo permissions\n- **Instance Configuration** - Set hostname and instance ID for cloud\n  environments\n\n### 🔧 Advanced Features\n\n- **Detached Mode** - Run VMs in the background as daemon processes with `-d`\n  flag\n- **Live Logs** - Stream VM output and follow logs in real-time with `-f` flag\n- **VM Inspection** - Detailed information about running and stopped VMs\n- **Resource Configuration** - Customizable CPU (type and cores), memory, and\n  disk settings\n- **ARM64 \u0026 x86_64 Support** - Native support for both architectures with UEFI\n  firmware\n- **Install Mode** - Persist changes to VM disk image with `--install` flag\n- **Automatic Caching** - Downloaded ISOs and images are cached locally for\n  faster subsequent runs\n\n### 🌍 HTTP API\n\n- **RESTful API** - Full-featured HTTP API for programmatic VM management\n- **Bearer Authentication** - Secure API access with token-based auth\n  (auto-generated or custom via `VMX_API_TOKEN`)\n- **Machines Endpoint** - Create, start, stop, restart, and remove VMs via API\n- **Images Endpoint** - List and query VM images\n- **Volumes Endpoint** - Create, list, inspect, and delete persistent volumes\n- **CORS Support** - Cross-origin requests for web-based tools\n- **Custom Port** - Configure API server port with `--port` flag or\n  `VMX_API_PORT` env var\n\n## Installation\n\n```bash\n# Install with Deno\n deno install -A -r -f -g jsr:@tsiry/vmx\n```\n\n### Requirements\n\n- [Deno](https://deno.com) runtime\n- [QEMU](https://www.qemu.org/) installed on your system\n  - macOS: `brew install qemu`\n  - Linux: `apt-get install qemu-system` or `yum install qemu-kvm`\n\n## Quick Start\n\n### Initialize Configuration\n\nCreate a default VM configuration file:\n\n```bash\nvmx init\n```\n\nThis creates a `vmconfig.toml` file with sensible defaults.\n\n### Run a VM from ISO\n\n```bash\n# From a local ISO file\nvmx /path/to/ubuntu.iso\n\n# Download and run from URL\nvmx https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso\n\n# From OCI registry\nvmx ghcr.io/tsirysndr/ubuntu:24.04\n```\n\n### Quick Start with Linux Distributions\n\nUse distribution shortcuts to quickly spin up VMs:\n\n```bash\n# Ubuntu\nvmx ubuntu\n\n# Debian  \nvmx debian\n\n# Fedora\nvmx fedora\nvmx fedora-coreos\n\n# Alpine Linux\nvmx alpine\n\n# AlmaLinux\nvmx alma\n\n# Rocky Linux\nvmx rocky\n# NixOS\nvmx nixos\n\n# Gentoo\nvmx gentoo\n```\n\nThese shortcuts automatically download the appropriate cloud-ready or\ninstallation images for your architecture (ARM64 or x86_64).\n\n### Pull and Run from Registry\n\n```bash\n# Pull an image\nvmx pull ghcr.io/tsirysndr/ubuntu:24.04\n\n# Run the image\nvmx run ghcr.io/tsirysndr/ubuntu:24.04\n\n# Run with custom resources\nvmx run ghcr.io/tsirysndr/ubuntu:24.04 -m 4G -C 4 -d\n```\n\n## Usage\n\n### VM Lifecycle Management\n\n```bash\n# List running VMs\nvmx ps\n\n# List all VMs (including stopped)\nvmx ps --all\n\n# Start a VM\nvmx start my-vm\n\n# Stop a VM\nvmx stop my-vm\n\n# Restart a VM\nvmx restart my-vm\n\n# Remove a VM\nvmx rm my-vm\n\n# View VM logs\nvmx logs my-vm\n\n# Follow logs in real-time\nvmx logs -f my-vm\n\n# Inspect VM details\nvmx inspect my-vm\n```\n\n### Image Management\n\n```bash\n# List local images\nvmx images\n\n# Pull from registry\nvmx pull ghcr.io/tsirysndr/ubuntu:24.04\n\n# Push to registry\nvmx push ghcr.io/tsirysndr/my-vm:latest\n\n# Tag an image\nvmx tag my-vm ghcr.io/tsirysndr/my-vm:v1.0\n\n# Remove an image\nvmx rmi ghcr.io/tsirysndr/ubuntu:24.04\n```\n\n### Registry Authentication\n\n```bash\n# Login to registry\nvmx login -u username ghcr.io\n\n# Login with password from stdin\necho \"password\" | vmx login -u username ghcr.io\n\n# Logout\nvmx logout ghcr.io\n```\n\n### Volume Management\n\n```bash\n# List volumes\nvmx volumes\n\n# Create and attach a volume to VM\nvmx run ubuntu -v my-data\n\n# Create volume with custom size\nvmx run ubuntu -v my-data -s 50G\n\n# Inspect a volume\nvmx volume inspect my-data\n\n# Remove a volume\nvmx volume rm my-data\n```\n\n### Cloud-Init Configuration\n\n```bash\n# Create a cloud-init seed image interactively\nvmx seed\n\n# Create with custom output path\nvmx seed my-seed.iso\n\n# Run VM with cloud-init seed\nvmx ubuntu --cloud --seed seed.iso\n\n# The seed command will prompt for:\n# - Instance ID\n# - Hostname\n# - Default username\n# - User shell\n# - Sudo permissions\n# - SSH authorized keys\n```\n\n### Advanced Options\n\n```bash\n# Run with custom resources\nvmx run ubuntu:24.04 \\\n  --cpu host \\\n  --cpus 4 \\\n  --memory 4G \\\n  --detach\n\n# With multiple port forwards (SSH and HTTP)\nvmx run ubuntu:24.04 -p 2222:22,8080:80\n\n# With bridge networking\nvmx run ubuntu:24.04 --bridge br0\n\n# With persistent disk and install mode\nvmx ubuntu:24.04 \\\n  --image /path/to/disk.img \\\n  --size 40G \\\n  --disk-format qcow2 \\\n  --install\n\n# With cloud-init and volume\nvmx run ubuntu:24.04 \\\n  --cloud \\\n  --seed seed.iso \\\n  -v data \\\n  -s 50G \\\n  -d\n```\n\n## Configuration File\n\nThe `vmconfig.toml` file allows you to define default VM settings:\n\n```toml\n[vm]\niso = \"https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso\"\ncpu = \"host\"\ncpus = 2\nmemory = \"2G\"\nimage = \"./vm-disk.img\"\ndisk_format = \"raw\"\nsize = \"20G\"\n\n[network]\nbridge = \"br0\"\nport_forward = \"2222:22\"\n\n[options]\ndetach = false\n```\n\n## HTTP API\n\nStart the API server:\n\n```bash\n# Start on default port (8889)\nvmx serve\n\n# Start on custom port\nvmx serve --port 3000\n\n# With custom API token\nexport VMX_API_TOKEN=your-secret-token\nvmx serve\n```\n\n### API Endpoints\n\n#### Machines (VMs)\n\n- `GET /machines` - List all machines\n- `GET /machines?all=true` - List all machines including stopped\n- `POST /machines` - Create a new machine\n- `GET /machines/:id` - Get machine details\n- `DELETE /machines/:id` - Remove a machine\n- `POST /machines/:id/start` - Start a machine\n- `POST /machines/:id/stop` - Stop a machine\n- `POST /machines/:id/restart` - Restart a machine\n\n#### Images\n\n- `GET /images` - List all images\n- `GET /images/:id` - Get image details\n\n#### Volumes\n\n- `GET /volumes` - List all volumes\n- `GET /volumes/:id` - Get volume details\n- `POST /volumes` - Create a new volume\n- `DELETE /volumes/:id` - Remove a volume\n\n### API Authentication\n\nAll API requests require a Bearer token. The token is auto-generated on first\nrun or can be set via the `VMX_API_TOKEN` environment variable:\n\n```bash\n# Auto-generated token (displayed on startup)\nvmx serve\n\n# Custom token\nexport VMX_API_TOKEN=your-secret-token\nvmx serve\n\n# Custom port\nvmx serve --port 3000\n# or\nexport VMX_API_PORT=3000\nvmx serve\n```\n\nAPI requests using the Bearer token:\n\n```bash\ncurl -H \"Authorization: Bearer your-token\" http://localhost:8889/machines\n```\n\n### Example API Usage\n\n```bash\n# Create a machine\ncurl -X POST http://localhost:8889/machines \\\n  -H \"Authorization: Bearer your-token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"image\": \"ubuntu:24.04\",\n    \"memory\": \"4G\",\n    \"cpus\": 4,\n    \"portForward\": [\"2222:22\"],\n    \"volume\": \"data\"\n  }'\n\n# Start a machine\ncurl -X POST http://localhost:8889/machines/{id}/start \\\n  -H \"Authorization: Bearer your-token\"\n\n# List all machines\ncurl http://localhost:8889/machines \\\n  -H \"Authorization: Bearer your-token\"\n\n# Create a volume\ncurl -X POST http://localhost:8889/volumes \\\n  -H \"Authorization: Bearer your-token\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"data\",\n    \"size\": \"50G\"\n  }'\n```\n\n## Architecture Support\n\nvmx automatically detects and adapts to your system architecture:\n\n- **x86_64 / amd64** - Full QEMU system emulation\n- **ARM64 / aarch64** - Native Apple Silicon and ARM server support with UEFI\n  firmware\n\n## Examples\n\n### Development Environment\n\n```bash\n# Quick start with Ubuntu\nvmx ubuntu:24.04\n\n# Or initialize with custom configuration\nvmx init\n\n# Edit vmconfig.toml to your needs\n# Then start the VM\nvmx\n\n# SSH into the VM (with port forwarding configured)\nssh -p 2222 user@localhost\n```\n\n### Cloud-Init Setup\n\n```bash\n# Create a cloud-init seed image\nvmx seed\n\n# Run Ubuntu with cloud-init\nvmx ubuntu --cloud --seed seed.iso -p 2222:22 -d\n\n# Wait for VM to boot and SSH in\nssh -p 2222 ubuntu@localhost\n```\n\n### CI/CD Integration\n\n```bash\n# Pull a pre-configured image\nvmx pull ghcr.io/company/test-env:latest\n\n# Run tests in detached mode with volume for results\nvmx run ghcr.io/company/test-env:latest -d -v test-results\n\n# Execute tests and cleanup\nvmx stop test-vm\nvmx rm test-vm\nvmx volume rm test-results\n```\n\n### Multi-VM Setup\n\n```bash\n# Start database VM with persistent storage\nvmx run postgres -d -p 5432:5432 -v pgdata -s 20G\n\n# Start application VM with bridge networking\nvmx run app -d -p 8080:8080 --bridge br0\n\n# Start cache VM\nvmx run redis -d -p 6379:6379\n\n# List all running VMs\nvmx ps\n```\n\n### Quick Distribution Testing\n\n```bash\n# Test different distributions\nvmx alpine -m 512M -C 1\nvmx fedora-coreos \nvmx nixos-m 4G -C 2 \nvmx rockylinux -p 2222:22 -d\n```\n\n## License\n\nMozilla Public License 2.0 (MPL-2.0)\n\nCopyright (c) 2025 Tsiry Sandratraina\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## Links\n\n- [Repository](https://github.com/tsirysndr/vmx)\n- [Issue Tracker](https://github.com/tsirysndr/vmx/issues)\n- [JSR Package](https://jsr.io/@tsiry/vmx)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsirysndr%2Fvmx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftsirysndr%2Fvmx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftsirysndr%2Fvmx/lists"}