Skip to main content

Running FUSE on MorphVMs

FUSE, short for Filesystem in Userspace, lets ordinary userspace programs implement filesystems without adding a custom kernel module for each one. In practice, that is what powers tools such as sshfs, s3fs, AgentFS-style workspace mounts, and fuse-overlayfs.

On MorphVMs, the important distinction is between kernel/device support and guest userspace tooling. Fresh current morphvm-minimal instances already expose the kernel side of FUSE: nodev fuse appears in /proc/filesystems and /dev/fuse exists. What they do not currently ship by default are the userspace packages that many workloads expect, such as fuse3 and fuse-overlayfs.

That means many reports that look like "MorphVM does not support FUSE" are really "this guest still needs the right userspace package." If you are working from an older or custom snapshot, verify the state inside the guest first before assuming you need a platform change.

Before You Start​

You can run the commands below through SSH or Command Execution. The examples assume a Debian-based instance such as morphvm-minimal and a root shell; if you are using an unprivileged user, prefix the package-management commands with sudo.

1. Verify the Current State​

Run these checks inside the instance before installing anything:

grep fuse /proc/filesystems || true
ls -l /dev/fuse
command -v fusermount3 || true
dpkg -l fuse3 fuse-overlayfs 2>/dev/null | grep '^ii' || true

Interpret the results like this:

  • nodev fuse in /proc/filesystems and a real /dev/fuse device mean the kernel/device side is present.
  • If fusermount3 is missing and dpkg -l shows no installed fuse3 package, the guest is missing the userspace tooling.
  • If you are using an older or custom snapshot and /dev/fuse is missing, compare it against a fresh current morphvm-minimal instance before treating it as a platform-wide regression.

2. Install the Userspace Packages You Need​

For many workloads, fuse3 is the important baseline package. Install fuse-overlayfs only when you need overlay-style FUSE mounts or rootless container workflows that depend on it.

apt-get update
apt-get install -y fuse3

# Optional: install this too if your workload needs overlay-style FUSE mounts
apt-get install -y fuse-overlayfs

If your workload uses a specific FUSE filesystem, install that package too. For example, sshfs needs the sshfs package even after fuse3 is present.

3. Run a Minimal FUSE Sanity Check​

The simplest verified check on a fresh MorphVM is a fuse-overlayfs mount. This is useful because it exercises /dev/fuse, the FUSE userspace tooling, and a real mount/unmount cycle.

set -euo pipefail

apt-get update
apt-get install -y fuse3 fuse-overlayfs

mkdir -p /tmp/fuse-demo/lower /tmp/fuse-demo/upper /tmp/fuse-demo/work /tmp/fuse-demo/merged
printf 'hello from MorphVM\n' >/tmp/fuse-demo/lower/hello.txt

fuse-overlayfs \
  -o lowerdir=/tmp/fuse-demo/lower,upperdir=/tmp/fuse-demo/upper,workdir=/tmp/fuse-demo/work \
  /tmp/fuse-demo/merged &
FUSE_PID=$!

sleep 2
cat /tmp/fuse-demo/merged/hello.txt
printf 'written through FUSE\n' >/tmp/fuse-demo/merged/write.txt
test -f /tmp/fuse-demo/upper/write.txt

fusermount3 -u /tmp/fuse-demo/merged
wait "$FUSE_PID" || true

If cat /tmp/fuse-demo/merged/hello.txt prints the file and /tmp/fuse-demo/upper/write.txt exists afterward, the FUSE path is working on that instance.

4. Make the Setup Reusable​

FUSE packages live in the guest OS. If you need them on every future instance, save them into a snapshot instead of repeating apt-get install on every boot.

  • If you already installed the packages on a running instance, create a snapshot from that configured VM with Basic Operations.
  • If you want a more repeatable build flow, use Snapshot Setup to run apt-get update && apt-get install -y fuse3 fuse-overlayfs during snapshot creation.
  • When you want a fresh machine with that disk state, launch it with Boot from Snapshot.
Want the shortest path to a repeatable FUSE-ready base?

Bake fuse3 and any workload-specific FUSE package into a reusable snapshot once, then boot future instances from that snapshot instead of reinstalling packages every time.

Troubleshooting​

/dev/fuse is missing​

If you started from an older or custom snapshot, compare it against a fresh current morphvm-minimal instance first. The current documented baseline is that fresh current morphvm-minimal instances expose /dev/fuse. If a fresh current base still lacks /dev/fuse, treat that as a platform issue rather than a normal guest-package problem.

fusermount3 is missing​

Install fuse3. Kernel support alone is not enough for most FUSE workflows.

fuse-overlayfs is missing​

Install fuse-overlayfs in addition to fuse3. fuse3 provides the base userspace tooling, but it does not provide every FUSE-backed filesystem implementation.

Your workload still fails after installing packages​

First, run the fuse-overlayfs sanity check above. If that succeeds, the MorphVM FUSE path is working and the remaining problem is likely specific to your filesystem package, mount options, or application-level setup.

You need NFSv3 instead​

This page only covers FUSE on MorphVMs. NFSv3 is a separate capability question and should not be inferred from the FUSE guidance here.

See Also​