Getting started, and answers to common questions.

Ubuntu 26.04 and 24.04 LTS, Debian 13 and 12, Fedora 44 Cloud Base, and Rocky Linux 10 and 9. The app downloads the vendor's official image, converts it for Apple's Virtualization framework, and passes cloud-init your username, password, this Mac's SSH key and a hostname. On first boot the system sets itself up and grows to the disk size you chose. Once the download is done, it's usually ready to sign in to in about a minute.

Ubuntu Server and Desktop, Fedora Server and Everything, and Rocky Linux (minimal and DVD). Leave Automatic installation on in the Image step and the app answers the installer's questions for you: your account and SSH key, plus this Mac's language, keyboard and time zone. The installer doesn't stop to ask anything, not even before it erases the virtual disk. When the install finishes, the workspace restarts into the new system.

Debian's installer, Fedora Workstation, Kali Linux, NixOS and Alpine Linux run their own installer in the workspace's display, just as they would on a PC. For a hands-free Debian, use the Debian cloud image instead. On an Apple silicon Mac you can also install macOS from Apple's restore image.

That's expected after any manual install, such as Kali Linux, NixOS, Alpine Linux or Debian's installer. Velo Workspaces knows when an automatic install has finished, but only you know when you've finished one by hand. While an OS is being installed, the workspace uses Large Text display scaling so the boot menu and installer are big enough to read. Once the installed system has booted, click Installation Complete: the installer is no longer attached, and the workspace's own display setting applies from the next start. Stop and start the workspace once to switch; a reboot inside the guest isn't enough.

Yes. Click Choose File… on the Image step, or Import… in Settings › Images. If the file's name is in the vendor's checksum list, the app checks it against the official checksum before using it. Everything you download or import stays in Settings › Images (also Images in the sidebar), where you can reuse, verify or delete it.

Start the workspace, open its Access tab and click Open Terminal. The built-in terminal signs in over SSH with a key the app created for this Mac and keeps in your Keychain. Workspaces made from a cloud image or an automatic install already trust that key.

For a system you installed yourself, type its username in the Access tab, sign in once with the password, then click Install Key so you won't need the password again. You can copy, import or export the key in Settings › Access.

Yes, and that part is free. The Access tab shows the workspace's address with a ready-to-copy ssh command, and the ~/.ssh/config block for VS Code's Remote - SSH extension. Those use your own SSH key, not the one the built-in terminal keeps in the Keychain, so paste your public key under SSH Public Keys when you create the workspace, or turn on Allow SSH logins with the password.

Other computers reach a workspace through your Mac, because workspaces sit on a private network inside it. Turn on Remote Login in System Settings › General › Sharing, then use the ssh -J command shown in the Access tab.

Workspaces sit on a small virtual network inside your Mac (addresses like 192.168.64.x), and macOS counts that as the local network. The SSH check and the terminal connect to that address, so macOS asks once. The app never browses or scans your network; it only talks to its own workspaces.

If you clicked Don't Allow, the Access tab shows No Local Network access. Turn it back on in System Settings › Privacy & Security › Local Network.

macOS workspaces (macOS 13 or later): shared folders mount automatically — open Finder and look under /Volumes/My Shared Files. No command needed.

Linux workspaces: each shared folder gets its own mount command, shown right in the app under the workspace's Shared Files tab. It looks like this, using that folder's own tag:

mkdir -p /mnt/my_folder
sudo mount -t virtiofs <folder-tag-shown-in-app> /mnt/my_folder

Use the exact tag shown in the app — it's unique per folder, so copying a command from somewhere else won't work.

Clipboard sharing on Linux depends on an agent running inside the guest. Work through these in order:

1. In the workspace's Resources tab, confirm Clipboard Sharing is turned on.
2. Inside the guest, make sure spice-vdagent is installed:

   sudo apt install spice-vdagent

3. Confirm the agent is actually running:

   systemctl status spice-vdagentd

   If it's inactive, start it with sudo systemctl start spice-vdagentd, and, if you're on a graphical desktop, log out and back in so the desktop session picks it up.
