tsiry-sandratraina.com
A Docker-like CLI and HTTP API for managing headless VMs
Add README.md with project overview, features, installation instructions, and usage examples
+367
README.md
+367
README.md
···
1
+
# vmx
2
+
3
+
A powerful command-line tool and HTTP API for managing and running headless virtual machines using QEMU. Built with Deno and TypeScript, vmx provides a Docker-like experience for VM management with OCI registry support.
4
+
5
+
## Features
6
+
7
+
### 🚀 Core Functionality
8
+
9
+
- **Headless VM Management** - Run VMs in the background without GUI overhead
10
+
- **QEMU Integration** - Leverages QEMU for robust virtualization on both x86_64 and ARM64 architectures
11
+
- **Docker-like CLI** - Familiar commands for VM lifecycle management (run, start, stop, ps, rm, etc.)
12
+
- **Configuration Files** - TOML-based configuration for reproducible VM setups
13
+
- **Multiple Input Sources** - Boot from local ISOs, remote URLs, or OCI registry images
14
+
15
+
### 📦 OCI Registry Support
16
+
17
+
- **Pull & Push** - Store and retrieve VM images from OCI-compliant registries (GitHub Container Registry, Docker Hub, etc.)
18
+
- **Image Management** - List, tag, and remove local VM images
19
+
- **Authentication** - Secure login/logout for private registries
20
+
- **Cross-platform** - Automatic architecture detection and handling (amd64/arm64)
21
+
22
+
### 🌐 Networking
23
+
24
+
- **Bridge Networking** - Create and manage network bridges for VM connectivity
25
+
- **Port Forwarding** - Easy SSH and service access with flexible port mapping
26
+
- **Multiple Network Modes** - Support for various QEMU networking configurations
27
+
28
+
### 💾 Storage & Volumes
29
+
30
+
- **Volume Management** - Create, list, inspect, and delete persistent volumes
31
+
- **Multiple Disk Formats** - Support for qcow2 and raw disk images
32
+
- **Automatic Provisioning** - Volumes are created automatically from base images
33
+
- **Flexible Sizing** - Configurable disk sizes for different workloads
34
+
35
+
### 🔧 Advanced Features
36
+
37
+
- **Detached Mode** - Run VMs in the background as daemon processes
38
+
- **Live Logs** - Stream VM output and follow logs in real-time
39
+
- **VM Inspection** - Detailed information about running and stopped VMs
40
+
- **Resource Configuration** - Customizable CPU, memory, and disk settings
41
+
- **ARM64 & x86_64 Support** - Native support for both architectures with UEFI firmware
42
+
43
+
### 🌍 HTTP API
44
+
45
+
- **RESTful API** - Full-featured HTTP API for programmatic VM management
46
+
- **Bearer Authentication** - Secure API access with token-based auth
47
+
- **Machines Endpoint** - Create, start, stop, restart, and remove VMs via API
48
+
- **Images Endpoint** - List and query VM images
49
+
- **Volumes Endpoint** - Manage persistent storage volumes
50
+
- **CORS Support** - Cross-origin requests for web-based tools
51
+
52
+
## Installation
53
+
54
+
```bash
55
+
# Install with Deno
56
+
deno install -A -n vmx jsr:@tsiry/vmx
57
+
58
+
```
59
+
60
+
### Requirements
61
+
62
+
- [Deno](https://deno.com) runtime
63
+
- [QEMU](https://www.qemu.org/) installed on your system
64
+
- macOS: `brew install qemu`
65
+
- Linux: `apt-get install qemu-system` or `yum install qemu-kvm`
66
+
67
+
## Quick Start
68
+
69
+
### Initialize Configuration
70
+
71
+
Create a default VM configuration file:
72
+
73
+
```bash
74
+
vmx init
75
+
```
76
+
77
+
This creates a `vmconfig.toml` file with sensible defaults.
78
+
79
+
### Run a VM from ISO
80
+
81
+
```bash
82
+
# From a local ISO file
83
+
vmx /path/to/ubuntu.iso
84
+
85
+
# Download and run from URL
86
+
vmx https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso
87
+
88
+
# From OCI registry
89
+
vmx ghcr.io/tsirysndr/ubuntu:24.04
90
+
```
91
+
92
+
### Pull and Run from Registry
93
+
94
+
```bash
95
+
# Pull an image
96
+
vmx pull ghcr.io/tsirysndr/ubuntu:24.04
97
+
98
+
# Run the image
99
+
vmx run ghcr.io/tsirysndr/ubuntu:24.04
100
+
101
+
# Run with custom resources
102
+
vmx run ghcr.io/tsirysndr/ubuntu:24.04 -m 4G -C 4 -d
103
+
```
104
+
105
+
## Usage
106
+
107
+
### VM Lifecycle Management
108
+
109
+
```bash
110
+
# List running VMs
111
+
vmx ps
112
+
113
+
# List all VMs (including stopped)
114
+
vmx ps --all
115
+
116
+
# Start a VM
117
+
vmx start my-vm
118
+
119
+
# Stop a VM
120
+
vmx stop my-vm
121
+
122
+
# Restart a VM
123
+
vmx restart my-vm
124
+
125
+
# Remove a VM
126
+
vmx rm my-vm
127
+
128
+
# View VM logs
129
+
vmx logs my-vm
130
+
131
+
# Follow logs in real-time
132
+
vmx logs -f my-vm
133
+
134
+
# Inspect VM details
135
+
vmx inspect my-vm
136
+
```
137
+
138
+
### Image Management
139
+
140
+
```bash
141
+
# List local images
142
+
vmx images
143
+
144
+
# Pull from registry
145
+
vmx pull ghcr.io/tsirysndr/ubuntu:24.04
146
+
147
+
# Push to registry
148
+
vmx push ghcr.io/tsirysndr/my-vm:latest
149
+
150
+
# Tag an image
151
+
vmx tag my-vm ghcr.io/tsirysndr/my-vm:v1.0
152
+
153
+
# Remove an image
154
+
vmx rmi ghcr.io/tsirysndr/ubuntu:24.04
155
+
```
156
+
157
+
### Registry Authentication
158
+
159
+
```bash
160
+
# Login to registry
161
+
vmx login -u username ghcr.io
162
+
163
+
# Login with password from stdin
164
+
echo "password" | vmx login -u username ghcr.io
165
+
166
+
# Logout
167
+
vmx logout ghcr.io
168
+
```
169
+
170
+
### Volume Management
171
+
172
+
```bash
173
+
# List volumes
174
+
vmx volumes
175
+
176
+
# Create and attach a volume to VM
177
+
vmx run ubuntu:24.04 -v my-data
178
+
179
+
# Inspect a volume
180
+
vmx volume inspect my-data
181
+
182
+
# Remove a volume
183
+
vmx volume rm my-data
184
+
```
185
+
186
+
### Advanced Options
187
+
188
+
```bash
189
+
# Run with custom resources
190
+
vmx run ubuntu:24.04 \
191
+
--cpu host \
192
+
--cpus 4 \
193
+
--memory 4G \
194
+
--detach
195
+
196
+
# With port forwarding (SSH on port 2222)
197
+
vmx run ubuntu:24.04 -p 2222:22
198
+
199
+
# With bridge networking
200
+
vmx run ubuntu:24.04 --bridge br0
201
+
202
+
# With persistent disk
203
+
vmx run ubuntu:24.04 \
204
+
--image /path/to/disk.img \
205
+
--size 40G \
206
+
--disk-format qcow2
207
+
```
208
+
209
+
## Configuration File
210
+
211
+
The `vmconfig.toml` file allows you to define default VM settings:
212
+
213
+
```toml
214
+
[vm]
215
+
iso = "https://cdimage.ubuntu.com/releases/24.04/release/ubuntu-24.04.3-live-server-arm64.iso"
216
+
cpu = "host"
217
+
cpus = 2
218
+
memory = "2G"
219
+
image = "./vm-disk.img"
220
+
disk_format = "raw"
221
+
size = "20G"
222
+
223
+
[network]
224
+
bridge = "br0"
225
+
port_forward = "2222:22"
226
+
227
+
[options]
228
+
detach = false
229
+
```
230
+
231
+
## HTTP API
232
+
233
+
Start the API server:
234
+
235
+
```bash
236
+
# Start on default port (8889)
237
+
vmx serve
238
+
239
+
# Start on custom port
240
+
vmx serve --port 3000
241
+
242
+
# With custom API token
243
+
export VMX_API_TOKEN=your-secret-token
244
+
vmx serve
245
+
```
246
+
247
+
### API Endpoints
248
+
249
+
#### Machines (VMs)
250
+
251
+
- `GET /machines` - List all machines
252
+
- `GET /machines?all=true` - List all machines including stopped
253
+
- `POST /machines` - Create a new machine
254
+
- `GET /machines/:id` - Get machine details
255
+
- `DELETE /machines/:id` - Remove a machine
256
+
- `POST /machines/:id/start` - Start a machine
257
+
- `POST /machines/:id/stop` - Stop a machine
258
+
- `POST /machines/:id/restart` - Restart a machine
259
+
260
+
#### Images
261
+
262
+
- `GET /images` - List all images
263
+
- `GET /images/:id` - Get image details
264
+
265
+
#### Volumes
266
+
267
+
- `GET /volumes` - List all volumes
268
+
- `GET /volumes/:id` - Get volume details
269
+
- `POST /volumes` - Create a new volume
270
+
- `DELETE /volumes/:id` - Remove a volume
271
+
272
+
### API Authentication
273
+
274
+
All API requests require a Bearer token:
275
+
276
+
```bash
277
+
curl -H "Authorization: Bearer your-token" http://localhost:8889/machines
278
+
```
279
+
280
+
### Example API Usage
281
+
282
+
```bash
283
+
# Create a machine
284
+
curl -X POST http://localhost:8889/machines \
285
+
-H "Authorization: Bearer your-token" \
286
+
-H "Content-Type: application/json" \
287
+
-d '{
288
+
"image": "ubuntu:24.04",
289
+
"memory": "4G",
290
+
"cpus": 4,
291
+
"portForward": ["2222:22"]
292
+
}'
293
+
294
+
# Start a machine
295
+
curl -X POST http://localhost:8889/machines/{id}/start \
296
+
-H "Authorization: Bearer your-token"
297
+
298
+
# List all machines
299
+
curl http://localhost:8889/machines \
300
+
-H "Authorization: Bearer your-token"
301
+
```
302
+
303
+
## Architecture Support
304
+
305
+
vmx automatically detects and adapts to your system architecture:
306
+
307
+
- **x86_64 / amd64** - Full QEMU system emulation
308
+
- **ARM64 / aarch64** - Native Apple Silicon and ARM server support with UEFI firmware
309
+
310
+
## Examples
311
+
312
+
### Development Environment
313
+
314
+
```bash
315
+
# Initialize configuration
316
+
vmx init
317
+
318
+
# Edit vmconfig.toml to your needs
319
+
# Then start the VM
320
+
vmx
321
+
322
+
# SSH into the VM (port forwarding configured)
323
+
ssh -p 2222 user@localhost
324
+
```
325
+
326
+
### CI/CD Integration
327
+
328
+
```bash
329
+
# Pull a pre-configured image
330
+
vmx pull ghcr.io/company/test-env:latest
331
+
332
+
# Run tests in detached mode
333
+
vmx run ghcr.io/company/test-env:latest -d
334
+
335
+
# Execute tests and cleanup
336
+
vmx stop test-vm
337
+
vmx rm test-vm
338
+
```
339
+
340
+
### Multi-VM Setup
341
+
342
+
```bash
343
+
# Start database VM
344
+
vmx run postgres:14 -d -p 5432:5432 -v pgdata
345
+
346
+
# Start application VM
347
+
vmx run app:latest -d -p 8080:8080
348
+
349
+
# List all running VMs
350
+
vmx ps
351
+
```
352
+
353
+
## License
354
+
355
+
Mozilla Public License 2.0 (MPL-2.0)
356
+
357
+
Copyright (c) 2025 Tsiry Sandratraina
358
+
359
+
## Contributing
360
+
361
+
Contributions are welcome! Please feel free to submit issues and pull requests.
362
+
363
+
## Links
364
+
365
+
- [Repository](https://github.com/tsirysndr/vmx)
366
+
- [Issue Tracker](https://github.com/tsirysndr/vmx/issues)
367
+
- [JSR Package](https://jsr.io/@tsiry/vmx)