Skip to content
docs.microagent.sh

Storage

Last updated: 2026-06-27

A workspace sees block devices, never host directories. microagent does not expose host bind mounts - everything the guest reads or writes is an ext4 disk image or the rootfs - which keeps the host filesystem outside the workspace boundary by construction. This page maps every way data gets into, out of, and between workspaces, and which to pick. For the hands-on walkthrough of these mechanisms, see Use volumes and move data.

The rootfs

Section titled “The rootfs”

Every workspace boots from a rootfs: an ext4 image built from an OCI image (run/create) or an existing rootfs path. It is per-workspace and lives under <state-dir>/workspaces/<name>/rootfs.ext4. Writes inside the guest persist in that image across stop/start, and are discarded by delete (and by run --delete). commit snapshots a stopped rootfs back into an OCI image.

Attaching extra storage

Section titled “Attaching extra storage”

Beyond the rootfs, a workspace can attach additional disks at declared mountpoints. There are three sources, all available through -v/--volume (and the spec’s disks/bundles):

SourceSyntaxWhat it isLifecycle
ext4 image-v /path/data.ext4:/dataAn existing ext4 file attached as a diskYou own the file
tar bundle-v /path/ctx.tar:/ctx:roA .tar/.tar.gz/.tgz built into a one-shot ext4 disk at startBuilt per start
named volume-v data:/dataA platform-managed ext4 disk addressed by nameManaged by microagent

A bare name (no path separator or extension) is a named volume; a path ending in .tar/.tar.gz/.tgz is a bundle; a path ending in .ext4/.img is a raw disk image. Host directories are rejected with guidance - package a directory as a tar for ingress, or use cp against a stopped workspace.

Named volumes

Section titled “Named volumes”

A named volume is the in-boundary analog of a container volume: a managed ext4 disk with a lifecycle independent of any one workspace. Instead of hand-managing .ext4 files, create one and attach it by name.

Terminal window
microagent volume create data --size-mib 2048
microagent run docker.io/library/python:3.12 --volume data:/work

Volumes live under <state-dir>/volumes/ (an index.json registry plus one <name>.ext4 per volume). A volume is single-attach: at most one running workspace holds it at a time, so two VMs never mount the same ext4 read-write. A holder that is no longer running is reclaimed automatically, and deleting a workspace releases the volumes it held; the data persists for the next attach.

This is deliberately not the Docker volume model - there is no daemon, no volume drivers, and no concurrent sharing between workspaces. It is a managed disk that maps cleanly onto microVM semantics.

Egress

Section titled “Egress”

To get data out of a workspace, declare --output paths or use cp against a stopped workspace. A named volume is also a natural handoff: write results to it in one workspace, attach it to another.

See also

Section titled “See also”