Volumes

On microsandbox cloud: Volumes use fast block storage managed by the platform. Every organization automatically gets an undeletable host volume: think of it as the disk of the one computer all its sandboxes run on, and it is what bind and disk-image mounts resolve against.

Volumes give a sandbox persistent or shared storage by mounting host data, managed storage, disk images, or in-memory filesystems into the guest. Mounts provide direct filesystem access and are significantly faster than the filesystem API, which transfers files individually, so they are preferable for anything beyond ad-hoc reads and writes. Choose bind mounts, named volumes, disk-image volumes, or tmpfs. Local sandboxes also support owned volumes: private storage that lives and dies with the sandbox.

Temporary files

For OCI sandboxes with a disk-backed root, /tmp uses the root disk unless you explicitly mount another filesystem there. Large package downloads and build files therefore consume disk capacity and leave guest RAM available for build processes. For a new Cloud OCI sandbox that omits disk size, the writable-disk default matches requested RAM, bounded to 4–16 GiB. Explicit disk sizes and restored snapshot sizes take precedence. Disk-backed temporary files can survive stop/start and be included in snapshots; remove them when they are no longer needed. An explicit tmpfs mount remains available for workloads that need RAM-backed, per-boot scratch space. Existing sandbox configurations with a saved tmpfs mount retain it on restart. OCI roots explicitly configured as tmpfs keep their bounded /tmp tmpfs default.

Cloud default volume

Every cloud organization has an always-present default volume. You can read and write it directly without starting a sandbox:

const volume = await Volume.getDefault();
await volume.fs().write("state.json", JSON.stringify({ ready: true }));

