Troubleshooting¶

Ensure virtualization is enabled in BIOS and /dev/kvm exists:

ls -la /dev/kvm
sistemo install  # checks KVM support

If /dev/kvm exists but you can't access it:

sudo usermod -aG kvm $USER
# Log out and back in

Something else is using port 7777. Find and stop it:

sudo lsof -i :7777

The daemon needs root for network namespaces:

sudo sistemo up

Run sistemo install to download Firecracker and the guest kernel. Verify they exist:

ls ~/.sistemo/bin/firecracker
ls ~/.sistemo/kernel/vmlinux

Try reducing memory or storage:

sistemo machine deploy debian --memory 256M --storage 1G

sistemo machine logs <name|id>

Shows the Firecracker log with boot output and errors.

The machine image must have openssh-server installed. If you built the image with sistemo image build, openssh-server is auto-installed. If you're using a pre-existing rootfs file, make sure it has openssh-server.

Try redeploying the machine:

sistemo machine delete <name>
sistemo machine deploy <image> --name <name>

Sistemo always injects its SSH key and configures sshd at deploy time.

The terminal connects via WebSocket. Check that the daemon is running and the machine is in running status:

sistemo machine status <name>

Upgrade to the latest binary. Older versions incorrectly interpreted flags like -h as sistemo flags. The current version passes all arguments after the machine name to SSH:

sistemo machine exec myvm df -h          # works
sistemo machine exec myvm -- ls -la      # also works

On low-memory machines (512 MB), Docker export can be slow. Wait a few minutes. If it still hangs:

• Check available disk space: df -h
• Reduce rootfs size: ROOTFS_MB=1024 sudo sistemo image build myimage
• Build on a larger machine and copy the .rootfs.ext4 file over

The auto-install uses chroot and needs network access (DNS). Make sure:

• The host has internet access
• /etc/resolv.conf on the host has valid DNS servers
• The Docker image uses a supported package manager (apt, apk, dnf, yum, pacman)

As a fallback, install openssh-server in your Dockerfile before building.

The default machine subnet is 10.200.0.0/16. If it conflicts with your VPN, Kubernetes, or other network, change it:

# ~/.sistemo/config.yml
bridge_subnet: "10.50.0.0/16"

Restart the daemon and redeploy machines after changing the subnet.

Run sudo nft list ruleset and check for duplicate DNAT rules. If you see stale rules from previous test runs, clean them up:

sudo nft delete rule ip sistemo prerouting handle <handle>
sudo nft delete rule ip sistemo output handle <handle>

Then restart the daemon. Port rules are restored from the database on startup.

Check that the bridge exists and has the right IP:

ip addr show sistemo0

Check that MASQUERADE and FORWARD rules exist:

sudo nft list chain ip sistemo postrouting
sudo nft list chain ip sistemo forward

If rules are missing, restart the daemon — it recreates them on startup.

Check that the SISTEMO-ISOLATION chain exists and has rules:

sudo nft list chain ip sistemo isolation

If empty or missing, restart the daemon and recreate networks:

sistemo network delete mynet
sistemo network create mynet

Verify the bridge exists and has an IP:

ip addr show br-mynet

Check MASQUERADE rule exists for the network's subnet:

sudo nft list chain ip sistemo postrouting | grep br-mynet

The daemon validates all config values. Fix the value shown in the error message. Run sistemo config to see the effective configuration. See Configuration for all validation rules.

Reset it from the CLI:

sistemo admin reset-password

This prompts for a new password interactively.

The in-browser terminal uses a WebSocket connection to the daemon. Check:

• The daemon is running: curl -s http://localhost:7777/health
• The machine is in running status: sistemo machine status <name>
• If behind a reverse proxy, ensure Upgrade and Connection headers are forwarded (see Dashboard — Remote access)

The daemon listens on localhost only by default. To expose it:

1. Set HOST_API_KEY as an environment variable (not in config.yml)
2. Put a reverse proxy (nginx, Caddy) with TLS in front of port 7777
3. Forward WebSocket headers for the terminal to work

See Dashboard — Remote access for a full nginx example.

A volume must be detached before it can be deleted. If the volume shows as attached, stop the machine first, then detach:

sistemo machine stop <vm-name>
sistemo machine volume detach <vm-name> <volume-name>
sistemo volume delete <volume-name>

Volumes can only be attached or detached while the machine is stopped:

sistemo machine stop <vm-name>
sistemo machine volume attach <vm-name> <volume-name>
sistemo machine start <vm-name>

After attaching a data volume, it appears as an additional block device inside the machine (e.g. /dev/vdb). You may need to format and mount it on first use:

sistemo machine ssh <vm-name>
# Inside the machine:
mkfs.ext4 /dev/vdb
mkdir -p /mnt/data
mount /dev/vdb /mnt/data

Add an entry to /etc/fstab inside the machine for automatic mounting on boot.