tsiry-sandratraina.com
A Docker-like CLI and HTTP API for managing headless VMs
1# vmx
2
3[](https://github.com/tsirysndr/vmx/actions/workflows/ci.yml)
4[](https://jsr.io/@tsiry/vmx)
5
6A powerful command-line tool and HTTP API for managing and running headless
7virtual machines using QEMU. Built with Deno and TypeScript, vmx provides a
8Docker-like experience for VM management with OCI registry support.
9
10
11
12## Features
13
14### 🚀 Core Functionality
15
16- **Headless VM Management** - Run VMs in the background without GUI overhead
17- **QEMU Integration** - Leverages QEMU for robust virtualization on both x86_64
18 and ARM64 architectures
19- **Docker-like CLI** - Familiar commands for VM lifecycle management (`run`,
20 `start`, `stop`, `ps`, `rm`, `logs`, `inspect`, etc.)
21- **Configuration Files** - TOML-based configuration for reproducible VM setups
22- **Multiple Input Sources** - Boot from local ISOs, remote URLs, or OCI
23 registry images
24
25### 📦 OCI Registry Support
26
27- **Pull & Push** - Store and retrieve VM images from OCI-compliant registries
28 (GitHub Container Registry, Docker Hub, etc.)
29- **Image Management** - List, tag, and remove local VM images
30- **Authentication** - Secure login/logout for private registries with password
31 from stdin or interactive prompt
32- **Cross-platform** - Automatic architecture detection and handling
33 (amd64/arm64)
34
35### 🐧 Quick Start Linux Distributions
36
37- **Ubuntu** - Quick shortcuts like `vmx ubuntu` with automatic download
38- **Debian** - Support for `vmx debian` with cloud-init ready images
39- **Fedora** - Run `vmx fedora:43` with CoreOS and Server editions
40- **Alpine Linux** - Lightweight `vmx alpine` for minimal setups
41- **AlmaLinux** - Enterprise-ready with `vmx alma`
42- **Rocky Linux** - RHEL-compatible via `vmx rocky`
43- **NixOS** - Declarative systems with `vmx nixos`
44- **Gentoo** - Source-based distributions with `vmx gentoo`
45- **Fedora CoreOS** - Container-optimized OS with automatic version detection
46
47All distributions automatically download the appropriate image for your
48architecture (ARM64/x86_64) and cache for subsequent runs.
49
50### 🌐 Networking
51
52- **Bridge Networking** - Create and manage network bridges for VM connectivity
53- **Port Forwarding** - Easy SSH and service access with flexible port mapping
54 (e.g., `-p 2222:22,8080:80`)
55- **Multiple Network Modes** - Support for various QEMU networking
56 configurations
57- **Automatic Bridge Setup** - Creates network bridges automatically when needed
58
59### 💾 Storage & Volumes
60
61- **Volume Management** - Create, list, inspect, and delete persistent volumes
62- **Multiple Disk Formats** - Support for qcow2 and raw disk images
63- **Automatic Provisioning** - Volumes are created automatically from base
64 images or attached to VMs
65- **Flexible Sizing** - Configurable disk sizes for different workloads (e.g.,
66 `-s 40G`)
67- **Volume Attachment** - Attach volumes to VMs with `-v` flag
68
69### ☁️ Cloud-Init Support
70
71- **Seed Image Creation** - Interactive `vmx seed` command to generate
72 cloud-init configuration
73- **User Data & Meta Data** - Full support for cloud-init user-data and
74 meta-data
75- **SSH Key Injection** - Automatically configure SSH authorized keys
76- **Custom User Setup** - Define default user, shell, and sudo permissions
77- **Instance Configuration** - Set hostname and instance ID for cloud
78 environments
79
80### 🔧 Advanced Features
81
82- **Detached Mode** - Run VMs in the background as daemon processes with `-d`
83 flag
84- **Live Logs** - Stream VM output and follow logs in real-time with `-f` flag
85- **VM Inspection** - Detailed information about running and stopped VMs
86- **Resource Configuration** - Customizable CPU (type and cores), memory, and
87 disk settings
88- **ARM64 & x86_64 Support** - Native support for both architectures with UEFI
89 firmware
90- **Install Mode** - Persist changes to VM disk image with `--install` flag
91- **Automatic Caching** - Downloaded ISOs and images are cached locally for
92 faster subsequent runs
93
94### 🌍 HTTP API
95
96- **RESTful API** - Full-featured HTTP API for programmatic VM management
97- **Bearer Authentication** - Secure API access with token-based auth
98 (auto-generated or custom via `VMX_API_TOKEN`)
99- **Machines Endpoint** - Create, start, stop, restart, and remove VMs via API
100- **Images Endpoint** - List and query VM images
101- **Volumes Endpoint** - Create, list, inspect, and delete persistent volumes
102- **CORS Support** - Cross-origin requests for web-based tools
103- **Custom Port** - Configure API server port with `--port` flag or
104 `VMX_API_PORT` env var
105
106## Installation
107
108```bash
109# Install with Deno
110 deno install -A -r -f -g jsr:@tsiry/vmx
111```
112
113### Requirements
114
115- [Deno](https://deno.com) runtime
116- [QEMU](https://www.qemu.org/) installed on your system
117 - macOS: `brew install qemu`
118 - Linux: `apt-get install qemu-system` or `yum install qemu-kvm`
119
120## Quick Start
121
122### Initialize Configuration
123
124Create a default VM configuration file:
125
126```bash
127vmx init
128```
129
130This creates a `vmconfig.toml` file with sensible defaults.
131
132### Run a VM from ISO
133
134```bash
135# From a local ISO file
136vmx /path/to/ubuntu.iso
137
138# Download and run from URL
139vmx https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso
140
141# From OCI registry
142vmx ghcr.io/tsirysndr/ubuntu:24.04
143```
144
145### Quick Start with Linux Distributions
146
147Use distribution shortcuts to quickly spin up VMs:
148
149```bash
150# Ubuntu
151vmx ubuntu
152
153# Debian
154vmx debian
155
156# Fedora
157vmx fedora
158vmx fedora-coreos
159
160# Alpine Linux
161vmx alpine
162
163# AlmaLinux
164vmx alma
165
166# Rocky Linux
167vmx rocky
168# NixOS
169vmx nixos
170
171# Gentoo
172vmx gentoo
173```
174
175These shortcuts automatically download the appropriate cloud-ready or
176installation images for your architecture (ARM64 or x86_64).
177
178### Pull and Run from Registry
179
180```bash
181# Pull an image
182vmx pull ghcr.io/tsirysndr/ubuntu:24.04
183
184# Run the image
185vmx run ghcr.io/tsirysndr/ubuntu:24.04
186
187# Run with custom resources
188vmx run ghcr.io/tsirysndr/ubuntu:24.04 -m 4G -C 4 -d
189```
190
191## Usage
192
193### VM Lifecycle Management
194
195```bash
196# List running VMs
197vmx ps
198
199# List all VMs (including stopped)
200vmx ps --all
201
202# Start a VM
203vmx start my-vm
204
205# Stop a VM
206vmx stop my-vm
207
208# Restart a VM
209vmx restart my-vm
210
211# Remove a VM
212vmx rm my-vm
213
214# View VM logs
215vmx logs my-vm
216
217# Follow logs in real-time
218vmx logs -f my-vm
219
220# Inspect VM details
221vmx inspect my-vm
222```
223
224### Image Management
225
226```bash
227# List local images
228vmx images
229
230# Pull from registry
231vmx pull ghcr.io/tsirysndr/ubuntu:24.04
232
233# Push to registry
234vmx push ghcr.io/tsirysndr/my-vm:latest
235
236# Tag an image
237vmx tag my-vm ghcr.io/tsirysndr/my-vm:v1.0
238
239# Remove an image
240vmx rmi ghcr.io/tsirysndr/ubuntu:24.04
241```
242
243### Registry Authentication
244
245```bash
246# Login to registry
247vmx login -u username ghcr.io
248
249# Login with password from stdin
250echo "password" | vmx login -u username ghcr.io
251
252# Logout
253vmx logout ghcr.io
254```
255
256### Volume Management
257
258```bash
259# List volumes
260vmx volumes
261
262# Create and attach a volume to VM
263vmx run ubuntu -v my-data
264
265# Create volume with custom size
266vmx run ubuntu -v my-data -s 50G
267
268# Inspect a volume
269vmx volume inspect my-data
270
271# Remove a volume
272vmx volume rm my-data
273```
274
275### Cloud-Init Configuration
276
277```bash
278# Create a cloud-init seed image interactively
279vmx seed
280
281# Create with custom output path
282vmx seed my-seed.iso
283
284# Run VM with cloud-init seed
285vmx ubuntu --cloud --seed seed.iso
286
287# The seed command will prompt for:
288# - Instance ID
289# - Hostname
290# - Default username
291# - User shell
292# - Sudo permissions
293# - SSH authorized keys
294```
295
296### Advanced Options
297
298```bash
299# Run with custom resources
300vmx run ubuntu:24.04 \
301 --cpu host \
302 --cpus 4 \
303 --memory 4G \
304 --detach
305
306# With multiple port forwards (SSH and HTTP)
307vmx run ubuntu:24.04 -p 2222:22,8080:80
308
309# With bridge networking
310vmx run ubuntu:24.04 --bridge br0
311
312# With persistent disk and install mode
313vmx ubuntu:24.04 \
314 --image /path/to/disk.img \
315 --size 40G \
316 --disk-format qcow2 \
317 --install
318
319# With cloud-init and volume
320vmx run ubuntu:24.04 \
321 --cloud \
322 --seed seed.iso \
323 -v data \
324 -s 50G \
325 -d
326```
327
328## Configuration File
329
330The `vmconfig.toml` file allows you to define default VM settings:
331
332```toml
333[vm]
334iso = "https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso"
335cpu = "host"
336cpus = 2
337memory = "2G"
338image = "./vm-disk.img"
339disk_format = "raw"
340size = "20G"
341
342[network]
343bridge = "br0"
344port_forward = "2222:22"
345
346[options]
347detach = false
348```
349
350## HTTP API
351
352Start the API server:
353
354```bash
355# Start on default port (8889)
356vmx serve
357
358# Start on custom port
359vmx serve --port 3000
360
361# With custom API token
362export VMX_API_TOKEN=your-secret-token
363vmx serve
364```
365
366### API Endpoints
367
368#### Machines (VMs)
369
370- `GET /machines` - List all machines
371- `GET /machines?all=true` - List all machines including stopped
372- `POST /machines` - Create a new machine
373- `GET /machines/:id` - Get machine details
374- `DELETE /machines/:id` - Remove a machine
375- `POST /machines/:id/start` - Start a machine
376- `POST /machines/:id/stop` - Stop a machine
377- `POST /machines/:id/restart` - Restart a machine
378
379#### Images
380
381- `GET /images` - List all images
382- `GET /images/:id` - Get image details
383
384#### Volumes
385
386- `GET /volumes` - List all volumes
387- `GET /volumes/:id` - Get volume details
388- `POST /volumes` - Create a new volume
389- `DELETE /volumes/:id` - Remove a volume
390
391### API Authentication
392
393All API requests require a Bearer token. The token is auto-generated on first
394run or can be set via the `VMX_API_TOKEN` environment variable:
395
396```bash
397# Auto-generated token (displayed on startup)
398vmx serve
399
400# Custom token
401export VMX_API_TOKEN=your-secret-token
402vmx serve
403
404# Custom port
405vmx serve --port 3000
406# or
407export VMX_API_PORT=3000
408vmx serve
409```
410
411API requests using the Bearer token:
412
413```bash
414curl -H "Authorization: Bearer your-token" http://localhost:8889/machines
415```
416
417### Example API Usage
418
419```bash
420# Create a machine
421curl -X POST http://localhost:8889/machines \
422 -H "Authorization: Bearer your-token" \
423 -H "Content-Type: application/json" \
424 -d '{
425 "image": "ubuntu:24.04",
426 "memory": "4G",
427 "cpus": 4,
428 "portForward": ["2222:22"],
429 "volume": "data"
430 }'
431
432# Start a machine
433curl -X POST http://localhost:8889/machines/{id}/start \
434 -H "Authorization: Bearer your-token"
435
436# List all machines
437curl http://localhost:8889/machines \
438 -H "Authorization: Bearer your-token"
439
440# Create a volume
441curl -X POST http://localhost:8889/volumes \
442 -H "Authorization: Bearer your-token" \
443 -H "Content-Type: application/json" \
444 -d '{
445 "name": "data",
446 "size": "50G"
447 }'
448```
449
450## Architecture Support
451
452vmx automatically detects and adapts to your system architecture:
453
454- **x86_64 / amd64** - Full QEMU system emulation
455- **ARM64 / aarch64** - Native Apple Silicon and ARM server support with UEFI
456 firmware
457
458## Examples
459
460### Development Environment
461
462```bash
463# Quick start with Ubuntu
464vmx ubuntu:24.04
465
466# Or initialize with custom configuration
467vmx init
468
469# Edit vmconfig.toml to your needs
470# Then start the VM
471vmx
472
473# SSH into the VM (with port forwarding configured)
474ssh -p 2222 user@localhost
475```
476
477### Cloud-Init Setup
478
479```bash
480# Create a cloud-init seed image
481vmx seed
482
483# Run Ubuntu with cloud-init
484vmx ubuntu --cloud --seed seed.iso -p 2222:22 -d
485
486# Wait for VM to boot and SSH in
487ssh -p 2222 ubuntu@localhost
488```
489
490### CI/CD Integration
491
492```bash
493# Pull a pre-configured image
494vmx pull ghcr.io/company/test-env:latest
495
496# Run tests in detached mode with volume for results
497vmx run ghcr.io/company/test-env:latest -d -v test-results
498
499# Execute tests and cleanup
500vmx stop test-vm
501vmx rm test-vm
502vmx volume rm test-results
503```
504
505### Multi-VM Setup
506
507```bash
508# Start database VM with persistent storage
509vmx run postgres -d -p 5432:5432 -v pgdata -s 20G
510
511# Start application VM with bridge networking
512vmx run app -d -p 8080:8080 --bridge br0
513
514# Start cache VM
515vmx run redis -d -p 6379:6379
516
517# List all running VMs
518vmx ps
519```
520
521### Quick Distribution Testing
522
523```bash
524# Test different distributions
525vmx alpine -m 512M -C 1
526vmx fedora-coreos
527vmx nixos-m 4G -C 2
528vmx rockylinux -p 2222:22 -d
529```
530
531## License
532
533Mozilla Public License 2.0 (MPL-2.0)
534
535Copyright (c) 2025 Tsiry Sandratraina
536
537## Contributing
538
539Contributions are welcome! Please feel free to submit issues and pull requests.
540
541## Links
542
543- [Repository](https://github.com/tsirysndr/vmx)
544- [Issue Tracker](https://github.com/tsirysndr/vmx/issues)
545- [JSR Package](https://jsr.io/@tsiry/vmx)