> ## Documentation Index
> Fetch the complete documentation index at: https://docs.machine0.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Folders (alpha)

> Shared, persistent network filesystems you can mount on any VM.

<Warning>
  Folders are an **alpha** feature. The `folders` commands are hidden by
  default — set `USE_EXPERIMENTAL_FEATURES=true` in your environment to enable
  them. The commands and behavior described here may change, and you should
  keep copies of anything you cannot afford to lose.
</Warning>

A folder is a named, persistent filesystem that lives independently of any VM.
Mount the same folder on several VMs to share files between them, or use it to
keep data alive across VM destroy/recreate cycles.

* **Persistent:** destroying a VM never touches folder data. The folder exists
  until you run `machine0 folders rm`.
* **Shared:** mount one folder on multiple VMs at the same time.
* **25 GiB per folder** (default quota), **5 folders per account**, free during
  the alpha.
* Folders have a single home region. VMs in any region can mount them; VMs
  farther from the home region see higher latency.

## Consistency and performance

Folders provide **close-to-open consistency**: when one VM closes a file and
another VM subsequently opens it, the second VM sees the data the first one
wrote. Two VMs holding the same file open concurrently do not see each other's
writes until close/open.

Folders are slower than local disk, especially for metadata-heavy work (git
operations, `npm install`, compiling large trees). Use local disk for working
sets and folders for sharing and persistence.

<Note>
  Writes are uploaded to storage in the background. Destroying a VM within a few
  seconds of writing can lose the last writes, and other VMs may need a moment
  after a file is closed before they see it.
</Note>

## Quickstart

Create a folder and mount it on a VM:

```bash theme={"theme":"css-variables"}
$ machine0 folders new code
✓ Folder "code" is ready (25 GiB)

   Mount it on a new VM:  machine0 new <vm> --mount folder:code path:/data

$ machine0 new dev1 --mount folder:code path:/data
✓ VM is starting
```

SSH in and write a file to the folder (if `/data` is missing right after
boot, cloud-init is still installing the mount — give it a minute):

```bash theme={"theme":"css-variables"}
$ machine0 ssh dev1
dev1$ df -h /data
Filesystem      Size  Used Avail Use% Mounted on
JuiceFS:code     25G  4.0K   25G   1% /data
dev1$ echo "hello from dev1" > /data/hello.txt
dev1$ exit
```

Mount the same folder on a second VM — both see the same files:

```bash theme={"theme":"css-variables"}
$ machine0 new dev2 --mount folder:code path:/data
✓ VM is starting

$ machine0 ssh dev2
dev2$ cat /data/hello.txt
hello from dev1
dev2$ exit
```

Destroy both VMs. The folder — and its data — survives:

```bash theme={"theme":"css-variables"}
$ machine0 rm dev1 -y
✓ VM "dev1" destroyed
$ machine0 rm dev2 -y
✓ VM "dev2" destroyed

$ machine0 folders ls
┌──────┬────────┬────────┬────────┬────────────┐
│ Name │ Status │ Size   │ Mounts │ Created    │
├──────┼────────┼────────┼────────┼────────────┤
│ code │ READY  │ 25 GiB │ 0      │ 2026-07-08 │
└──────┴────────┴────────┴────────┴────────────┘
```

The files are still there too — browse them without mounting the folder
anywhere with [`machine0 folders get code`](/cli/folders#folders-get).

Prove it by mounting the folder on a third VM:

```bash theme={"theme":"css-variables"}
$ machine0 new dev3 --mount folder:code path:/data
✓ VM is starting

$ machine0 ssh dev3
dev3$ cat /data/hello.txt
hello from dev1
dev3$ exit
$ machine0 rm dev3 -y
✓ VM "dev3" destroyed
```

When you are done with the folder, remove it. This deletes **all** of its data
permanently:

```bash theme={"theme":"css-variables"}
$ machine0 folders rm code
Are you sure you want to destroy folder "code" and ALL its data? This cannot be undone. (y/N) y
✓ Folder "code" destroyed
```

## Rules and limits

* A folder can only be removed when no VM mounts it — destroy (or
  suspend-destroy) the VMs first. `folders rm` tells you which VMs are in the
  way.
* Mounts are set at VM creation (`--mount`, repeatable). Attaching a folder to
  an already-running VM is not supported in the alpha.
* Folder names: lowercase letters, numbers, and hyphens, max 31 characters.
  Mount paths: absolute paths like `/data` (letters, numbers, `/`, `_`, `-`);
  system directories (`/etc`, `/usr`, `/var`, ...) are not allowed.
* Suspending a VM keeps its mounts: they come back automatically on resume.
* VM images and snapshots taken from a VM with mounted folders can carry the
  folder's access credentials on disk. `folders rm` revokes those credentials
  everywhere, permanently.
* NixOS images do not support folder mounts (mounts are installed via
  cloud-init).