Models, images, and storage
Volumes, platform storage, model weights, runtime images, and inference keys from the CLI.
Verified with zb v0.1.
Resource commands at a glance
| Command family | Subcommands | Purpose |
|---|
| `zb volume` | create, ls, inspect, put, import, expand, rm, classes | persistent volumes: create them, fill them, look inside |
| `zb s3` | create, ls, rm, quota | object-storage buckets you own |
| `zb uploads` | ls, cancel | large transfers still in flight |
| `zb model` | upload, import, register, ls, get, rm, tag, fav, unfav, note | model weights and the model registry |
| `zb image` | import, build, ls, get, rm, cred, tag, fav, unfav, note | runtime images in your private registry |
| `zb key` | create, ls, update, rm | inference API keys for serve endpoints |
| `zb gpus` | | GPU types, quota, and usage |
| `zb auth` | login, logout, whoami, hf set|status|rm | sign in and out, show who you are, save a Hugging Face token |
| `zb version`, `zb docs` | | the CLI version; links to these docs |
Storage: volumes and buckets
You manage exactly two kinds of storage. The difference is who owns the lifecycle. A volume is a disk you create, name, size, and mount on purpose. Run `zb volume create data --size 100 --class CLASS` (`zb volume classes` lists the classes), then `--volume data:/data` on any workload. An S3 bucket is object storage you own, provisioned against your tenant's S3 quota. The verbs are `zb s3 create NAME` (cap it with `--quota GB`), `ls`, `rm`, and `quota`. `zb s3` is bucket lifecycle only. Fill and read the bucket with your own S3 client, or point `zb model register --from-s3` at it.
Everything else stages through platform-managed space you never name, size, or clean. That covers shipped code, `outputs:` results, and model uploads. `zb pull` downloads results, and it works after `zb down` because results outlive the workload. The platform reclaims what nothing references.
Volumes
`zb volume create NAME --size GB --class CLASS` creates a persistent volume. `--class` is required: without it the command stops with `storage_class is required`. `zb volume classes` lists the classes. `zb volume expand NAME --size GB` grows it. `zb volume rm` deletes it along with its data. It asks for confirmation in a terminal and needs `-y` in scripts and other non-interactive use. A volume that a workload still mounts cannot be removed: run `zb down` on the workload first, and retry after a short wait if the first attempt is still rejected. Mount volumes with `volumes:` entries in a spec, or with `--volume NAME:/path` at launch.
`zb volume put NAME SRC [PATH]` copies a local directory onto a volume. It is the lane for datasets: too big for `zb push` or `zb cp` (which refuses uploads over 64 MiB). It also needs no running workload. Size is not a limit. Files over 1 GiB upload as resumable transfers, and an interruption never loses the bytes that already landed. `--upload-id` (printed at the start) resumes the transfer. It checks that the volume has room before it uploads anything. If the volume is too small, free space, run `zb volume expand`, or pass `--skip-capacity-check`. `PATH` defaults to the source directory's name.
`zb volume import NAME URL [PATH]` fills the same volume on the platform's bandwidth instead of yours. For anything already on the internet, nothing downloads to your machine first. It takes `hf://ORG/NAME` or any http(s) URL. Recognized archives (`.tar.gz`, `.tgz`, `.tar.bz2`, `.tar.xz`, `.tar`, `.zip`) unpack in place unless you pass `--no-extract`. Gated repos use the token saved by `zb auth hf set` automatically (or pass `--hf-token`). `hf://` downloads pull up to 8 files in parallel (`--workers 1-16` to tune). Interrupting is safe. The download continues, and a re-run reattaches.
`zb volume inspect NAME [PATH]` shows a volume's contents and usage: capacity, per-entry usage, and a listing. You do not wire the volume into a workload. A temporary helper looks inside, then cleans itself up automatically. `--keep` keeps the helper so you can open a `zb shell` in it and browse. `-o json` is stable for scripts.
`zb uploads ls` shows large transfers still in flight. `zb uploads cancel ID` abandons one. An interrupted transfer keeps its landed bytes, so a re-run resumes. Nothing is discarded until you cancel (`--prefix PREFIX --purge` also deletes the landed bytes).
Upload or import models
`zb model upload DIR --name NAME` is the bulk lane for weights. Uploads go directly to platform storage, and any size works, 50 GB shards included. Files over 1 GiB upload as resumable transfers, so an interruption never loses the bytes that already landed. `zb model upload DIR --name NAME --upload-id PREFIX` resumes and skips finished files (the prefix prints at the start). `--upload-id` without a directory registers an already-uploaded run. The model lands on the tenant share volume, the same home `zb model import` uses. `-d` (`--detach`) returns early, and registration finishes automatically. Abandon an upload and free its space with `zb uploads cancel --prefix PREFIX --purge`.
`zb model import hf://ORG/NAME` downloads the model on the platform's bandwidth instead of yours. It spends no GPU: a temporary CPU-only helper does the work. The model lands on the tenant share volume and registers automatically. Serving uses that copy directly, so there is one download and no extra copies. Downloads pull up to 8 files in parallel (`--workers 1-16` to tune). Progress streams to stderr. The register result lands on stdout.
Imports are fully async-capable. `-d` (`--detach`) returns as soon as the download is underway. `zb model import WORKLOAD` finishes it from any machine. Re-running the same import while one is underway attaches to it instead of downloading twice. Interruptions never lose work. The download keeps running, resumes in place on a retry, and every error says how to resume. When the download completes, the model registers and cleans up automatically. It simply appears in `zb model ls`.
`zb model register --name NAME --from-s3 URL` serves weights that already live in your own bucket (`https://endpoint/bucket/prefix`). The platform reads the bucket directly when serving. No bytes are copied, and the storage stays yours. Read access suffices (`--s3-access-key`). The secret key comes from `--s3-secret-key`, `$ZB_S3_SECRET_KEY`, or a prompt that never echoes. The CLI never writes it to disk.
`zb model register --name NAME --share-dir DIR` is the other half of the same command. It registers weights that already sit on the share volume, however they got there. Sources include an import you finished by hand, a copy from another volume, or your own downloader. Nothing moves. The command registers the directory where it is, and serving reads it from there. `DIR` names a top-level folder of the share volume as a single lowercase segment (`my-model`, not `models/my-model`). Delete any `.cache` folder a downloader left inside first, or it becomes part of the model. A folder created seconds ago takes up to a minute to become visible to the platform. The command waits that out rather than failing, so a fresh copy needs no manual retry.
`zb model register --name NAME --volume VOL[:PATH]` registers weights that live on one of your volumes. Examples: a training run's checkpoint directory, or a dataset volume's model folder. Serving reads models from the share volume only, so this lane copies once, in-cluster. A temporary helper copies `PATH` (or the volume root) onto the share volume's top level, registers the copy, and cleans itself up. The source is never modified. It checks the share has room before copying (`--skip-capacity-check` overrides). Interrupting is safe: the copy keeps running, and the model registers itself when it lands. Re-run the same command to re-attach.
zb model register --name my-model --volume data:checkpoints/final
The model's directory is a top-level folder on the share volume (also visible in the console's model address picker). `zb model rm` deletes just the registration and keeps the weights. `zb model rm NAME --purge` deletes both in one step.
Gated Hugging Face repos
Save a token once with `zb auth hf set`. `zb model import` and `zb volume import` use it automatically, with a notice. Or pass `--hf-token` (the bare form reads `$HF_TOKEN`). `--no-hf-token` forces an anonymous download. On the default lane the token is delivered over the exec channel and is not stored in the workload spec. Prefer a fine-grained read-only token regardless.
Runtime images
`zb image import REF` mirrors an external image into your tenant's private registry. It prints the runtime image id that serve needs. `--cred NAME` uses a saved registry credential for private sources (`zb image cred add`, `ls`, and `rm` manage them). `--wait` blocks until the mirror completes. `zb image build --name N --tag T -f Dockerfile` builds a runtime image from a Dockerfile on the platform, with no local Docker needed. It can also snapshot a running pod.
`zb image ls` lists import and build jobs alongside the platform presets. `--private` hides the presets and shows only your own. `zb image get` shows one job's status, and answers to the runtime image id as well as the job id. `zb image rm` removes job records without deleting registry bytes. For how images are picked at launch (presets, bare names, `@TAG` and `@fav` handles), see Images and presets on the Launch and specs page.
Tags, favorites, and notes
Tags, favorites, and notes organize models and images. Examples: `zb image tag add ID golden cuda12` (organizational labels, not the docker version tag), `zb model fav llama`, and `zb image note ID base image for RL runs`. Filter and sort lists with `ls --tag golden --fav --sort created`. Models also sort by `name` and `status`, and images by `status` and `source`. Repeating `--tag` means AND. Favorites show in a fav column. All of these verbs are idempotent and prompt-free.
List tables are compact by default. Long identifiers (model ids, image job ids, key ids, credential ids) stay hidden until you ask with `--wide` (or `-o wide`). Names resolve everywhere (`zb key rm NAME`, `zb model get NAME`).
Privacy
Tenant-scoped by default
Images imported or built via `zb image` land in your tenant's private registry. They are not visible to other tenants.
Next steps
[Scripting and agents](https://docs.zettabyte.com/docs/zcloud/cli/automation): the machine contract, and how to hand the CLI to an AI agent.