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

# Disks

> Standalone disks that outlive the machine they are attached to.

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

```bash theme={"theme":"github-dark"}
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:

```bash theme={"theme":"github-dark"}
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.

<Note>
  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`.
</Note>

## 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

```python theme={"theme":"github-dark"}
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")])
```

```typescript theme={"theme":"github-dark"}
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](/reference/python-sdk#disks) and [TypeScript SDK](/reference/typescript-sdk#disks) references.