Skip to content

Volumes

Fly.io volume lifecycle operations for session persistence.

FlyVolume dataclass 

FlyVolume(id, name, region, size_gb, app_name, state)

Represents a Fly.io volume.

Attributes:

Name Type Description
id str

The unique Fly volume ID.
name str

Human-readable volume name.
region str

Fly.io region the volume is in.
size_gb int

Volume size in gigabytes.
app_name str

The Fly app this volume belongs to.
state str

Current volume state.

create_volume async 

create_volume(app_name, *, name='flaude_session', region='iad', size_gb=DEFAULT_VOLUME_SIZE_GB, token=None)

Create a Fly.io volume for session persistence.

Parameters:

Name Type Description Default
app_name str

The Fly app to create the volume under.

 required
name str

Volume name (visible in Fly dashboard).

 'flaude_session'
region str

Region for the volume (must match machine region).

 'iad'
size_gb int

Volume size in GB (default 1).

 DEFAULT_VOLUME_SIZE_GB
token str | None

Explicit API token.

 None

Returns:

Name Type Description
A FlyVolume

class:FlyVolume with the volume's ID and metadata.
Source code in flaude/volume.py 
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
async def create_volume(
    app_name: str,
    *,
    name: str = "flaude_session",
    region: str = "iad",
    size_gb: int = DEFAULT_VOLUME_SIZE_GB,
    token: str | None = None,
) -> FlyVolume:
    """Create a Fly.io volume for session persistence.

    Args:
        app_name: The Fly app to create the volume under.
        name: Volume name (visible in Fly dashboard).
        region: Region for the volume (must match machine region).
        size_gb: Volume size in GB (default 1).
        token: Explicit API token.

    Returns:
        A :class:`FlyVolume` with the volume's ID and metadata.
    """
    payload = {
        "name": name,
        "region": region,
        "size_gb": size_gb,
    }

    logger.info(
        "Creating volume in app %r region=%s size=%dGB",
        app_name,
        region,
        size_gb,
    )

    data = await fly_post(
        f"/apps/{app_name}/volumes",
        json=payload,
        token=token,
    )

    if not data or not isinstance(data, dict):
        raise FlyAPIError(
            status_code=0,
            detail="Empty or invalid response from create-volume endpoint",
            method="POST",
            url=f"/apps/{app_name}/volumes",
        )

    volume = _parse_volume_response(data, app_name)
    logger.info(
        "Volume %s created (region=%s, size=%dGB)",
        volume.id,
        volume.region,
        volume.size_gb,
    )
    return volume

list_volumes async 

list_volumes(app_name, *, token=None)

List all volumes for a Fly app.

Parameters:

Name Type Description Default
app_name str

The Fly app to list volumes for.

 required
token str | None

Explicit API token.

 None

Returns:

Type Description
list[FlyVolume]

List of :class:FlyVolume objects.
Source code in flaude/volume.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
async def list_volumes(
    app_name: str,
    *,
    token: str | None = None,
) -> list[FlyVolume]:
    """List all volumes for a Fly app.

    Args:
        app_name: The Fly app to list volumes for.
        token: Explicit API token.

    Returns:
        List of :class:`FlyVolume` objects.
    """
    data = await fly_get(
        f"/apps/{app_name}/volumes",
        token=token,
    )

    if not data or not isinstance(data, list):
        return []

    return [_parse_volume_response(v, app_name) for v in data]

destroy_volume async 

destroy_volume(app_name, volume_id, *, token=None)

Destroy a Fly.io volume permanently.

Parameters:

Name Type Description Default
app_name str

The Fly app the volume belongs to.

 required
volume_id str

The volume ID to destroy.

 required
token str | None

Explicit API token.

 None
Source code in flaude/volume.py 
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
async def destroy_volume(
    app_name: str,
    volume_id: str,
    *,
    token: str | None = None,
) -> None:
    """Destroy a Fly.io volume permanently.

    Args:
        app_name: The Fly app the volume belongs to.
        volume_id: The volume ID to destroy.
        token: Explicit API token.
    """
    try:
        await fly_delete(
            f"/apps/{app_name}/volumes/{volume_id}",
            token=token,
        )
        logger.info("Volume %s destroyed", volume_id)
    except FlyAPIError as exc:
        if exc.status_code == 404:
            logger.debug("Volume %s already gone (404)", volume_id)
        else:
            raise