Desktop lifecycle

Status flow#

Every desktop goes through these states:

pending → booting → running → stopped → destroying → destroyed

Transitions happen automatically or when you take an action from the dashboard.

What each status means#

Pending#

The desktop exists in the database but the VM has not been provisioned yet. This lasts a few seconds while resources are allocated.

No actions available. Wait for provisioning to finish.

Booting#

The VM is starting. The initialization process configures the system, installs your plugins, and starts background services. This takes 30-60 seconds.

No actions available. The VNC viewer may show the boot screen, but the desktop is not usable yet.

Running#

The desktop is ready. XFCE is loaded, the terminal works, and if you configured an AI provider, the agent accepts chat messages.

Available actions: stop, restart, destroy, connect via VNC, open terminal, upload files, chat with agent.

Stopped#

The VM is powered off but still exists. Files, software, and configuration are preserved on disk. A stopped desktop does not use CPU or RAM, but it counts toward your desktop limit.

Available actions: start (goes back through booting → running), destroy.

Destroying#

The VM is being torn down and disk resources freed. This is brief and irreversible.

No actions available.

Destroyed#

The desktop no longer exists. The database record is kept for history, but all VM resources have been released. You can create a new desktop from the dashboard.

Common operations#

Creating a desktop#

From the dashboard, click New Desktop. Pick a name, a tier (Free, Pro, or Max), and optionally configure an AI provider. The desktop enters pending immediately, then moves to booting.

Stopping a desktop#

Click Stop on a running desktop. The VM shuts down gracefully. Useful when you want to pause work without destroying the environment.

Restarting a desktop#

Click Restart on a running desktop. This stops and then starts it again. Use it to recover from a stuck state or apply configuration changes.

Destroying a desktop#

Click Destroy to permanently remove a desktop. This is irreversible. All files, installed packages, and agent history on that desktop are lost. Conversation history in the dashboard is preserved.

Tips#

• If a desktop stays in booting for more than 2 minutes, check the troubleshooting guide.
• Stopped desktops still count toward your plan's limit. Destroy desktops you no longer need.
• You can watch boot progress in real time through the VNC viewer. It shows the Ubuntu boot screen during booting.