4. Some minimal or headless desktop environments don't launch spice-vdagent automatically — check your desktop environment's autostart settings if it still doesn't work after the agent is installed and running.

Clipboard sharing currently works for Linux workspaces only.

Debian uses the same apt and update-binfmts tooling as Ubuntu. Turn on Rosetta for the workspace in its Resources tab, start the workspace, then run this once inside the guest:

sudo mkdir -p /media/rosetta
sudo mount -t virtiofs rosetta /media/rosetta

sudo apt-get update
sudo apt-get install -y binfmt-support

sudo /usr/sbin/update-binfmts --install rosetta /media/rosetta/rosetta \
  --magic "\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00" \
  --mask "\xff\xff\xff\xff\xff\xfe\xfe\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff" \
  --credentials yes --preserve yes --fix-binary yes

Fedora doesn't ship Debian's update-binfmts tool, but it does ship systemd-binfmt, which reads the exact same kernel binfmt_misc registration from a config file. Turn on Rosetta for the workspace in its Resources tab, start the workspace, then run this once inside the guest:

sudo mkdir -p /media/rosetta
sudo mount -t virtiofs rosetta /media/rosetta

sudo mkdir -p /etc/binfmt.d
sudo tee /etc/binfmt.d/rosetta.conf > /dev/null <<'EOF'
:rosetta:M::\x7fELF\x02\x01\x01\x00\x00\x00\x00\x00\x00\x00\x00\x00\x02\x00\x3e\x00:\xff\xff\xff\xff\xff\xfe\xfe\x00\xff\xff\xff\xff\xff\xff\xff\xff\xfe\xff\xff\xff:/media/rosetta/rosetta:CF
EOF

sudo systemctl restart systemd-binfmt

The rosetta.conf file persists across reboots, so this is a one-time setup per workspace.

1. Install and run Ollama or MLX on your Mac, outside the workspace.
2. Enable AI Bridge for the workspace (on by default in the AI Sandbox profile, or turn it on yourself in the workspace's Integrations or Resources settings).
3. Start the workspace, then open its AI Bridge tab — it shows the local endpoint address and, for a Linux guest, the exact commands to forward the connection.
4. Inside the workspace, point your tooling at that address the same way you'd point it at any local server that speaks the standard chat-completions API format.

Full setup guide: MLX or Ollama + AI agents in a VM →

Open Diagnostics from the sidebar, then click Export. This bundles your local app logs and system information into a single file on your Mac — handy to attach to an email when working through an issue with us.

Nothing is collected automatically, ever. That export only happens when you run it yourself, and the resulting file stays on your Mac unless you choose to send it.

It's deleted automatically the moment you close it, including its disk. There's nothing to recover afterward — don't use a disposable workspace for anything you need to keep.

Stop the workspace, then choose Save as Base Image from the banner on a stopped workspace. Saving the same workspace again later creates a new, separate base image instead of replacing the old one. Manage and delete base images in Settings › Images › Base Images.

Workspace disks and base images live under ~/Library/Application Support/VeloWorkspaces on your Mac. To free up space, delete workspaces you no longer need from the library, and downloaded images or base images you no longer use from Settings › Images.

Not in this release. Velo Workspaces currently supports Linux and macOS guests.

CPU, memory, storage, shared folders, and a few other settings are part of the virtual machine's configuration and can't be changed while it's running (Apple's Virtualization framework doesn't support hot-plugging them). Stop the workspace, make the change, and start it again.

macOS guests require an Apple silicon Mac as the host. On an Intel Mac, Linux guests are still fully supported.

Velo Workspaces assigns a new, unique MAC address to every workspace, including one cloned from a base image. Ubuntu Server's minimized install configures networking with Netplan on top of systemd-networkd, which by default binds the interface to the base image's original MAC address instead of matching it by interface name — so once the clone has a different MAC, nothing matches and DHCP is never requested.

Find the workspace's actual MAC address, then update it in netplan's configuration:

ip addr show

Note the address shown after link/ether for the interface (commonly enp0s1), then set it as that interface's MAC in netplan's config and reapply:

sudo sed -i 's/macaddress:.*/macaddress: <new-mac-address>/' /etc/netplan/*.yaml
sudo netplan apply