Commands reference¶

Global flags¶

Flag	Description
`--output json`, `-o json`	Output in JSON format (works on list and status commands)
`--yes`, `-y`	Skip confirmation prompts (e.g. on delete)

Aliases¶

Several commands have short aliases for convenience:

Alias	Command
`sistemo machine ls`	`sistemo machine list`
`sistemo machine rm`	`sistemo machine delete`
`sistemo machine show`	`sistemo machine status`

The vm alias

sistemo vm is a permanent alias for sistemo machine. All sistemo vm ... commands continue to work exactly as before — vm and machine are fully interchangeable.

System¶

Command	Description
`sistemo up`	Start the daemon
`sistemo install`	Create `~/.sistemo`, download Firecracker + kernel, generate SSH key
`sistemo install --upgrade`	Re-download Firecracker and kernel
`sistemo --version`, `sistemo -v`	Print version and exit
`sistemo ssh-key`	Print SSH public key
`sistemo doctor`	Run diagnostic checks on your installation
`sistemo history`	Show operation history (audit log)
`sistemo completion bash\\|zsh\\|fish`	Generate shell completion scripts

Machines¶

Command	Description
`sistemo machine deploy <image>`	Create and start a machine
`sistemo machine list`	List machines
`sistemo machine start <name\\|id>`	Start a stopped machine
`sistemo machine stop <name\\|id>`	Stop a running machine (keeps disk)
`sistemo machine restart <name\\|id>`	Restart a machine (stop + start)
`sistemo machine delete <name\\|id>`	Delete a machine (removes disk)
`sistemo machine delete <name\\|id> -y`	Delete a machine, skip confirmation
`sistemo machine delete <name\\|id> --preserve-storage`	Delete a machine but keep data volumes
`sistemo machine terminal <name\\|id>`	Open browser terminal
`sistemo machine ssh <name\\|id>`	SSH into a machine (interactive)
`sistemo machine exec <name\\|id> <cmd>`	Run a command in a machine (non-interactive)
`sistemo machine logs <name\\|id>`	Tail Firecracker log
`sistemo machine status <name\\|id>`	Show machine details (IP, ports, resources)
`sistemo machine expose <name\\|id> --port P`	Expose a machine port on the host
`sistemo machine unexpose <name\\|id> --port P`	Remove a port expose rule

Deploy flags¶

Flag	Description	Default
`--name`	Set a custom machine name	derived from image
`--vcpus`	Number of vCPUs	`2`
`--memory`	Memory size (e.g. `512`, `2G`, `2GB`)	`512M`
`--storage`	Root disk size (e.g. `2048`, `10G`)	`2G`
`--attach`	Attach volumes by ID or name (comma-separated)	—
`--volume`	Boot from an existing volume (skip image)	—
`--expose`	Expose port (`hostPort:machinePort` or just `port`)	—
`--network`	Join a named network (see Networking)	default bridge

Image resolution¶

sistemo machine deploy <image> resolves the image argument in this order:

Priority	Match	Example
1	URL (`http://` or `https://`)	`sistemo machine deploy https://example.com/debian.rootfs.ext4`
2	Local file (contains `/` or ends `.ext4`)	`sistemo machine deploy ./my-image.rootfs.ext4`
3	Cached (in `~/.sistemo/images/`)	Previously pulled or built images
4	Registry (`registry.sistemo.io`)	`sistemo machine deploy debian` downloads automatically
5	Not found	Error with suggestions

Deploy examples¶

# Deploy from registry (auto-downloads if not cached)
sistemo machine deploy debian
# or: sistemo vm deploy debian

# Local rootfs file
sistemo machine deploy ./my-image.rootfs.ext4

# Custom resources and name
sistemo machine deploy debian --vcpus 4 --memory 2G --storage 10G --name dev-box

# With port expose
sistemo machine deploy debian --expose 80 --expose 8080:3000

# With a persistent volume
sistemo machine deploy debian --attach=mydata

# Boot from an existing volume
sistemo machine deploy --volume web-root --name web2

# From URL
sistemo machine deploy https://example.com/images/debian.rootfs.ext4

Exec examples¶

sistemo machine exec myvm "uname -a"
sistemo machine exec myvm df -h
sistemo machine exec myvm -- ls -la /tmp