let volume = Volume::get_default().await?;
volume.fs().write("state.json", br#"{"ready":true}"#).await?;

volume = await Volume.get_default()
await volume.fs().write("state.json", b'{"ready": true}')

volume, err := m.GetDefaultVolume(ctx)
err = volume.FS().WriteString(ctx, "state.json", `{"ready":true}`)

microsandbox isolates the default volume to the authenticated cloud organization, and you cannot remove it. microsandbox deliberately does not support default-volume lookup on the local backend: forgetting an API key cannot expose or modify files from your machine. Named local volumes continue to live under ~/.microsandbox/volumes/ and retain their existing direct filesystem API.

Bind mounts

Mount a directory from the host directly into the sandbox. Changes inside the sandbox are reflected on the host, and vice versa.

import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("dev")
    .image("python")
    .volume("/app/src",  (m) => m.bind("./src").readonly().noexec())
    .volume("/app/data", (m) => m.bind("./data"))
    .create();

let sb = Sandbox::builder("dev")
    .image("python")
    .volume("/app/src", |v| v.bind("./src").readonly().noexec())
    .volume("/app/data", |v| v.bind("./data"))
    .create()
    .await?;

from microsandbox import Sandbox, Volume

sb = await Sandbox.create(
    "dev",
    image="python",
    volumes={
        "/app/src": Volume.bind("./src", readonly=True, noexec=True),
        "/app/data": Volume.bind("./data"),
    },
)

sb, err := m.CreateSandbox(ctx, "dev",
    m.WithImage("python"),
    m.WithMounts(map[string]m.MountConfig{
        "/app/src":  m.Mount.Bind("./src", m.MountOptions{Readonly: true, Noexec: true}),
        "/app/data": m.Mount.Bind("./data", m.MountOptions{}),
    }),
)

msb create python --name dev \
  --mount-dir ./src:/app/src:ro,noexec \
  --mount-dir ./data:/app/data

microsandbox supports nested destinations. It canonicalizes guest paths and always applies enclosing mounts before their children. SDKs that accept unordered maps (such as Go) produce the same result regardless of map iteration order. Use --mount-file when you want to bind one host file instead of an entire directory. File mounts expose the selected host inode through an isolated one-entry filesystem. They do not hard-link or copy the source, host changes remain visible, and other files in the source directory are not part of the guest-visible share. Writable file mounts receive the same default quota as directory binds; use quota=<size> to set a smaller or larger guest-growth budget.

msb create alpine --name config-reader \
  --mount-file ./config.toml:/etc/app/config.toml:ro,nodev

Owned volumes

Use an owned volume when the data belongs to one sandbox. No volume name or separate cleanup is needed. It starts empty, survives stop/start, and is removed with the sandbox. Mounting over an existing image directory hides its contents; it does not copy them into the volume.

msb create alpine --name app --mount-owned /data

# An ext4 disk, useful for Docker's data root
msb create docker:dind --name docker-app \
  --mount-owned /var/lib/docker:kind=disk,size=10G

const sb = await Sandbox.builder("app").image("alpine")
  .volume("/data", (v) => v.owned())
  .volume("/disk", (v) => v.owned({ kind: "disk", sizeMib: 1024 }))
  .create();

let sb = Sandbox::builder("app")
    .image("alpine")
    .volume("/data", |v| v.owned())
    .volume("/disk", |v| v.owned_with(|d| d.disk().size(1024_u32)))
    .create().await?;

sb = await Sandbox.create("app", image="alpine", volumes={
    "/data": Volume.owned(),
    "/disk": Volume.owned(kind=VolumeKind.DISK, size_mib=1024),
})

sb, err := m.CreateSandbox(ctx, "app", m.WithImage("alpine"),
    m.WithMounts(map[string]m.MountConfig{
        "/data": m.Mount.Owned(m.OwnedVolumeOptions{}),
        "/disk": m.Mount.Owned(m.OwnedVolumeOptions{Kind: m.VolumeKindDisk, SizeMiB: 1024}),
    }),
)

Disk-only snapshots capture owned data too. Full snapshots and branches retain it along with execution state. Restoring or branching creates private copies automatically; no mount mapping or inheritance flag is needed, and child writes never change the source’s data. Use a named volume instead when data should outlive or be shared between sandboxes. Owned-directory snapshots retain platform-specific filesystem metadata and cannot move between Unix (macOS/Linux) and Windows. Owned disks do not have this directory-format restriction; full snapshots still require a compatible execution-state restore target.

Named volumes

microsandbox manages named volumes and stores them by default under ~/.microsandbox/volumes/<name>/. They persist independently of any sandbox, so you can create a volume, populate it, and mount it into different sandboxes over time. Named volumes can be directory-backed or disk-backed. Directory volumes mount through virtiofs. Disk volumes are raw ext4 disk images that microsandbox manages, and they mount through virtio-blk. CLI named mounts are idempotent. -v name:/path and --mount-named name:/path create a directory-backed named volume if it does not already exist, then mount it. If the volume already exists, microsandbox reuses it when the requested storage settings are compatible and errors when they are not. Use --mount-named name:/path:kind=disk,size=20G to create or reuse a disk-backed named volume from the mount flag itself. SDK named(...) mount helpers are existing-only. They fail if the named volume does not already exist. Use each SDK’s explicit named-volume mode API when you want sandbox creation to create or ensure the volume.

Create a volume

import { Volume } from "microsandbox";

const cache = await Volume.builder("pip-cache").create();

let cache = Volume::builder("pip-cache")
    .create()
    .await?;

cache = await Volume.create("pip-cache")

cache, err := m.CreateVolume(ctx, "pip-cache")

cache = Microsandbox::Volume.builder("pip-cache").directory.create

msb volume create pip-cache

Create a disk-backed named volume when a workload needs a real guest block filesystem, such as Docker’s data root:

const dockerData = await Volume.builder("docker-data")
  .disk()
  .size(20 * 1024)
  .create();

let docker_data = Volume::builder("docker-data")
    .disk()
    .size(20.gib())
    .create()
    .await?;

from microsandbox import VolumeKind

docker_data = await Volume.create(
    "docker-data",
    kind=VolumeKind.DISK,
    size_mib=20 * 1024,
)

dockerData, err := m.CreateVolume(ctx, "docker-data",
    m.WithVolumeKind(m.VolumeKindDisk),
    m.WithVolumeSize(20 * 1024),
)

docker_data = Microsandbox::Volume.builder("docker-data")
  .disk
  .size(20 * 1024)
  .create

msb volume create docker-data --kind disk --size 20G

Mount in a sandbox

await using sb = await Sandbox.builder("worker")
    .image("python")
    .volume("/root/.cache/pip", (m) => m.named(cache.name))
    .create();

let sb = Sandbox::builder("worker")
    .image("python")
    .volume("/root/.cache/pip", |v| v.named(cache.name()))
    .create()
    .await?;

sb = await Sandbox.create(
    "worker",
    image="python",
    volumes={
        "/root/.cache/pip": Volume.named(cache.name),
    },
)

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("python"),
    m.WithMounts(map[string]m.MountConfig{
        "/root/.cache/pip": m.Mount.Named(cache.Name(), m.MountOptions{}),
    }),
)

