Skip to main content

Getting started with Morph EFS

Morph EFS, short for Elastic File System, is a Morph-managed elastic 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. Use Morph Volumes when you want object storage for buckets and objects.

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.

Open the interactive EFS experience​

morphcloud efs tui

The TUI is the normal interactive EFS experience. Use it to inspect filesystems, watch mount status, create or mount a filesystem, unmount it, and browse a mounted filesystem.

If you have multiple ready filesystems, pass the filesystem name explicitly:

morphcloud efs tui shared-files

Open the browser dashboard​

Open the EFS dashboard for your current Morph context:

morphcloud efs dashboard

Open a specific filesystem:

morphcloud efs dashboard shared-files

The dashboard command creates a temporary browser link from your current Morph profile. Your Morph API key is not placed in the browser URL.

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​

  • Read Concepts for the EFS mental model.
  • Read CLI for command details.
  • Read Dashboard for the browser workflow.
  • Read TUI for the interactive workflow.
  • Read Troubleshooting if install, auth, or mount setup fails.