TrueNAS VMs on iPhone, iPad and Mac

Which TrueNAS versions work

Saffron speaks SPICE, so it needs a VM with a SPICE display. TrueNAS SCALE (now TrueNAS Community Edition) has one; CORE doesn’t.

1. Give the VM a SPICE display

On 24.10 and 25.04.2 the Create Virtual Machine wizard already made one if Enable Display was on, so go straight to step 2. From 25.10 the wizard makes a VNC display instead, so add a SPICE one:

1. Open Virtual Machines, expand the VM and stop it. Display changes apply when the VM next starts, and TrueNAS won’t delete a device from a running VM.
2. Click Devices. If there’s a VNC display you don’t use, remove it with ⋮ → Delete. One display is the simplest setup.
3. Click Add, set Type to Display and Display Type to SPICE.
4. Bind: 0.0.0.0, or your TrueNAS LAN address. Not 127.0.0.1 or ::1: only the NAS itself can reach those.
5. Password: required. Keep it under 60 characters. The 8-character limit you may see mentioned applies to VNC, not SPICE.
6. Port: leave it empty and TrueNAS saves the next free port from 5900 up, or enter your own between 5900 and 65535, such as 5910. Either way it stays put, so your saved connection keeps working.
7. Resolution: pick one for the screen you use most. 1280x720 reads well on a phone, 1920x1080 on a Mac.
8. Web Interface is optional. It keeps the browser console available on a separate Web Port.
9. Save, then start the VM.

2. Find the address and port

Under Devices, open ⋮ → Details on the Display device. It lists the port, the bind address and the password. On 25.10, if the VM has no VNC display and Web Interface is off, the running VM’s Display button tells you too: “Connect using a SPICE client to” the bind address and port. If it says “VNC client”, that’s the VNC display’s port, not the SPICE one.

• If the bind is 0.0.0.0, connect to your TrueNAS IP: the address you open the TrueNAS web UI on.
• Use Port, not Web Port. The Web Port is for the browser console.

3. Add it to Saffron

iPhone and iPad

1. Tap + (or Add your first server).
2. Fill in Name, Host (the TrueNAS IP), Port and the Password, then tap Save. Saffron keeps the password in the device’s Keychain.
3. Tap the card to connect. The first time, allow Saffron on your local network. If you said no, turn it back on in Settings → Privacy & Security → Local Network.

Mac

1. File → Connections… (⌘L), then click ＋.
2. Fill in Name, Host, Port and Password, then click Save & Connect.

4. Copy and paste both ways

Clipboard sharing needs the SPICE agent inside the VM. TrueNAS already adds the channel it talks over, so installing the agent is all there is to it. On a Debian or Ubuntu guest:

sudo apt install spice-vdagent

Log out and back in afterwards. On a Windows guest, install the SPICE Guest Tools from spice-space.org.

• iPhone and iPad: copy as usual, then tap the clipboard button in the session to send it. Anything you copy in the VM lands on your device on its own.
• Mac: it flows both ways by itself while the VM’s window is in front. Text and images both work.

If copy and paste stays dead on a Wayland desktop, try an Xorg session: the agent’s Wayland clipboard support is still being worked on upstream.

Screen size and sound

• Saffron shows the VM at its own resolution and fits it to your screen, with pinch-to-zoom and pan on iPhone and iPad. It doesn’t resize the guest, so choose the resolution in the Display device or inside the VM.
• TrueNAS doesn’t give VMs a virtual sound card, so a TrueNAS VM has no audio to send. Saffron’s sound and microphone switches work with hosts that add one.

Away from home

The SPICE port isn’t encrypted, so never forward it to the internet. Put the NAS on a VPN instead: install Tailscale from TrueNAS Apps and advertise your LAN as a subnet route, or run WireGuard. With the same VPN on your phone or Mac, Saffron connects exactly as it does at home.

If it doesn’t connect

“Connection failed — is the server reachable?”

• The VM isn’t running.
• Bind is 127.0.0.1 or ::1, or you typed 0.0.0.0 as the host instead of the TrueNAS IP.
• The port is wrong, or nothing is listening on it. Check Port in Details.
• On iPhone or iPad, Local Network access for Saffron is off.
• You’re away from home without the VPN on.

“Authentication failed — check the password”

• The password doesn’t match the one in Details.
• The password is 60 characters or longer. Set a shorter one.

Stuck on “Connecting…”

You probably entered the Web Port. That one belongs to the browser console, so use Port from Details instead.

It connects, then drops

Someone opened the VM’s Display button in TrueNAS with Web Interface on. SPICE serves one viewer at a time, so the browser took over.

Black screen

The VM may still be booting, or its screen has gone to sleep: tap or press a key. If the VM has both a VNC and a SPICE display, remove the VNC one.

Still stuck? Tell us what you see, and which TrueNAS version you run.