Persistent /workspace

Without it, a MicroVM's files are gone when it stops, apart from what you push. With it, /workspace lives on an Amazon EFS file system and outlives every MicroVM.

Making a file system

A file system lives on a VPC network connector; see Network Connectors. In Settings → Storage, choose the region at the top, then New File System…, name it, and choose its type (Amazon EFS, the only one today) and the Network connector: one that exists in that region, never a new one. No connector yet? Open Network Connectors takes you to Settings → Network to make one. The file system gets a mount target in each Availability Zone of the connector's subnets.

The Security group for the mount targets is Create new, which lets NFS in from the connector's security group only, or Use existing. For an existing group, MicroVM Studio adds the NFS rule (TCP 2049 from the connector's security group) if it's missing, and tells you it did. It deletes a group only if it made it; for one of yours, it removes at most the rule it added, and only with the last file system that uses it. If your group also lets NFS in from other groups, the sheet warns you that the file system would be reachable from there too. A connector can't use a client security group another connector already has.

Before Create, the sheet lists what it makes: the group if new, and the encrypted EFS file system. It takes about 2 minutes, and closing the sheet doesn't stop it. Resume picks up a create that stopped. Refresh checks the file systems against AWS again, as opening the tab does.

Using it

Choose the file system under Persistent /workspace in the workspace's Storage section. Each workspace gets its own folder on it, which no other workspace can reach, mounted at /workspace. Repos are cloned there, and the terminal and start command open there.

The workspace's image needs All OS capabilities and EFS tools; the starter image has both. With Lifecycle hooks in the image too, as in the starter image, /workspace is mounted while the MicroVM starts, so it's ready when you connect; that makes the launch about 12 seconds longer. Without them, it's mounted when the terminal connects. Either way, each connect checks the mount and repairs it if needed. See Images.

A role of its own

Root in the MicroVM can use the workspace's role, so the role must reach this workspace's folder and nothing else. Persistent /workspace therefore needs a role made by MicroVM Studio that no other workspace uses: choose New Role…. Saving the workspace lets the role into its folder, and the file system's policy keeps everyone else out of it. The role stays this workspace's for good, even once the workspace is deleted, so no other workspace can take it.

A role that can change file system policies or its own permissions (PowerUserAccess or AdministratorAccess can) could undo those rules. A MicroVM reaches every file system on its network, so such a role may only keep /workspace on a network where no other workspace keeps its own, and no other workspace may join a file system on that network. The same goes for a workspace that only leaves through the connector, with no storage of its own: it is on that network too, so with a role like that it can't use a connector another workspace keeps /workspace behind (choose Internet, or a connector of its own). Connectors that share one client security group count as one network. Saving checks this with the IAM policy simulator, and Settings → Storage flags a workspace whose role has become able to since.

A MicroVM keeps the storage it was launched with. After changing a workspace's storage, start a new MicroVM to use it.

Internet

A MicroVM with a persistent /workspace leaves through its file system's connector, so it reaches the internet only if that connector's VPC routes its subnets to a NAT gateway, which you set up in your VPC. Without one, GitHub, package installs, Claude Code and Codex won't work. Settings → Storage shows Internet: yes or Internet: no for each file system.

View…

View… in Settings → Storage shows the file system's type, network, health, mount targets and their state, and the workspaces using it.

Costs

A NAT gateway in your VPC has a cost of its own, which you pay your VPC's account for: see Network Connectors. The menu bar's estimate doesn't include any of these.

Deleting

Delete… in Settings → Storage, or Delete File System… in View…, deletes the file system and every workspace's files on it, and can't be undone. Its network connector stays. Workspaces that used it go back to having no persistent /workspace. Deleting a workspace, or setting its storage to None, keeps its folder: choose the same file system again for that workspace to get its files back.