Quickstart
Start a GPU shell with one command, then run a first job, from the terminal.
Verified with zb v0.1.
Everything below assumes three things: a zCLOUD account with GPU quota, the CLI installed (see [Overview and install](https://docs.zettabyte.com/docs/zcloud/cli/overview)), and `zb auth login` done. `zb gpus` lists the GPU types available to the account and, where the platform reports it, quota and current usage. The CLI cannot create accounts or purchase resources. On GPU workloads it sizes CPU and memory per card, and the first box and job below use a default image, so neither needs an image or a size. `TYPE:COUNT` stands for a GPU type listed by `zb gpus` and a card count.
A GPU shell in one command
zb box --gpu TYPE:COUNT
With no box running, this command creates one on the default preset, a GPU-ready PyTorch image, waits for `RUNNING` and attaches a shell. Inside the shell, `python -c "import torch; print(torch.cuda.get_device_name(0))"` prints the name of the GPU the box holds.
- Exiting the shell leaves the box running. `zb box` re-attaches, and with exactly one box live the name is optional. `zb down NAME` deletes the box and frees the GPU; the freed card can take a few seconds to show in quota.
- A named box needs an image on first create. Run `zb box dev1 --image pytorch --gpu TYPE:COUNT`; `--image` takes a preset name such as `pytorch` or an image reference. See [Everyday commands](https://docs.zettabyte.com/docs/zcloud/cli/everyday-commands) for the rules a custom image must meet.
Your first training job
A job starts the same way. With no `--image`, the default preset is used:
zb launch -k job --gpu TYPE:COUNT \
--run 'python -c "import torch; print(torch.cuda.get_device_name(0))"' \
--name hello -w # -w blocks until RUNNING
zb logs -f hello # follows until the job completes
zb down hello # clean up
When GPU quota is exhausted, a launch waits in a server-side queue as `QUEUED` instead of failing; `--no-queue` makes it fail at once. A queued launch gives up after about 24 hours. `zb wait hello` and `-w` keep polling while the launch is queued.
The same job as a spec file
Flags cover one-liners. A spec file holds the same launch in a file that can be reviewed, diffed and repeated.
# hello.yaml: image omitted, so the default preset fills in
kind: job
name: hello
run: python -c "import torch; print(torch.cuda.get_device_name(0))"
resources:
gpu: TYPE:COUNT
zb launch hello.yaml -w && zb logs -f hello
Next steps
- [Launch and specs](https://docs.zettabyte.com/docs/zcloud/cli/launch-and-specs): everything a spec can say about code, results, environment, and scheduling.
- [Everyday commands](https://docs.zettabyte.com/docs/zcloud/cli/everyday-commands): status, logs, and shell for a running workload.
- [Scripting and agents](https://docs.zettabyte.com/docs/zcloud/cli/automation): run `zb` from scripts or hand it to an AI agent.
- [Models, images, and storage](https://docs.zettabyte.com/docs/zcloud/cli/models-images-and-storage): volumes, model weights, and runtime images from the CLI.