API
CLI Reference
Complete reference for all vmsan commands and flags
Global flags
| Flag | Description |
|---|---|
--json | Output structured JSON |
--verbose | Show detailed debug output |
Commands
vmsan create
Create and start a new microVM.
| Flag | Type | Default | Description |
|---|---|---|---|
--vcpus | string | 1 | Number of vCPUs |
--memory | string | 128 | Memory in MiB |
--runtime | string | base | Runtime label (base, node22, node24, python3.13) |
--disk | string | 10gb | Root disk size |
--from-image | string | — | Build rootfs from a Docker/OCI image |
--kernel | string | — | Path to kernel image (auto-detected if omitted) |
--rootfs | string | — | Path to rootfs image (auto-detected if omitted) |
--timeout | string | — | Auto-shutdown timeout (e.g. 1h, 30m, 2h30m) |
--project | string | — | Project label for grouping VMs |
--snapshot | string | — | Snapshot ID to restore from |
--publish-port | string | — | Ports to forward (comma-separated) |
--network-policy | string | allow-all | Network mode: allow-all, deny-all, custom |
--allowed-domain | string | — | Allowed domains (comma-separated, wildcard *) |
--allowed-cidr | string | — | Allowed CIDR ranges (comma-separated) |
--denied-cidr | string | — | Denied CIDR ranges (comma-separated) |
--bandwidth | string | — | Max bandwidth (e.g. 50mbit) |
--no-seccomp | boolean | false | Disable seccomp-bpf filter |
--no-pid-ns | boolean | false | Disable PID namespace isolation |
--no-cgroup | boolean | false | Disable cgroup resource limits |
--no-netns | boolean | false | Disable per-VM network namespace |
--connect | boolean | false | Auto-connect to shell after creation |
--silent | boolean | false | Suppress all output |
--from-image and --connect are mutually exclusive. Custom images do not include the agent, so connect, exec, upload, and download are unavailable for VMs created with --from-image.vmsan list
List all VMs. Alias: ls.
vmsan start
Start a stopped VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to start |
vmsan stop
Stop a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to stop |
vmsan remove
Remove a VM and its chroot directory. Alias: rm.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to remove |
vmsan exec
Execute a command inside a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to run the command in |
command | yes | Command to execute, followed by args |
| Flag | Type | Default | Description |
|---|---|---|---|
--sudo | boolean | false | Run as root |
-i, --interactive | boolean | false | Interactive shell mode (PTY) |
-w, --workdir | string | — | Working directory inside the VM |
-e, --env | string | — | Environment variable (KEY=VAL), repeatable |
-t, --tty | boolean | false | Allocate a pseudo-TTY (compatibility) |
--no-extend-timeout | boolean | false | Skip timeout extension (interactive only) |
vmsan connect
Open an interactive shell to a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to connect to |
| Flag | Type | Default | Description |
|---|---|---|---|
-s, --session | string | — | Attach to an existing shell session ID |
vmsan upload
Upload one or more local files to a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | Target VM |
files... | yes | One or more local file paths |
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dest | string | /root | Destination directory inside the VM |
vmsan download
Download a file from a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | Source VM |
remote-path | yes | File path inside the VM |
| Flag | Type | Default | Description |
|---|---|---|---|
-d, --dest | string | basename of remote path in cwd | Local destination path |
vmsan network
Update the network policy on a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to update |
| Flag | Type | Required | Description |
|---|---|---|---|
--network-policy | string | yes | Network mode: allow-all, deny-all, custom |
--allowed-domain | string | no | Allowed domains (comma-separated) |
--allowed-cidr | string | no | Allowed CIDR ranges (comma-separated) |
--denied-cidr | string | no | Denied CIDR ranges (comma-separated) |
vmsan snapshot
Manage VM snapshots. This is a command group with subcommands.
vmsan snapshot create
Create a snapshot of a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to snapshot |
| Flag | Type | Default | Description |
|---|---|---|---|
--no-resume | boolean | false | Keep VM paused after snapshot (default: auto-resume) |
vmsan snapshot list
List all snapshots. Alias: ls.
vmsan snapshot delete
Delete one or more snapshots. Alias: rm.
| Argument | Required | Description |
|---|---|---|
snapshot-id... | yes | One or more snapshot IDs |
vmsan doctor
Check system prerequisites and vmsan installation health.
Runs 8 diagnostic checks across three categories:
- System — KVM availability, disk space, default network interface
- Binaries — Firecracker, Jailer, Agent
- Images — Kernel, base rootfs
Returns exit code 1 if any check fails. Supports --json for scripted health checks.
Programmatic API
vmsan also exports a TypeScript API for programmatic use:
example.ts
import { VMService, vmsanPaths, FirecrackerClient } from "vmsan";
const paths = vmsanPaths();
const service = new VMService(paths);
Key exports include VMService, FirecrackerClient, AgentClient, NetworkManager, Jailer, and ShellSession.