msb create python --name worker \
  --mount-named pip-cache:/root/.cache/pip

The CLI command above creates pip-cache as a directory-backed named volume if it is missing. To create or reuse a disk-backed named volume while mounting it:

msb create docker:dind --name docker-demo \
  --mount-named docker-data:/var/lib/docker:kind=disk,size=20G

Mount the same directory-backed named volume into multiple sandboxes when they need to share files. Use readonly on consumers that should not write. microsandbox attaches disk-backed named volumes as block devices; use one writable sandbox at a time, or read-only mounts where sharing is intended. Directory-backed named volumes are also accessible without a running sandbox, so you can pre-populate a cache or inspect output after the sandbox stops. Local volumes expose their host path directly; cloud default and managed directory volumes use the same volume filesystem API shown above. Disk-backed local volumes store guest data inside disk.raw; host filesystem helpers operate on the managed volume directory, not the filesystem inside the disk image.

Manage volumes

const volumes = await Volume.list();
await Volume.remove("old-cache");

let volumes = Volume::list().await?;
Volume::remove("old-cache").await?;

volumes = await Volume.list()
await Volume.remove("old-cache")

volumes, err := m.ListVolumes(ctx)
err = m.RemoveVolume(ctx, "old-cache")

volumes = Microsandbox::Volume.list
Microsandbox::Volume.remove("old-cache")

msb volume ls
msb volume rm old-cache

Disk-image volumes

Disk-image volumes attach a host disk image as a virtio-blk device and mount its inner filesystem at a guest path. Use them when you want persistent state isolated from ordinary host filesystem metadata, or when distributing a prebuilt filesystem image. The disk format defaults from the file extension (.qcow2, .raw, .vmdk; otherwise raw). microsandbox auto-detects the inner filesystem type unless you set fstype.

await using sb = await Sandbox.builder("seeded")
    .image("alpine")
    .volume("/seed", (m) => m.disk("./seed.raw").readonly().noexec())
    .create();

let sb = Sandbox::builder("seeded")
    .image("alpine")
    .volume("/seed", |v| v.disk("./seed.raw").readonly().noexec())
    .create()
    .await?;

sb = await Sandbox.create(
    "seeded",
    image="alpine",
    volumes={"/seed": Volume.disk("./seed.raw", readonly=True, noexec=True)},
)

sb, err := m.CreateSandbox(ctx, "seeded",
    m.WithImage("alpine"),
    m.WithMounts(map[string]m.MountConfig{
        "/seed": m.Mount.Disk("./seed.raw", m.DiskOptions{Readonly: true, Noexec: true}),
    }),
)

msb create alpine --name seeded \
  --mount-disk ./seed.raw:/seed:ro,noexec,fstype=ext4

Tmpfs

An in-memory filesystem that disappears when the sandbox stops. Useful for scratch space, build artifacts, or anything that doesn’t need to outlive the sandbox.

import { Sandbox } from "microsandbox";

await using sb = await Sandbox.builder("worker")
    .image("alpine")
    .volume("/tmp/scratch", (m) => m.tmpfs().size(100).noexec())
    .create();

let sb = Sandbox::builder("worker")
    .image("alpine")
    .volume("/tmp/scratch", |v| v.tmpfs().size(100).noexec())
    .create()
    .await?;

sb = await Sandbox.create(
    "worker",
    image="alpine",
    volumes={
        "/tmp/scratch": Volume.tmpfs(size_mib=100, noexec=True),
    },
)

