> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stacyos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# StacyVM 0.15.0

> Interactive Experience & Cross-Platform Desktop — styled CLI, terminal UI, embedded web dashboard, and downloadable desktop apps for Linux, macOS, and Windows.

# StacyVM 0.15.0 — Interactive Experience & Cross-Platform Desktop

Date: 2026-05-31

This release is all about how you *use* StacyVM. The sandbox and runtime engine
are unchanged; everything new is operator-facing: a styled CLI, a full-screen
terminal UI, a web dashboard embedded right in the binary, downloadable desktop
apps for every OS, and a one-command installer.

It is a **minor version bump (0.14.x → 0.15.0)** because the install/build flow
and frontend layout changed — see [Upgrade notes](#upgrade-notes).

## New features

### One-command installer

* `npx stacyvm-setup@latest` clones StacyVM, builds the web UI and the CLI,
  installs `stacyvm` onto your PATH, runs the setup wizard, and removes the
  downloaded checkout — leaving a working `stacyvm` command and nothing else.
* The repo is only deleted **after** a successful install, so a failed run never
  leaves you without a binary.

### Interactive CLI

* Restyled with [`charmbracelet/fang`](https://github.com/charmbracelet/fang)
  and a StacyVM brand theme.
* New `stacyvm setup` wizard (huh forms) to pick an isolation provider
  (Docker / Firecracker / PRoot), the Docker runtime (runc / runsc / kata), a
  preview domain, and optional shell auto-completion (bash, zsh, fish).
* New `stacyvm update` (self-update) and `stacyvm uninstall` (remove binaries +
  `~/.stacyvm`).

### Terminal UI (`stacyvm tui`)

* Full-screen Bubble Tea app with six screens: **Dashboard**, **Sandboxes**,
  **Templates**, **Providers**, **Logs**, **Config**.
* Keys: `1`–`6` switch screens, `Ctrl+K` command palette, `r` refresh,
  `q`/`Ctrl+C` quit; sandbox actions `s` spawn, `e` exec, `f` workspace/files,
  `l` logs, `d` destroy.
* Workspace screen with a netrw-style file tree and a modal text editor
  (`Ctrl+S` to save), an editor-majority layout, and a toggleable terminal pane.

### Embedded web dashboard

* A new Next.js dashboard (`web/`) with Dashboard, Sandboxes, Templates,
  Providers, Environments, Operations, Tenants, and Settings pages.
* Built as a static export and embedded directly into the binary. Launch it with
  `stacyvm web-ui` (alias `ui`), which serves it on port `5749` and opens a
  browser. (Run `stacyvm serve` alongside it for live data.)
* Refreshed branding: new logos, color palette, and icons.

### Desktop app

* A [Wails](https://wails.io) desktop app that packages the dashboard **and**
  runs the StacyVM API daemon in-process — one window, no separate `serve`.
* Download prebuilt installers from the
  [Releases page](https://github.com/StacyOS/stacyvm/releases/latest); full guide
  in [Desktop App](/docs/desktop-app).

## Cross-platform desktop distribution

Wails cannot be reliably cross-compiled (each platform links its native
webview), so desktop builds now run on a native GitHub Actions matrix:

* **`.github/workflows/desktop.yml`** builds on Linux, macOS, and Windows
  runners and produces a per-OS installer:
  * **Windows** — NSIS installer (`StacyVM-amd64-installer.exe`)
  * **macOS** — universal `.dmg` (`StacyVM-macos-universal.dmg`, Apple Silicon + Intel)
  * **Linux** — self-contained AppImage (`StacyVM-x86_64.AppImage`) + tarball
* Installers are attached to the GitHub Release on each `v*` tag, and the
  workflow can also be run manually via **workflow\_dispatch**.
* A committed `desktop/build/` scaffold (app icon, `Info.plist`, NSIS config)
  keeps installer branding and metadata reproducible.

<Note>
  The desktop app bundles the UI and API, but you still need **Docker** (or another
  provider) running on the host to spawn sandboxes. v0.15.0 desktop builds are
  **unsigned**, so macOS Gatekeeper and Windows SmartScreen show a one-time prompt;
  the [Desktop App guide](/docs/desktop-app) documents the bypass.
</Note>

## Build & packaging

* `make build` now builds the web UI (`npm run build` → `web/out`) before
  compiling the Go binary, since the CLI embeds the dashboard.
* `make build-desktop` is now OS-aware (auto-applies the Linux-only
  `-tags webkit2_41`), and `desktop/wails.json` gained a `frontend:install` step
  so clean CI checkouts build the frontend.
* `scripts/npm-setup.mjs` builds the web UI before `go build` and only removes
  the cloned repo after a successful global install.

## Upgrade notes

* **Version:** `0.14.x → 0.15.0` (`package.json`, `desktop/wails.json`).
* **Building from source** now requires the web UI to be built first. `make build`
  and `npx stacyvm-setup` handle this automatically; a bare
  `go build ./cmd/stacyvm` needs `web/out` to exist.
* **Frontend relocation:** the previous Vite frontend moved to `deprecated/web/`;
  the active dashboard is the Next.js app in `web/`.
* **Desktop app** is a separate prebuilt download and is intentionally **not**
  produced by `scripts/npm-setup.mjs` (that builds the CLI from source).

## Bug fixes

* TUI: stopped styled-in-styled nesting from leaking raw ANSI escape codes in
  navigation/selection rows (with a regression test).
* TUI: arrow keys now act within the active screen instead of hijacking screen
  switching; `1`–`6` switch screens.
* Desktop build fixed: reuse the embedded `web.Assets` instead of a non-existent
  `frontend/out`, and refresh `desktop/go.sum` for the new `gopsutil/v4`
  dependency.