zBox Desktop Appliance

Based on zBox

Opinionated Remote Desktop Graphical Linux Appliance setup for my personal use. Just RDP to the VM with the zadmin credentials and you're good to go.

Note

This is a work in progress and will be updated over time.

What changed in each version: GitHub releases (one per Debian point release) or CHANGELOG.md.

Purpose

My personal all-in-one Desktop VM for dev and testing.

• Fancy zsh prompt shell (oh-my-zsh/posh/custom theme, zsh-autosuggestions, zsh-syntax-highlighting, atuin, zoxide)
• Pre-configured apt sources lists for docker, kubernetes, hashicorp, tailscale, netbird, cloudflare tunnel, mise
• XFCE desktop over xrdp with JetBrainsMono Nerd Font and Noto Color Emoji
• tmux with TPM and the Catppuccin theme, true color tuned
• chezmoi preinstalled for dotfiles management (runtime version manager mise is not preinstalled, but its apt repo is ready: apt install mise)
• LVM2 based storage configuration (first boot grows root via zbox-init; zbox-init.sh --extend-disk runs storage expansion only)
• Various misc tools (eza, bat, ripgrep, fzf, httpie, doggo, gping, mtr, snitch, witr, ttl, xfr, surge, fx, ...)

Easily deploy the appliance using the provided OVF Properties or cloud-init configuration.

Downloads

Latest builds are available here:

• https://cloud.tsugliani.fr/ova/zboxdesktop-13.7.ova
• https://cloud.tsugliani.fr/ova/zboxdesktop-13.6.ova
• https://cloud.tsugliani.fr/ova/zboxdesktop-13.5.ova

Deployment examples

For both examples we will be using the govc cli tool to deploy the appliance.

A basic configuration for govc is to export the appropriate variables in your shell environment. For example I use the following xyz.env file:

export GOVC_INSECURE=true
export GOVC_URL="https://vc/sdk"

export GOVC_USERNAME="username"
export GOVC_PASSWORD="password"

export GOVC_DATACENTER="Datacenter"
export GOVC_DATASTORE="vsanDatastore"

This way I can source the file in my shell session and have the appropriate target environment ready to use through the govc cli tool. (easy to manage multiple target environments this way for quick testing)

source xyz.env

Then I can use the govc cli tool to deploy the appliance, either using the OVF Properties or the cloud-init configuration.

OVF Properties Deployment

Sample configuration for OVF Properties deployment where it will setup the networking, the root/zadmin password and ssh key.

ovfproperties.json (adapt to your environment):

{
  "DiskProvisioning": "flat",
  "IPAllocationPolicy": "dhcpPolicy",
  "IPProtocol": "IPv4",
  "PropertyMapping": [
    {
      "Key": "guestinfo.hostname",
      "Value": "zboxdesktop"
    },
    {
      "Key": "guestinfo.ipaddress",
      "Value": "10.10.42.139"
    },
    {
      "Key": "guestinfo.netprefix",
      "Value": "24"
    },
    {
      "Key": "guestinfo.gateway",
      "Value": "10.10.42.1"
    },
    {
      "Key": "guestinfo.dns",
      "Value": "10.10.42.254"
    },
    {
      "Key": "guestinfo.domain",
      "Value": "ovfproperty.lab"
    },
    {
      "Key": "guestinfo.password",
      "Value": "zboxisamazing2025!"
    },
    {
      "Key": "guestinfo.sshkey",
      "Value": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC/i56xhpfJKBC9TaL4BlPP3eDY03Csf4aLIM4OkSGDlTwNbadu5doGb8x/Z7650xsxXTuDq22UEVv0fuklc3DCl3NP9yv27LNj54g9WZPrC0wlDZOblvQo52atjkh4SIYZp5Rn9FFY+Vwc5/c3widbZ8OrNynS4QkKWrZHfmrjzWR0ZwGZPgTNxRiD0db6XVfxAxr3MuTKEd2yKlWenS8+ZEKnjR1nhEC6awmkt8p/uNZvyKHcVQ4Goyeo6EKaJf5JtdSV6mnN0lL3URuvDefrJygFzTNqhu1bwiXQl/zG969HaAkNRA4FhM2BIziIjCAzXrmQoaY8+5bWDXJg3kdp root@zPodMaster"
    }
  ],
  "NetworkMapping": [
    {
      "Name": "VM Network",
      "Network": "Segment-Dev-Lab"
    }
  ],
  "MarkAsTemplate": false,
  "PowerOn": true,
  "InjectOvfEnv": true,
  "WaitForIP": false,
  "Name": null
}

Note

the PowerOn flag is set to true and will automatically power on the VM after deployment.

govc import.ova -name zboxdesktop -options ovfproperties.json https://cloud.tsugliani.fr/ova/zboxdesktop-13.7.ova

Wait a moment for the VM to be uploaded, created and it should be available with the provided IP address/credentials from the ovfproperties.json file.

cloud-init Deployment

Not supported yet.

Screenshots

Some screenshots of the appliance using some of the installed tools.

Packer setup

If you want to build and/or modify the appliance yourself, you can follow the below steps.

Set your zboxdesktop-builder.json file with the correct parameters from the provided example file.

cp zboxdesktop-builder.json.sample zboxdesktop-builder.json

Edit the required values in the zboxdesktop-builder.json file to reflect your builder environment.

vi zboxdesktop-builder.json

Warning

This step requires you to have a proper VMware ESXi environment prepared for packer to use. You can use William Lam provided Nested ESXi Virtual Appliances to build the zBox appliance.

Then you can build the appliance using the provided build-zboxdesktop.sh script.

./build-zboxdesktop.sh

This should take around 15 minutes to build the appliance. The OVA is named after APPLIANCE_VERSION in build-zboxdesktop.sh, not after the var file: 13.7 is written to output-zboxdesktop-13.7/zboxdesktop-13.7.ova, and a respin 13.7.1 of the same Debian release — still built from zboxdesktop-13.7.json — to output-zboxdesktop-13.7.1/zboxdesktop-13.7.1.ova.

ls -l output-zboxdesktop-13.7/*.ova