sb, err := m.CreateSandbox(ctx, "worker",
    m.WithImage("alpine"),
    m.WithMounts(map[string]m.MountConfig{
        "/tmp/scratch": m.Mount.Tmpfs(m.TmpfsOptions{SizeMiB: 100, Noexec: true}),
    }),
)

msb create alpine --name worker \
  --tmpfs /tmp/scratch:100:noexec

Mount options

Mounts use normal Linux behavior by default: writable, executable, suid-enabled, and device-enabled. Adjust with:

readonly / ro when the guest should not write to the mount.
noexec when files on the mount should not be executed directly.
nosuid when setuid/setgid bits should be ignored.
nodev when device files should be ignored.

noexec does not stop interpreters from reading scripts from the mount, for example sh /app/src/script.sh. For stronger in-guest hardening, create the sandbox with the restricted security profile. Restricted sandboxes set no_new_privs, drop mount-admin capability from user commands, and force nosuid,nodev on user mounts. This profile is incompatible with workloads such as sudo and Docker-in-Docker.

Fallback guest ownership

Bind mounts and directory-backed named volumes normally present host files without a per-file metadata override using the sandbox user’s fallback identity. Set a mount owner when those files should consistently appear as another guest (uid, gid) pair. This changes only the guest view: it does not chown the host files or create per-file metadata overrides, and an existing per-file override still takes precedence. Both IDs are required together and may range from 0 through 4294967295. Mount owners require stat virtualization, so they cannot be combined with stat-virt=off, tmpfs, host disk images, or disk-backed named volumes. The local backend supports this policy; the cloud backend currently rejects it until ownership capability negotiation is available.

CLI syntax and flags

Most CLI mount flags use SOURCE:DEST[:OPTIONS]; --mount-owned only needs DEST[:OPTIONS]. The : before OPTIONS starts the option block, and commas separate options inside that block.

Flag	Source	Options
`--mount-dir`	Host directory	`ro`, `rw`, `noexec`, `nosuid`, `nodev`, `stat-virt=strict\|relaxed\|off`, `host-perms=private\|mirror`, `quota=<size>`, paired `uid=<N>,gid=<N>`
`--mount-file`	Host file	`ro`, `rw`, `noexec`, `nosuid`, `nodev`, `stat-virt=strict\|relaxed\|off`, `host-perms=private\|mirror`, `quota=<size>`, paired `uid=<N>,gid=<N>`
`--mount-named`	Named volume	`ro`, `rw`, `noexec`, `nosuid`, `nodev`, `kind=dir\|disk`, `size=<size>` for `kind=disk`, `quota=<size>` for directory volumes; directory-backed named volumes also support `stat-virt=strict\|relaxed\|off`, `host-perms=private\|mirror`, paired `uid=<N>,gid=<N>`
`--mount-disk`	Host disk image	`ro`, `rw`, `noexec`, `nosuid`, `nodev`, `format=raw\|qcow2\|vmdk`, `fstype=<type>`
`--mount-owned`	Guest path	`ro`, `rw`, `noexec`, `nosuid`, `nodev`, `kind=dir\|disk`; disks require `size=<size>`; directories accept `quota=<size>`, `stat-virt=strict\|relaxed\|off`, `host-perms=private\|mirror`, paired `uid=<N>,gid=<N>`
`--tmpfs`	Guest path	`ro`, `rw`, `noexec`, `nosuid`, `nodev`; size may be passed as `PATH:SIZE[:OPTIONS]`

Combining mounts

A sandbox can combine host directories, individual files, named volumes, disk images, and tmpfs scratch space. In the CLI, repeat the mount flags. Ruby currently supports named-volume management, but does not expose sandbox mount configuration.

await using sb = await Sandbox.builder("full")
  .image("python")
  .volume("/app/src", (v) => v.bind("./src").readonly().noexec())
  .volume("/app/pyproject.toml", (v) => v.bind("./pyproject.toml").readonly())
  .volume("/root/.cache/pip", (v) =>
    v.named("pip-cache").statVirtualization("relaxed"),
  )
  .volume("/dataset", (v) =>
    v.disk("./dataset.qcow2").format("qcow2").fstype("ext4").readonly(),
  )
  .volume("/tmp", (v) => v.tmpfs().size(1024).noexec().nosuid().nodev())
  .create();

