# Volume

A persistent disk in an environment — created implicitly when a service enables `volume`, then managed by id (grow, snapshot, detach, re-attach; delete when detached).

**Attributes** (`VolumeDto`)

- `id` · `string` · read-only
- `environmentId` · `string` · read-only — The environment this volume belongs to.
- `serviceId` · `string | null` · read-only — The service mounting this volume; null when detached (an orphan).
- `name` · `string` · read-only — Volume name, unique within the environment.
- `mountPath` · `string` · read-only — Path the volume is mounted at when attached.
- `sizeGb` · `integer` · read-only — Current volume size in GB.
- `status` · `object` · read-only — Read-only: live disk state (provisioning/ready, actual size, usage).
  - `state` · `"ready" | "provisioning" | "repairing" | "unknown"` · read-only — Live state of the attached disk: `ready` (bound + in use), `provisioning` (being created/attached), `repairing`, or `unknown`.
  - `location` · `string` · read-only — The location the volume is actually provisioned in (when provisioned).
  - `currentSizeGb` · `number` · read-only — Actual provisioned capacity in GiB, as the storage layer reports it live.
  - `usedBytes` · `number` · read-only — Bytes currently used on the disk.
  - `commands` · `object[]` · read-only — Recent day-2 commands (newest first), persisted by Koo — live AND terminal state, so the console shows an in-progress or just-completed/failed operation even after a page reload.
    - `id` · `string` · read-only — Command record id.
    - `kind` · `"expand" | "snapshot" | "restore"` · read-only — Which day-2 command this is.
    - `status` · `"running" | "succeeded" | "failed"` · read-only — Lifecycle: running, then succeeded or failed.
    - `startedAt` · `string <date-time>` · read-only — When the command was fired.
    - `completedAt` · `string <date-time>` · read-only — When it finished (succeeded/failed).
    - `error` · `string` · read-only — Failure message when the command failed.
    - `detail` · `string` · read-only — Human detail — the snapshot name, or the target size for an expand.
- `createdAt` · `string <date-time>` · read-only
- `updatedAt` · `string <date-time>` · read-only

**Example `VolumeDto`**

```json
{
  "id": "vol_01example0000000000000000x",
  "environmentId": "env_01example0000000000000000x",
  "serviceId": "svc_01example0000000000000000x",
  "name": "my-app",
  "mountPath": "example",
  "sizeGb": 0,
  "status": {
    "state": "ready",
    "location": "example",
    "currentSizeGb": 1,
    "usedBytes": 1,
    "commands": [
      {
        "id": "vol_01example0000000000000000x",
        "kind": "expand",
        "status": "running",
        "startedAt": "2026-01-01T00:00:00.000Z",
        "completedAt": "2026-01-01T00:00:00.000Z",
        "error": "example",
        "detail": "example"
      }
    ]
  },
  "createdAt": "2026-01-01T00:00:00.000Z",
  "updatedAt": "2026-01-01T00:00:00.000Z"
}
```