tsiry-sandratraina.com
A Docker-like CLI and HTTP API for managing headless VMs
feat: enhance README with detailed usage instructions and cloud-init support
+187
-24
+187
-24
README.md
+187
-24
README.md
···
13
13
- **Headless VM Management** - Run VMs in the background without GUI overhead
14
14
- **QEMU Integration** - Leverages QEMU for robust virtualization on both x86_64
15
15
and ARM64 architectures
16
-
- **Docker-like CLI** - Familiar commands for VM lifecycle management (run,
17
-
start, stop, ps, rm, etc.)
16
+
- **Docker-like CLI** - Familiar commands for VM lifecycle management (`run`,
17
+
`start`, `stop`, `ps`, `rm`, `logs`, `inspect`, etc.)
18
18
- **Configuration Files** - TOML-based configuration for reproducible VM setups
19
19
- **Multiple Input Sources** - Boot from local ISOs, remote URLs, or OCI
20
20
registry images
···
24
24
- **Pull & Push** - Store and retrieve VM images from OCI-compliant registries
25
25
(GitHub Container Registry, Docker Hub, etc.)
26
26
- **Image Management** - List, tag, and remove local VM images
27
-
- **Authentication** - Secure login/logout for private registries
27
+
- **Authentication** - Secure login/logout for private registries with password
28
+
from stdin or interactive prompt
28
29
- **Cross-platform** - Automatic architecture detection and handling
29
30
(amd64/arm64)
30
31
32
+
### 🐧 Quick Start Linux Distributions
33
+
34
+
- **Ubuntu** - Quick shortcuts like `vmx ubuntu` with automatic download
35
+
- **Debian** - Support for `vmx debian` with cloud-init ready images
36
+
- **Fedora** - Run `vmx fedora:43` with CoreOS and Server editions
37
+
- **Alpine Linux** - Lightweight `vmx alpine` for minimal setups
38
+
- **AlmaLinux** - Enterprise-ready with `vmx alma`
39
+
- **Rocky Linux** - RHEL-compatible via `vmx rocky`
40
+
- **NixOS** - Declarative systems with `vmx nixos`
41
+
- **Gentoo** - Source-based distributions with `vmx gentoo`
42
+
- **Fedora CoreOS** - Container-optimized OS with automatic version detection
43
+
44
+
All distributions automatically download the appropriate image for your
45
+
architecture (ARM64/x86_64) and cache for subsequent runs.
46
+
31
47
### 🌐 Networking
32
48
33
49
- **Bridge Networking** - Create and manage network bridges for VM connectivity
34
50
- **Port Forwarding** - Easy SSH and service access with flexible port mapping
51
+
(e.g., `-p 2222:22,8080:80`)
35
52
- **Multiple Network Modes** - Support for various QEMU networking
36
53
configurations
54
+
- **Automatic Bridge Setup** - Creates network bridges automatically when needed
37
55
38
56
### 💾 Storage & Volumes
39
57
40
58
- **Volume Management** - Create, list, inspect, and delete persistent volumes
41
59
- **Multiple Disk Formats** - Support for qcow2 and raw disk images
42
60
- **Automatic Provisioning** - Volumes are created automatically from base
43
-
images
61
+
images or attached to VMs
44
62
- **Flexible Sizing** - Configurable disk sizes for different workloads
63
+
(e.g., `-s 40G`)
64
+
- **Volume Attachment** - Attach volumes to VMs with `-v` flag
65
+
66
+
### ☁️ Cloud-Init Support
67
+
68
+
- **Seed Image Creation** - Interactive `vmx seed` command to generate
69
+
cloud-init configuration
70
+
- **User Data & Meta Data** - Full support for cloud-init user-data and
71
+
meta-data
72
+
- **SSH Key Injection** - Automatically configure SSH authorized keys
73
+
- **Custom User Setup** - Define default user, shell, and sudo permissions
74
+
- **Instance Configuration** - Set hostname and instance ID for cloud
75
+
environments
45
76
46
77
### 🔧 Advanced Features
47
78
48
-
- **Detached Mode** - Run VMs in the background as daemon processes
49
-
- **Live Logs** - Stream VM output and follow logs in real-time
79
+
- **Detached Mode** - Run VMs in the background as daemon processes with `-d`
80
+
flag
81
+
- **Live Logs** - Stream VM output and follow logs in real-time with `-f` flag
50
82
- **VM Inspection** - Detailed information about running and stopped VMs
51
-
- **Resource Configuration** - Customizable CPU, memory, and disk settings
83
+
- **Resource Configuration** - Customizable CPU (type and cores), memory, and
84
+
disk settings
52
85
- **ARM64 & x86_64 Support** - Native support for both architectures with UEFI
53
86
firmware
87
+
- **Install Mode** - Persist changes to VM disk image with `--install` flag
88
+
- **Automatic Caching** - Downloaded ISOs and images are cached locally for
89
+
faster subsequent runs
54
90
55
91
### 🌍 HTTP API
56
92
57
93
- **RESTful API** - Full-featured HTTP API for programmatic VM management
58
94
- **Bearer Authentication** - Secure API access with token-based auth
95
+
(auto-generated or custom via `VMX_API_TOKEN`)
59
96
- **Machines Endpoint** - Create, start, stop, restart, and remove VMs via API
60
97
- **Images Endpoint** - List and query VM images
61
-
- **Volumes Endpoint** - Manage persistent storage volumes
98
+
- **Volumes Endpoint** - Create, list, inspect, and delete persistent volumes
62
99
- **CORS Support** - Cross-origin requests for web-based tools
100
+
- **Custom Port** - Configure API server port with `--port` flag or
101
+
`VMX_API_PORT` env var
63
102
64
103
## Installation
65
104
···
100
139
vmx ghcr.io/tsirysndr/ubuntu:24.04
101
140
```
102
141
142
+
### Quick Start with Linux Distributions
143
+
144
+
Use distribution shortcuts to quickly spin up VMs:
145
+
146
+
```bash
147
+
# Ubuntu
148
+
vmx ubuntu
149
+
150
+
# Debian
151
+
vmx debian
152
+
153
+
# Fedora
154
+
vmx fedora
155
+
vmx fedora-coreos
156
+
157
+
# Alpine Linux
158
+
vmx alpine
159
+
160
+
# AlmaLinux
161
+
vmx alma
162
+
163
+
# Rocky Linux
164
+
vmx rocky
165
+
# NixOS
166
+
vmx nixos
167
+
168
+
# Gentoo
169
+
vmx gentoo
170
+
```
171
+
172
+
These shortcuts automatically download the appropriate cloud-ready or
173
+
installation images for your architecture (ARM64 or x86_64).
174
+
103
175
### Pull and Run from Registry
104
176
105
177
```bash
···
185
257
vmx volumes
186
258
187
259
# Create and attach a volume to VM
188
-
vmx run ubuntu:24.04 -v my-data
260
+
vmx run ubuntu -v my-data
261
+
262
+
# Create volume with custom size
263
+
vmx run ubuntu -v my-data -s 50G
189
264
190
265
# Inspect a volume
191
266
vmx volume inspect my-data
···
194
269
vmx volume rm my-data
195
270
```
196
271
272
+
### Cloud-Init Configuration
273
+
274
+
```bash
275
+
# Create a cloud-init seed image interactively
276
+
vmx seed
277
+
278
+
# Create with custom output path
279
+
vmx seed my-seed.iso
280
+
281
+
# Run VM with cloud-init seed
282
+
vmx ubuntu --cloud --seed seed.iso
283
+
284
+
# The seed command will prompt for:
285
+
# - Instance ID
286
+
# - Hostname
287
+
# - Default username
288
+
# - User shell
289
+
# - Sudo permissions
290
+
# - SSH authorized keys
291
+
```
292
+
197
293
### Advanced Options
198
294
199
295
```bash
···
204
300
--memory 4G \
205
301
--detach
206
302
207
-
# With port forwarding (SSH on port 2222)
208
-
vmx run ubuntu:24.04 -p 2222:22
303
+
# With multiple port forwards (SSH and HTTP)
304
+
vmx run ubuntu:24.04 -p 2222:22,8080:80
209
305
210
306
# With bridge networking
211
307
vmx run ubuntu:24.04 --bridge br0
212
308
213
-
# With persistent disk
214
-
vmx run ubuntu:24.04 \
309
+
# With persistent disk and install mode
310
+
vmx ubuntu:24.04 \
215
311
--image /path/to/disk.img \
216
312
--size 40G \
217
-
--disk-format qcow2
313
+
--disk-format qcow2 \
314
+
--install
315
+
316
+
# With cloud-init and volume
317
+
vmx run ubuntu:24.04 \
318
+
--cloud \
319
+
--seed seed.iso \
320
+
-v data \
321
+
-s 50G \
322
+
-d
218
323
```
219
324
220
325
## Configuration File
···
282
387
283
388
### API Authentication
284
389
285
-
All API requests require a Bearer token:
390
+
All API requests require a Bearer token. The token is auto-generated on first
391
+
run or can be set via the `VMX_API_TOKEN` environment variable:
392
+
393
+
```bash
394
+
# Auto-generated token (displayed on startup)
395
+
vmx serve
396
+
397
+
# Custom token
398
+
export VMX_API_TOKEN=your-secret-token
399
+
vmx serve
400
+
401
+
# Custom port
402
+
vmx serve --port 3000
403
+
# or
404
+
export VMX_API_PORT=3000
405
+
vmx serve
406
+
```
407
+
408
+
API requests using the Bearer token:
286
409
287
410
```bash
288
411
curl -H "Authorization: Bearer your-token" http://localhost:8889/machines
···
299
422
"image": "ubuntu:24.04",
300
423
"memory": "4G",
301
424
"cpus": 4,
302
-
"portForward": ["2222:22"]
425
+
"portForward": ["2222:22"],
426
+
"volume": "data"
303
427
}'
304
428
305
429
# Start a machine
···
309
433
# List all machines
310
434
curl http://localhost:8889/machines \
311
435
-H "Authorization: Bearer your-token"
436
+
437
+
# Create a volume
438
+
curl -X POST http://localhost:8889/volumes \
439
+
-H "Authorization: Bearer your-token" \
440
+
-H "Content-Type: application/json" \
441
+
-d '{
442
+
"name": "data",
443
+
"size": "50G"
444
+
}'
312
445
```
313
446
314
447
## Architecture Support
···
324
457
### Development Environment
325
458
326
459
```bash
327
-
# Initialize configuration
460
+
# Quick start with Ubuntu
461
+
vmx ubuntu:24.04
462
+
463
+
# Or initialize with custom configuration
328
464
vmx init
329
465
330
466
# Edit vmconfig.toml to your needs
331
467
# Then start the VM
332
468
vmx
333
469
334
-
# SSH into the VM (port forwarding configured)
470
+
# SSH into the VM (with port forwarding configured)
335
471
ssh -p 2222 user@localhost
472
+
```
473
+
474
+
### Cloud-Init Setup
475
+
476
+
```bash
477
+
# Create a cloud-init seed image
478
+
vmx seed
479
+
480
+
# Run Ubuntu with cloud-init
481
+
vmx ubuntu --cloud --seed seed.iso -p 2222:22 -d
482
+
483
+
# Wait for VM to boot and SSH in
484
+
ssh -p 2222 ubuntu@localhost
336
485
```
337
486
338
487
### CI/CD Integration
···
341
490
# Pull a pre-configured image
342
491
vmx pull ghcr.io/company/test-env:latest
343
492
344
-
# Run tests in detached mode
345
-
vmx run ghcr.io/company/test-env:latest -d
493
+
# Run tests in detached mode with volume for results
494
+
vmx run ghcr.io/company/test-env:latest -d -v test-results
346
495
347
496
# Execute tests and cleanup
348
497
vmx stop test-vm
349
498
vmx rm test-vm
499
+
vmx volume rm test-results
350
500
```
351
501
352
502
### Multi-VM Setup
353
503
354
504
```bash
355
-
# Start database VM
356
-
vmx run postgres:14 -d -p 5432:5432 -v pgdata
505
+
# Start database VM with persistent storage
506
+
vmx run postgres -d -p 5432:5432 -v pgdata -s 20G
357
507
358
-
# Start application VM
359
-
vmx run app:latest -d -p 8080:8080
508
+
# Start application VM with bridge networking
509
+
vmx run app -d -p 8080:8080 --bridge br0
510
+
511
+
# Start cache VM
512
+
vmx run redis -d -p 6379:6379
360
513
361
514
# List all running VMs
362
515
vmx ps
516
+
```
517
+
518
+
### Quick Distribution Testing
519
+
520
+
```bash
521
+
# Test different distributions
522
+
vmx alpine -m 512M -C 1
523
+
vmx fedora-coreos
524
+
vmx nixos-m 4G -C 2
525
+
vmx rockylinux -p 2222:22 -d
363
526
```
364
527
365
528
## License