let sb = Sandbox::builder("full")
    .image("python")
    .volume("/app/src", |v| v.bind("./src").readonly().noexec())
    .volume("/app/pyproject.toml", |v| v.bind("./pyproject.toml").readonly())
    .volume("/root/.cache/pip", |v| {
        v.named("pip-cache")
            .stat_virtualization(StatVirtualization::Relaxed)
    })
    .volume("/dataset", |v| {
        v.disk("./dataset.qcow2")
            .format(DiskImageFormat::Qcow2)
            .fstype("ext4")
            .readonly()
    })
    .volume("/tmp", |v| v.tmpfs().size(1024).noexec().nosuid().nodev())
    .create()
    .await?;

from microsandbox import DiskImageFormat, Sandbox, StatVirtualization, Volume

sb = await Sandbox.create(
    "full",
    image="python",
    volumes={
        "/app/src": Volume.bind("./src", readonly=True, noexec=True),
        "/app/pyproject.toml": Volume.bind("./pyproject.toml", readonly=True),
        "/root/.cache/pip": Volume.named(
            "pip-cache", stat_virtualization=StatVirtualization.RELAXED,
        ),
        "/dataset": Volume.disk(
            "./dataset.qcow2", format=DiskImageFormat.QCOW2,
            fstype="ext4", readonly=True,
        ),
        "/tmp": Volume.tmpfs(size_mib=1024, noexec=True, nosuid=True, nodev=True),
    },
)

sb, err := m.CreateSandbox(ctx, "full",
    m.WithImage("python"),
    m.WithMounts(map[string]m.MountConfig{
        "/app/src": m.Mount.Bind("./src", m.MountOptions{
            Readonly: true, Noexec: true,
        }),
        "/app/pyproject.toml": m.Mount.Bind("./pyproject.toml", m.MountOptions{
            Readonly: true,
        }),
        "/root/.cache/pip": m.Mount.Named("pip-cache", m.MountOptions{
            StatVirtualization: m.StatVirtualizationRelaxed,
        }),
        "/dataset": m.Mount.Disk("./dataset.qcow2", m.DiskOptions{
            Format: "qcow2", Fstype: "ext4", Readonly: true,
        }),
        "/tmp": m.Mount.Tmpfs(m.TmpfsOptions{
            SizeMiB: 1024, Noexec: true, Nosuid: true, Nodev: true,
        }),
    }),
)
if err != nil {
    return err
}

msb create python --name full \
  --mount-dir ./src:/app/src:ro,noexec \
  --mount-file ./pyproject.toml:/app/pyproject.toml:ro \
  --mount-named pip-cache:/root/.cache/pip:stat-virt=relaxed \
  --mount-disk ./dataset.qcow2:/dataset:ro,format=qcow2,fstype=ext4 \
  --tmpfs /tmp:1G:noexec,nosuid,nodev

Reference

For exact volume APIs, see TypeScript, Rust, Python, or Go. For local volume management, see Volume commands.

Getting Started

Sandboxes

Networking

Deep dive

Troubleshooting

Temporary files

Cloud default volume

Bind mounts

Owned volumes

Named volumes

Create a volume

Mount in a sandbox

Manage volumes

Disk-image volumes

Tmpfs

Mount options

Fallback guest ownership

CLI syntax and flags

Combining mounts

Reference

​Temporary files

​Cloud default volume

​Bind mounts

​Owned volumes

​Named volumes

​Create a volume

​Mount in a sandbox

​Sharing and host-side access

​Manage volumes

​Disk-image volumes

​Tmpfs

​Mount options

​Fallback guest ownership

​CLI syntax and flags

​Combining mounts

​Reference

Temporary files

Cloud default volume

Bind mounts

Owned volumes

Named volumes

Create a volume

Mount in a sandbox

Sharing and host-side access

Manage volumes

Disk-image volumes

Tmpfs

Mount options

Fallback guest ownership

CLI syntax and flags

Combining mounts

Reference