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, 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 |
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 connect
Open an interactive shell to a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | The VM to connect to |
vmsan upload
Upload a file to a running VM.
| Argument | Required | Description |
|---|---|---|
vm-id | yes | Target VM |
local-path | yes | Local file path |
remote-path | yes | Destination path 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 |
local-path | yes | 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) |
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.