Skip to content

reference

deputyos-desktop

One-click desktop launcher for deputyOS.

One-click desktop launcher for deputyOS.

deputyos-desktop is the end-user-facing binary that turns “I want to try deputyOS on my laptop” into “double-click this and a browser opens to the wizard”. It is not baked into appliance images — it is the host that runs an appliance image.

The launcher mandates the host’s native virtualization stack:

  • Linux: qemu-system-x86_64 / qemu-system-aarch64 + KVM.
  • Windows: WSL2 (wsl --install -d Ubuntu).
  • macOS: UTM 4.x (Vz.framework on Apple Silicon, qemu fallback on Intel).

There is no bundled hypervisor. The launcher prints a clear install hint when its prereq is missing and refuses to download an image until that prereq is satisfied.

Synopsis

deputyos-desktop [<command>] [options]

Invoking with no subcommand mimics double-click: install if needed, start, then open the wizard URL in the default browser.

Global options

FlagEffect
-h, --helpPrint help.
-V, --versionPrint version.

Logging

tracing-subscriber is opt-in via RUST_LOG; default is off so the launcher prints its own clear ==>-prefixed stderr lines without a logger prefix in normal use. Set RUST_LOG=debug to see internal trace events.

Per-platform binary location

The launcher binary is per-platform — one binary per target triple, so the macOS bundle never carries wsl --import symbol references and the Linux binary never carries UTM bindings. End users get:

HostDistributed asDefault install location
Linuxtarball + deputyos-desktop ELF~/.local/bin/deputyos-desktop (or wherever the user mv’d it)
Windows.exe inside an installer%LOCALAPPDATA%\Programs\deputyos-desktop\deputyos-desktop.exe
macOS.app bundle (or bare ELF)/Applications/deputyos-desktop.app/Contents/MacOS/deputyos-desktop

Per-platform paths

The launcher uses dirs crate semantics for cache, data, and runtime directories.

HostCache (image storage)Data (PID file, last manifest)Runtime
Linux~/.cache/deputyos-desktop (or $XDG_CACHE_HOME/deputyos-desktop)~/.local/share/deputyos-desktop/run/user/<uid>/deputyos-desktop
Windows%LOCALAPPDATA%\deputyos-desktop (cache subdir)%LOCALAPPDATA%\deputyos-desktop (data subdir)falls back to data
macOS~/Library/Caches/deputyos-desktop~/Library/Application Support/deputyos-desktopfalls back to data

Every getter is overridable via environment for tests:

VariableOverrides
DEPUTYOS_DESKTOP_CACHE_DIRcache dir
DEPUTYOS_DESKTOP_DATA_DIRdata dir
DEPUTYOS_DESKTOP_RUNTIME_DIRruntime dir
DEPUTYOS_DESKTOP_PUBKEYminisign public key path
DEPUTYOS_DESKTOP_MANIFEST_URLmanifest URL (the production default contains the placeholder <<<NEEDS_DEPUTYOS_DIST_URL>>> until the CDN ships the bucket)
DEPUTYOS_DESKTOP_WIZARD_URLwizard URL the launcher opens (default http://localhost:8088)

Driver implementation status

DriverStatusWhat works today
LinuxRealqemu spawn with KVM, hostfwd :8088 and :8089, PID file under runtime dir, graceful stop.
WindowsScaffolded — unimplemented!()Only check_prereq() is wired; it errors with “Install WSL2 with: wsl --install -d Ubuntu”. Not yet implemented.
macOSScaffolded — unimplemented!()Only check_prereq() is wired; it errors with “Install UTM from the App Store”. Not yet implemented.

A host whose OS is not Linux/Windows/macOS gets the UnsupportedDriver fallback, which errors helpfully on every method.

Per-host VM target

The target_for_host() driver method picks which manifest artefact this host needs:

Host arch / OStarget_for_host
Linux x86_64qemu-x86_64
Linux aarch64qemu-aarch64
Windowswsl2
macOSmacos-qemu
otherunsupported

Exit codes

  • 0 — success.
  • 1 — anyhow error (printed with full chain via {err:#}). Includes prereq missing, manifest fetch / verification failure, download failure, driver error.

Commands

(no subcommand) — default action

Install-if-needed, start, open browser.

Synopsis

deputyos-desktop

Behavior

  1. Resolve the driver via current_driver() (compile-time gated).
  2. Check whether <cache>/deputyos-<target>.qcow2 exists.
  3. If missing: run install.
  4. Run start.

This is the double-click path for non-technical users.

Examples

$ deputyos-desktop
==> deputyos-desktop (no subcommand) — install-if-needed + start + open browser
==> deputyos-desktop install
==> fetching manifest: https://cdn.deputyos.com/dev/manifest.json
==> selected artefact: deputyos-openclaw-qemu-x86_64-2026.4.27.qcow2 (1873294848 bytes)
==> downloading + verifying...
==> install complete
==> deputyos-desktop start
==> linux driver: spawning /usr/bin/qemu-system-x86_64
==> wizard at http://localhost:8088

install

Verify prereq, fetch + verify manifest, download + verify image, stage in cache.

Synopsis

deputyos-desktop install

Behavior

  1. Driver prereq check. Runs the platform-specific check:
    • Linux: qemu-system-{x86_64|aarch64} on PATH; soft warn if /dev/kvm not present.
    • Windows: wsl --status (today: hard error with install hint).
    • macOS: /Applications/UTM.app exists (today: hard error with install hint).
  2. Manifest fetch. Fetch the manifest at DEPUTYOS_DESKTOP_MANIFEST_URL (or the placeholder default).
  3. Manifest verification. Verify the manifest’s minisign signature against DEPUTYOS_DESKTOP_PUBKEY (defaults to the dev key at ~/.config/deputyos/dev-keys/deputyos-dev.pub; production builds will embed the public key — not yet implemented).
  4. Pick artefact. From manifest.artefacts, pick the first whose target equals driver.target_for_host().
  5. Download. Download the artefact and its .minisig to <cache>/deputyos-<target>.qcow2[.minisig]. Verify SHA256, then verify the minisign signature.
  6. Driver install_image. Per-platform import step (no-op on Linux since qemu reads the image directly).

Files written

  • <cache-dir>/deputyos-<target>.qcow2
  • <cache-dir>/deputyos-<target>.qcow2.minisig

Exit codes

  • 0 — image staged.
  • 1 — prereq missing, signature failed, network failure, or driver error.

start

Boot the VM, open browser. Idempotent.

Synopsis

deputyos-desktop start

Behavior

  1. Run the driver’s prereq check.
  2. Call driver.start(). On Linux:
    • Build the qemu argv with KVM acceleration (or TCG fallback if /dev/kvm is unavailable).
    • Set up hostfwd for ports 8088 (wizard) and 8089 (PWA) to localhost.
    • Spawn qemu detached, write its PID to <runtime>/deputyos-desktop.pid.
  3. Resolve wizard_url (DEPUTYOS_DESKTOP_WIZARD_URL or http://localhost:8088) and call browser::open_url.
  4. Print ==> wizard at <url>.

If a VM is already running (Linux: PID file exists and kill -0 succeeds), start returns the existing handle without spawning a second qemu — the operation is idempotent.

Files written

  • <runtime-dir>/deputyos-desktop.pid (Linux).

Exit codes

  • 0 — VM running, browser opened (or browser failed to open — that’s best-effort).
  • 1 — prereq missing or qemu spawn failed.

stop

Graceful shutdown.

Synopsis

deputyos-desktop stop

Behavior

Linux: read the PID file, send SIGTERM to qemu. Optionally a system_powerdown via the qemu monitor for a clean ACPI shutdown (the qemu monitor may take ~10s to drain disk caches; use stop then wait if the user wants ACPI-clean).

Exit codes

  • 0 — stop sent (or VM was already stopped).
  • 1 — driver error.

status

Print “running” or “stopped” and the wizard URL.

Synopsis

deputyos-desktop status

Behavior

Calls driver.status():

  • Running: prints running (id=<pid-or-handle>) followed by one URL per line (typically http://localhost:8088).
  • Stopped: prints stopped.

Examples

$ deputyos-desktop status
running (id=12345)
  http://localhost:8088
$ deputyos-desktop status
stopped

Exit codes

  • 0 — status printed.
  • 1 — driver error (rare).

update

Manifest check + download + (binary replacement is still a stub).

Synopsis

deputyos-desktop update

Behavior (today)

  1. Print a notice that signature-verified manifest fetch + image swap is not yet implemented; today the user re-runs install to pull the latest image.
  2. Exercise the manifest fetch path so a CI smoke catches breakage:
    1. Resolve DEPUTYOS_DESKTOP_MANIFEST_URL. If it equals the placeholder <<<NEEDS_DEPUTYOS_DIST_URL>>>, print “set DEPUTYOS_DESKTOP_MANIFEST_URL or wait for the CDN” and exit 0.
    2. Fetch + sig-verify the manifest.
    3. Print latest released_version = <v> (channel=<c>).

Examples

$ deputyos-desktop update
==> deputyos-desktop update: signature-verified manifest fetch is not yet implemented. Today: re-run `deputyos-desktop install` to pull the latest image.
==> latest released_version = 2026.4.27 (channel=dev)

Exit codes

  • 0 — manifest fetched + verified, or placeholder URL detected.
  • 1 — fetch / verification failed.

uninstall

Remove the cached image. Optionally also wipe the persistent data dir.

Synopsis

deputyos-desktop uninstall [--data]

Options

  • --data — also delete the persistent data directory.

Behavior

  1. rm -rf <cache-dir> (the image + its .minisig).
  2. If --data:
    • rm -rf <data-dir> (PID file, last-installed manifest, etc.).
    • Best-effort rm -rf <runtime-dir> if it differs from data dir (skip on /run/user/<uid> — we don’t want to recursively delete the user’s runtime dir).

Destructive --data removes all desktop-launcher state. The next start will spawn a fresh VM with whatever the cached image contains; if the cache is also gone (uninstall deleted it), start will fail until you install again.

Examples

$ deputyos-desktop uninstall
==> deputyos-desktop uninstall
==> removed cache: ~/.cache/deputyos-desktop
$ deputyos-desktop uninstall --data
==> deputyos-desktop uninstall
==> removed cache: ~/.cache/deputyos-desktop
==> removed data: ~/.local/share/deputyos-desktop

Exit codes

  • 0 — removed (or nothing to remove).
  • 1 — filesystem error.

See also

Search

Search index isn't built yet. Run npm run build to generate it (Pagefind writes to dist/pagefind/).