# Desktop and troubleshooting
Find the right next check, and understand the current display and guest support boundaries.

## Use a FreeBSD desktop
Start an installed desktop VM from Cube.app or the CLI:

```sh
cubectl start work
```

Replace work with your VM name. This starts an existing VM; it does not install desktop packages. For repository-assisted desktop installation, see [Build from source](build-from-source.html). The [desktop runbook](https://github.com/darcyliu/cube/blob/main/docs/freebsd-desktop.md) covers guest setup and validation scope.

## Native window or VNC
For an installed guest's direct cube launch, --gui native opens a Cocoa/Metal window instead of using --vnc. The --retina option opts into a 2× framebuffer at the same window size; guest UI scaling is configured separately.

VNC binds to loopback and accepts one client at a time. Use an SSH tunnel for remote access. The simple framebuffer uses a fixed boot-time resolution and does not provide 3D acceleration, runtime resizing, multiple displays, or clipboard synchronization.

## The first FreeBSD boot fails on networking
If you only need a live shell, use cube with --net none and your existing kernel and disk paths. Otherwise, start the service in Cube.app and confirm it is still running. See [Getting started](getting-started.html) for a complete direct-launch example.

## A VM starts but SSH does not connect
Check that the guest finished booting, sshd is running, the guest address and forwarding rule match, and the configured key or credentials are correct. Inspect console.log and vmm.log. A static guest address will not populate DHCP-based IP discovery automatically.

## Startup reports a disk or port conflict
Check cubectl list and the status of other VMs. A writable disk, overlay, or listening port may already be in use. Shut down the owner or choose distinct resources. Do not bypass the conflict by deleting live state files.

## The shared folder is missing or stale
Confirm the export path exists on the host and the mount tag matches. Load virtio_p9fs in the guest and mount it explicitly. Shares are attached at boot; restart the VM to change them. If host edits are not visible, unmount and remount to refresh the guest view.

## Collect useful diagnostics
Preserve run logs before restarting, since a new run replaces them. Record the macOS version, Cube commit, guest release, launch command, network mode, and whether the issue occurs after a cold start or reboot. Remove credentials from any diagnostics you share.

The [verification guide](https://github.com/darcyliu/cube/blob/main/docs/verification.md) describes core, offline, and full suites. Those tests have prerequisites and may create disposable guests; read the guide before running a broad suite.