Reference

Configuration reference

Every field of clockingcloud.yaml, with types, defaults, validation rules and a complete example.

The file

An instance is defined in a YAML file named clockingcloud.yaml. Pass another path with -f. Unknown keys are rejected with exit code 2 so typos never silently change behavior. Run clockingcloud plan to validate.

Complete example

clockingcloud.yaml

name: product-shots
model: z-image-turbo
gpu: auto
gpus: 1

scale:
  min: 0
  max: 8
idle_timeout: 60s

setup:
  - pip install -r requirements.txt
  - python warm_cache.py

env:
  LOG_LEVEL: info
  WEBHOOK_TOKEN: ${secrets.WEBHOOK_TOKEN}

volumes:
  - name: assets
    mount: /data
    mode: ro
  - name: renders
    mount: /out

Top-level fields

Field	Type	Default	Description
name	string	required	2 to 39 lowercase letters, numbers or dashes. Unique within your account. Cannot be changed after creation.
model	string	required	A model ID from the model catalog, `hf://org/model`, or a path to a local model directory.
gpu	enum	auto	One of `auto`, `l40s`, `h100`, `h200`, `b200`. `auto` picks the smallest GPU that fits the model.
gpus	integer	1	GPUs per replica: 1, 2, 4 or 8. Multi-GPU is used for sequence-parallel video models.
scale	object	min 0, max 1	Replica bounds. See below.
idle_timeout	duration	60s	Release a replica after this long without work. Minimum 10s, maximum 24h.
setup	list of strings	none	Shell commands run in order when a replica starts, before it accepts requests. A non-zero exit fails the start and releases the GPU.
env	map	none	Environment variables. Values may reference secrets as `${secrets.NAME}`.
volumes	list	none	Volumes to mount. See below.

scale

Field	Type	Default	Description
scale.min	integer	0	Minimum replicas. 0 means no GPU runs while idle. 1 or more keeps that many replicas warm and billed.
scale.max	integer	1	Maximum replicas. Must be greater than or equal to min. Bounds your worst-case spend rate.

volumes

Field	Type	Default	Description
volumes[].name	string	required	Name of an existing volume (see `clockingcloud volume ls`).
volumes[].mount	path	required	Absolute path inside the replica. Must not be `/`, `/proc`, `/sys` or `/dev`.
volumes[].mode	enum	rw	`ro` for read-only, `rw` for read-write.
volumes[].path	string	volume root	Sub-path inside the volume to mount.

Accepted aliases

These older spellings are accepted and rewritten on read, so examples from earlier material keep working. New files should use the canonical form.

You may write	Canonical
storage:	volumes:
- volume: global://renders	- name: renders
source: s3://bucket	connect with `clockingcloud volume connect s3://bucket --name assets`, then `name: assets`

Value formats

Type	Format	Examples
duration	Integer followed by s, m, h or d	30s, 5m, 1h, 30d
uri	vol://, s3://, azure://, gs://, hf://	vol://outputs/brand-lora
secret reference	${secrets.NAME}	${secrets.WEBHOOK_TOKEN}

Something unclear or missing? Email hello@clockingcloud.com.