Note

Flags in the command (like -h) are passed to the machine, not to sistemo.

Volumes¶

Command	Description
`sistemo volume create <size> [--name NAME]`	Create a volume (e.g. `5G`, `512M`)
`sistemo volume list`	List all volumes with status and attachments
`sistemo volume delete <name\\|id>`	Delete a volume (must not be attached)
`sistemo volume resize <name\\|id> <new-size>`	Grow a volume (machine must be stopped, grow only)
`sistemo machine volume attach <machine> <volume>`	Attach a volume to a stopped machine
`sistemo machine volume detach <machine> <volume>`	Detach a volume from a stopped machine

Images¶

Command	Description
`sistemo image list`	List local and remote images (fetches registry index)
`sistemo image pull <name>`	Download an image from `registry.sistemo.io`
`sistemo image build <docker-image>`	Build rootfs from any Docker image (requires root)
`sistemo image delete <name>`	Delete a cached image from `~/.sistemo/images/`

Image build examples¶

# Build from Docker Hub images — openssh-server auto-installed
sudo sistemo image build nginx:latest
sudo sistemo image build ubuntu:24.04
sudo sistemo image build node:20
sudo sistemo image build python:3.12

# Build from a custom Dockerfile
docker build -t myapp .
sudo sistemo image build myapp

# Custom rootfs size (default 2 GB)
ROOTFS_MB=1024 sudo sistemo image build myapp

Info

sistemo image build automatically installs openssh-server via chroot if the Docker image doesn't have it. Supports apt, apk, dnf, yum, and pacman. See Building images for details.

Registry¶

Images are pulled from registry.sistemo.io by default. Override with SISTEMO_REGISTRY_URL:

SISTEMO_REGISTRY_URL=https://my-registry.example.com/images/ sistemo machine deploy debian

Service¶

Command	Description
`sistemo service install`	Install and start as systemd service
`sistemo service uninstall`	Stop and remove systemd service
`sistemo service status`	Show service status
`sistemo service logs`	Follow service logs

Networks¶

Command	Description
`sistemo network create <name>`	Create an isolated network
`sistemo network create <name> --subnet X`	Create with a custom subnet
`sistemo network list`	List all networks
`sistemo network delete <name>`	Delete a network (must have no machines)

Machines deployed with --network <name> join that network and can reach each other. Machines on different networks are fully isolated. See Networking for details.

sistemo network create production
sistemo machine deploy debian --name app --network production
sistemo machine deploy debian --name postgres --network production
# app and postgres can reach each other; machines on other networks cannot

Admin¶

Command	Description
`sistemo admin reset-password`	Reset the dashboard admin password (interactive prompt)

Configuration¶

Command	Description
`sistemo config`	Show effective merged configuration

See Configuration for ~/.sistemo/config.yml options.

Diagnostics¶

Doctor¶

sistemo doctor

Runs 10 diagnostic checks on your installation:

  ok    KVM available (/dev/kvm exists and writable)
  ok    Firecracker binary found (Firecracker v1.14.2)
  ok    Kernel image found
  ok    SSH key pair exists
  ok    Bridge sistemo0 is up (10.200.0.1/16)
  ok    nftables MASQUERADE rule active
  ok    Daemon reachable at http://127.0.0.1:7777 (3 machines running)
  ok    Disk space: 42 GB free
  ok    SQLite database healthy (wal mode, 3 machines, 2 port rules)
  FAIL  HOST_API_KEY not set

9/10 checks passed, 1 failed

Run as root for full checks (nftables requires root):

sudo sistemo doctor

History¶

sistemo history                     # last 20 operations
sistemo history --limit 50          # last 50
sistemo history --action create     # filter by action
sistemo history --target myvm       # filter by machine name or ID

Shows a log of all operations (create, delete, stop, start, expose, unexpose, network.create, network.delete).

Shell completions¶

# Bash
sistemo completion bash > /etc/bash_completion.d/sistemo

# Zsh
sistemo completion zsh > "${fpath[1]}/_sistemo"

# Fish
sistemo completion fish > ~/.config/fish/completions/sistemo.fish

Tab-completion works for commands, flags, and machine names.

Note

See Machines, Port expose, Networking, Volumes, and Building images for detailed usage.