Volumes

bladekit.Volume.from_name

A bladekit.Volume is a reference to a named network volume. The object returned by from_name() plays two roles: passed to @app.function/@app.cls via volumes={"/path": vol} it is a client-side reference used to build the mount spec for a run or deployment; called as vol.commit() from inside a running container it is an in-container handle that publishes local writes. from_name() itself performs no network call — it only validates the name and stores the flags for later.

class bladekit.Volume:
    @classmethod
    def from_name(
        cls,
        name: str,
        *,
        create_if_missing: bool = False,
        auto_commit_on_ready: bool = False,
        read_only: bool = False,
    ) -> "Volume": ...

name str

Volume name. Must match ^[a-z0-9][a-z0-9._-]{0,63}$ — lowercase alphanumerics, ., _, -, starting with an alphanumeric, up to 64 characters.

create_if_missing boolDefault: False

If True, the volume is created (empty, generation 0) if it does not exist yet — or fetched if it already does, since the underlying create call is idempotent by name. The create-or-get happens the first time a run or deployment referencing this volume is submitted, not at from_name() call time.

auto_commit_on_ready boolDefault: False

Commit the mount automatically once the replica reports serving-ready, without any vol.commit() call in user code. Only valid on deployed web_server/asgi_app endpoints — see below.

read_only boolDefault: False

Mount read-only. commit() on a read-only mount raises bladekit.VolumeCommitError (VOLUME_READ_ONLY) immediately.

Mounting a volume

Pass a {mount_path: bladekit.Volume} dict as volumes= on @app.function or @app.cls. Multiple volumes can be mounted at different paths on the same function. Every value must be a bladekit.Volume instance — anything else raises bladekit.InvalidArgumentError.

import bladekit

app = bladekit.app("training")

dataset = bladekit.Volume.from_name("datasets", create_if_missing=True)
checkpoints = bladekit.Volume.from_name("checkpoints", create_if_missing=True)

@app.function(
    gpu="RTX-A4500",
    image=bladekit.Image.from_catalog("fabric/torch"),
    volumes={"/data": dataset, "/ckpt": checkpoints},
)
def train():
    ...

auto_commit_on_ready

auto_commit_on_ready=True commits the mount automatically the first time the replica reports serving-ready — no vol.commit() needed in user code. It is meant for server warm-up caches (for example a vLLM VLLM_CACHE_ROOT): whatever the server wrote under the mount during startup is published for the next cold start, on any node. The commit is best-effort and non-blocking — it runs after traffic starts flowing, and a failure never affects the replica.

cache = bladekit.Volume.from_name("vllm-cache", create_if_missing=True, auto_commit_on_ready=True)

@app.cls(gpu="RTX-A4500", image=bladekit.Image.from_catalog("fabric/vllm"), volumes={"/cache": cache})
class Model:
    @bladekit.web_server(port=8000)
    def serve(self):
        ...

vol.commit()

Publishes this container's local writes under the mount as a new volume generation. Only valid inside an AI Fabric container — the SDK detects the container context via the FABRIC_VOLUMES environment variable and resolves the mount by matching self.name against it. Talks to the runner-internal API with the run's token; the runner never talks to the control-plane agent directly.

def commit(self, *, poll: bool = True, timeout: Optional[float] = 3600.0) -> int: ...

poll boolDefault: True

If True (default), block until the commit reaches a terminal state, polling with backoff from 1 s up to a 5 s ceiling. If False, return immediately after starting the commit without waiting for it to finish.

timeout Optional[float]Default: 3600.0

Caps the total poll time in seconds. Large commits — e.g. model weights pushed via multipart upload — legitimately run well past 10 minutes, so the default is generous; a genuinely stuck commit is bounded server-side by the commit stall watcher regardless. Pass None for no client-side timeout (not recommended in production), or a smaller value to fail fast.

On success, returns the new generation number (int) once the commit reaches state committed. Raises bladekit.VolumeCommitError if the commit reaches failed, or if the poll deadline elapses first.

@app.function(volumes={"/data": dataset})
def process():
    with open("/data/result.json", "w") as f:
        f.write("...")
    generation = dataset.commit()
    print(f"published generation {generation}")

Errors

Related reference