> See the full index of documentation pages at https://docs.zettabyte.com/llms.txt.

# Quickstart

> One command gives you a GPU shell. Three commands give you a finished training job.

Source: https://docs.zettabyte.com/docs/cli/quickstart

Last updated: 2026-08-21

Everything below assumes three things: a zCLOUD account with GPU quota, the CLI installed, and `zb auth login` done. `zb gpus` lists your quota. The CLI cannot create accounts or purchase resources (see Overview and install). Nothing else is required. There is no image to pick, no CPU or memory to size, and no cluster vocabulary.

## A GPU shell in one command

```bash
zb box --gpu h100:1
```

What you'll see:

```console
image: default → pytorch
✓ launched box box-brisk-otter
box-brisk-otter: RUNNING
root@box-brisk-otter:/workspace# python -c "import torch; print(torch.cuda.get_device_name(0))"
NVIDIA H100 80GB HBM3
```

One command created the box on the default preset, a GPU-ready PyTorch + CUDA image. It waited for `RUNNING` and attached a shell. The CLI sized CPU and memory automatically for the card. It also printed the image it chose, so nothing happened silently.

- Exiting the shell leaves the box running. `zb box` re-attaches. With exactly one box live, you do not even need the name. `zb down box-brisk-otter` deletes the box and frees the GPU.
- Want your own image? Run `zb box dev1 --image ghcr.io/acme/dev:cu124 --gpu h100:1`. Any pullable ref works if its ENTRYPOINT keeps running. Presets handle that for you.

## Your first training job

The same zero-setup start works for a job. No `--image` is needed, because the default preset fills in:

```bash
zb launch -k job --gpu h100:1 \
    --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
```

If the launch fails only because GPU quota is momentarily exhausted, it does not fail. The launch parks server-side as `QUEUED` and starts automatically when quota frees. `zb wait hello` (and `-w`) poll straight through the queue. You do not babysit or resubmit.

## The same job as a spec file

Flags cover one-liners. A spec file is the paved road: reviewable, diffable, repeatable.

```yaml
# 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: h100:1
```

```bash
zb launch hello.yaml -w && zb logs -f hello
```

## Where to go next

- Ship code and get results back. `workdir: .` snapshots your directory into the workload. `outputs: /outputs` plus `zb pull` downloads the results. See Launch and specs.
- Iterate. Template one spec, then sweep it with `--set` and `--name exp-N`. Relaunch changed code in seconds. See Launch and specs.
- Serve and chat with a model. Run `zb model import hf://ORG/NAME`, then `zb launch -k serve --model NAME --gpu h100:1`, then `zb chat`. See Models, images, and storage.
- Let an AI drive it. Agents can operate `zb` end to end. See Scripting and agents.