# 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.

```sh
cubectl list
cubectl start freebsd-dev
cubectl status freebsd-dev
```

The 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:

```sh
cubectl create freebsd-dev \
  --version 14.4 --unattended \
  --ram 2048 --cpus 2 --ssh-port 2222
```

After installation, start the network service as described in [Getting started](getting-started.html), then boot the installed guest:

```sh
cubectl start freebsd-dev
```

Enable 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:

```sh
cubectl ssh --help
cubectl ssh freebsd-dev
```

## Shut 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.

```sh
cubectl shutdown freebsd-dev --timeout 120
```

If 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.

```sh
cubectl stop freebsd-dev --timeout 10
```

## Find 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](https://github.com/darcyliu/cube/blob/main/docs/vm-management.md) covers configuration fields, creation, installation, overrides, and lifecycle behavior. The [overlay guide](https://github.com/darcyliu/cube/blob/main/docs/overlay-management.md) explains offline disk tools.