Disks

A disk is storage that lives on its own. Create it once, attach it to a machine, and later move it to a different machine without losing what is on it. A machine’s own 100 GB disk goes away with the machine. A standalone disk does not. Disks are managed from the console’s Disks page, with boxd disks on the CLI, and from the SDKs.

Create and attach

boxd disks new data --size 10G                       # create (alias: create)
boxd disks list                                      # name, size, status, attached to (alias: ls)
boxd disks attach data myapp --mount-path /mnt/data  # mount it inside the machine
boxd disks attach data myapp --mount-path /mnt/data --read-only
boxd disks detach data myapp
boxd disks remove data -y                            # must be detached first (alias: rm)

A disk is always created writable. Read-only is chosen per attachment. Names are unique within an org, and a disk is creating until its storage is allocated, so attach waits for ready. One attachment at a time. A disk’s storage is opened read-write by the machine that holds it, so a second attachment would be a second writer to the same bytes. Detach before attaching elsewhere.

Attaching at creation

A disk lives on one host, and a machine can only mount a disk on the host it runs on. Attaching to a machine that already exists therefore works only when the two happen to share a host. To pair a disk with a new machine, attach it at creation, and the machine is placed on the disk’s host:

boxd new myapp --disk data                        # mounted at /mnt/data
boxd new myapp --disk data:/srv/data              # a mount path of your choice
boxd new myapp --disk data:/srv/data:ro           # read-only
boxd new myapp --disk data --disk logs:/var/log/app   # several disks

The form is <disk>[:<mount-path>][:ro], with the disk by name or id. The SDKs take the same thing as volumes on create. A machine restored from a snapshot cannot take a disk at creation, since a restore rebuilds exactly what was captured. Create it first, then attach.

The console’s Attach picker lists only the machines on the disk’s host. When the machine you want is not there, create a new one with the disk attached from the start, with boxd new --disk or the SDK’s volumes.

Inside the machine

The disk shows up as a block device mounted at the path you chose, formatted and ready. An attached disk’s size and mount path appear on the machine’s Overview page in the console.

From the SDKs

disk = boxd.disks.create("data", "10G")
boxd.disks.attach(disk.id, machine.id, "/mnt/data")
boxd.disks.detach(disk.id, machine.id)

boxd.machines.create("myapp", volumes=[VolumeMount(disk_id=disk.id, mount_path="/mnt/data")])

const disk = await boxd.disks.create("data", "10G");
await boxd.disks.attach(disk.id, machine.id, "/mnt/data");
await boxd.disks.detach(disk.id, machine.id);

await boxd.machines.create({ name: "myapp", config: { volumes: [{ diskId: disk.id, mountPath: "/mnt/data" }] } });

See the Python SDK and TypeScript SDK references.

Getting started

Guides

Integrations & automations

Use cases

References

Create and attach

Attaching at creation

Inside the machine

From the SDKs

​Create and attach

​Attaching at creation

​Inside the machine

​From the SDKs

Create and attach

Attaching at creation

Inside the machine

From the SDKs