Skip to main content

Getting started with Morph EFS

Morph EFS, short for Ephemeral File System, is a Morph-managed ephemeral filesystem. It gives your workload a normal Linux path for files and directories, instead of an object storage API.

Use EFS when a workload needs a mounted path such as ~/morph-efs/shared-files rather than an object-storage API.

Prerequisites​

  • A Morph API key.
  • A Morph-managed Linux VM/devbox, or an equivalent FUSE-capable Linux host.
  • uv and morphcloud available in the target environment.
  • Morph private package access preconfigured by the Morph-managed environment. On an equivalent external host, package access must already be configured before install.

EFS does not install OS packages or run sudo during normal use. See Mount requirements if a mount fails before it starts.

Install the EFS client​

Authenticate once with your Morph API key, then install the EFS client:

export MORPH_API_KEY="morph_your_api_key"
uv auth login https://simple-index.svc.cloud.morph.so --token "$MORPH_API_KEY"
uv tool install morphcloud-efs-client
morphcloud profile set default --api-key "$MORPH_API_KEY"
morphcloud profile use default

Confirm the command is available:

morphcloud efs --help

To upgrade later, use:

uv tool upgrade morphcloud-efs-client

Morph EFS can also show a short update notice from interactive morphcloud efs commands when a newer client is available. It never auto-upgrades, does not appear in --json output, and does not run from uv tool install.

If your shell still resolves an older morphcloud command after install, refresh the shell command cache:

hash -r

Create a filesystem​

morphcloud efs create shared-files --ttl 1800
morphcloud efs get shared-files

The create command creates or reuses a filesystem with the requested name for your authenticated Morph context. The optional --ttl sets a filesystem TTL in seconds.

Inspect with the TUI or dashboard​

For interactive workflows, EFS provides a terminal TUI and a browser dashboard:

morphcloud efs tui
morphcloud efs dashboard

Use them to inspect filesystems, watch mount status, create or mount a filesystem, unmount, and browse a mounted filesystem. See TUI and dashboard for details.

Mount and use the filesystem​

Mount with the default path:

morphcloud efs mount shared-files

morphcloud efs mount <filesystem> asks EFS to mount the filesystem on this machine. The command returns when the mount path is ready.

By default, the mount path is:

~/morph-efs/<filesystem>

Write, flush, and read a file through the mounted path:

echo hello > ~/morph-efs/shared-files/test.txt
sync
cat ~/morph-efs/shared-files/test.txt

To choose the mount path yourself, pass it as the second argument:

mkdir -p /tmp/shared-files
morphcloud efs mount shared-files /tmp/shared-files

Mount from another host​

To share files across hosts, mount the same filesystem name from another supported Morph-managed Linux host using the same Morph context:

morphcloud efs mount shared-files
cat ~/morph-efs/shared-files/test.txt

Run sync after writes when you need another host to read the data immediately.

Inspect usage​

morphcloud efs usage shared-files

Usage output includes usage status, active mount count, sampled bytes used, and estimated monthly cost when EFS billing is enabled.

Unmount and delete​

Unmount when the mount path is no longer needed. This ends the active mount:

morphcloud efs unmount shared-files

Delete the filesystem when you are done with it. Delete marks the filesystem for cleanup:

morphcloud efs delete shared-files --yes

Cleanup completes asynchronously. Active mounts can delay cleanup, so unmount first when you are actively using the filesystem from a mounted path.

Next steps​