Installing embassyOS on Virtual Machine Manager (virt-manager)

How to install embassyOS on virt-manager

(for testing new packages without access to a physical Embassy)


  1. Download and install virt-manager
  2. Download the embassyOS ISO from Github (v0.3.3 or later)
  3. Open virt-manager
  4. Click “create a new virtual machine”
  5. Choose “Local install media” and click Forward
  6. Click Browse and choose the ISO that you downloaded
  7. Uncheck “Automatically detect”, and choose Ubuntu 22.04 LTS for your OS. Other versions of Ubuntu will probably work, as well as Generic Linux. Click Forward.
  8. On the next two pages, choose the resources you would like to allocate.

Minimum OS Requirements

  • Single vCPU Core 2Ghz
  • 4GB RAM
  • 64GB Storage (32GB will also work if you’re just doing package development)

Recommended OS Requirements

If you intend to run Bitcoin or store any meaningful amount of data, you will need

  • Quad-Core CPU 2.5Ghz+
  • 8GB+ RAM
  • 1TB+ Storage



  1. Give the machine a meaningful name and click Finish
  2. The VM will open up. Select install embassyOS with your keyboard and hit ENTER
  3. After a few seconds, a browser window will appear inside the VM. Click the disk (the only disk that will exist is the one you created for the VM) under Select Disk, and then click Install embassyOS.
    You will get a warning that you’re about to erase the disk - that’s fine, there’s nothing on it.
  4. You’ll get an Install Success popup. Click Reboot.
  5. After the reboot, the browser in the VM will show the setup page. If you’re installing for package development, click Start Fresh.
  6. Select your only storage drive on the next screen.
  7. Choose a password and click “Finish”.
  8. Success! EmbassyOS is now installed on your VM. It runs inside a browser window!
    Click to login. (You’ll be prompted for your password.)
  9. To begin package development, follow this guide.
  10. Once you’ve created an S9PK that you’d like to test, inside embassyOS click System in the sidebar, and then click Sideload Service under Manage. :warning: When I finish networking my VM, I’ll write that up so that sideloading is possible. If anyone else has a writeup for this, I’ll include it.

This is awesome, thank you so much for this guide, Spencer!

One thing I would mention, this is a perfect setup but there’s a quirk, if you happen to cancel out of the install, for some reason, it won’t boot the installer again until you do this:

  1. Right click the VM and go to Open
  2. Click the light bulb :bulb: to configure the VM
  3. Go to IDE CDROM 1
  4. Under Source Path, click Browse
  5. Under final, select eos-0.3.x-xxxxxxxx_amd64.iso, and click “Choose Volume”
  6. Click Apply
  7. Go to Boot Options
  8. Enable IDE CDROM 1 and position it above IDE Disk 1
  9. Click Apply

Now you can happily boot the installer even if you accidentally canceled out of it the first time, or want to reinstall. Just remember to also demote IDE CDROM 1 from the boot order after your initial setup.

1 Like

Hey @George , I wanted to come back and finish this post today, but I can’t edit it now.
I just want to tie off the LAN cert setup and sideloading.

I’d indended this to be a complete post that I could just send around. If I’m locked out of editing, I’ll have to delete and start over. If that’s unavoidable, then lemme know. :slight_smile:

You should be able to edit posts, and it shows that you have made edits to posts previously. I’m trying to see if there’s a rate limit, but not seeing anything on my end. Are you getting an error or message regarding this? Maybe we should move to a chat

The other day I found a message board that said (I believe) that by default Discourse allows editing only for 5 hours after the original post. (Presumably to cut down on people going in to popular posts and adding spam after the fact.)

Created this tutorial, which adds a bit more context to the above: