cubeCUBE / DOCUMENTATION
Manage your virtual machines
Use cubectl to give guests a name, inspect their state, and control their lifecycle.
Use the installed CLI
Open Cube.app and choose Open Terminal (Cube Environment), or use a terminal with cubectl on PATH. Replace freebsd-dev with the name of a VM you have already installed. Creating a configuration alone does not install an operating system.
cubectl list
cubectl start freebsd-dev
cubectl status freebsd-devThe native CLI is written in Rust and is also bundled in Cube.app. Python is used by some installation and verification scripts, not by the CLI itself.
Create and install FreeBSD
Use a new VM name and let cubectl download the official FreeBSD ARM64 disc1 ISO. The unattended installer partitions the disk and installs FreeBSD before the command returns:
cubectl create freebsd-dev \
--version 14.4 --unattended \
--ram 2048 --cpus 2 --ssh-port 2222After installation, start the network service as described in Getting started, then boot the installed guest:
cubectl start freebsd-devEnable the guest SSH server and configure authentication before using the SSH example. For an interactive installation from a local ISO, consult `cubectl create --help` and eject the installer ISO after setup.
Connect over SSH
The guest needs a running SSH server, a reachable endpoint, and valid credentials. Port forwarding and shutdown connection settings belong in the VM configuration. Consult the CLI help for your build:
cubectl ssh --help
cubectl ssh freebsd-devShut down cleanly
Shutdown requests a guest poweroff over batch-mode SSH. It requires the configured SSH endpoint and authentication to work. By default, a timeout leaves the VM running.
cubectl shutdown freebsd-dev --timeout 120If the guest is unresponsive, stop terminates the host VM process and allows backend cleanup before its forced-kill fallback. This is not an orderly guest shutdown; use it only when that is the intended action.
cubectl stop freebsd-dev --timeout 10Find configuration and logs
VM configuration and disks default to ~/Cube/<NAME>/. Runtime state and logs default to ~/.local/state/cube/<NAME>/. Look for vmm.log, console.log, and manager.log. A new run replaces run logs, so save relevant logs before restarting when diagnosing a failure.
JSON paths are relative to the configuration file. Command-line override paths are relative to your current directory. Overrides on start affect that run without rewriting the saved configuration.
Understand resource ownership
Managed VMs reserve writable disks, overlays, and TCP listeners to prevent conflicting use. Read-only media can be shared. If startup reports a conflict, inspect other running VMs rather than deleting lock or state files.
Full VM snapshots containing memory and device state are not covered by the documented disk-overlay workflow. Offline overlay inspection and export operate on disk contents.
Reference
The VM management runbook covers configuration fields, creation, installation, overrides, and lifecycle behavior. The overlay guide explains offline disk tools.