Guides

Deploying instances

Define an instance in clockingcloud.yaml, deploy it, scale it, debug it cheaply, and ship it from CI/CD.

Deploy from a file

Terminal

clockingcloud plan -f clockingcloud.yaml
clockingcloud deploy -f clockingcloud.yaml
clockingcloud status product-shots

clockingcloud deploy is idempotent: it creates the instance if the name is new and updates it in place otherwise. See the configuration reference for every field.

deploy versus up

Command	Behavior
clockingcloud deploy	Saves the definition. Starts a replica on the first request, or immediately if `scale.min` is 1 or more.
clockingcloud up	Saves the definition and starts a replica right now, even with `scale.min: 0`. Add `--debug` for the cheapest GPU and auto-stop on exit.

Debug without paying for GPUs

clockingcloud dev runs your setup steps and a shell in a CPU sandbox built from the same image. No GPU is attached.
clockingcloud plan validates the file and prints the GPU and estimated cost. Nothing is created.
clockingcloud up --debug uses the smallest compatible GPU, streams setup logs, and stops the instance when you exit.
idle_timeout releases the GPU after it goes quiet, and a failed setup releases it immediately.

Terminal

clockingcloud dev                          # fix setup on CPU first
clockingcloud plan                         # check GPU and cost
clockingcloud up -f clockingcloud.yaml --debug        # smallest GPU, stops when you exit

Scaling

Terminal

clockingcloud scale product-shots --max 16     # allow more replicas
clockingcloud scale product-shots --min 1      # keep one warm
clockingcloud scale product-shots --min 0      # back to scale to zero

Scaling changes take effect without a redeploy. Replicas are added when the queue grows and removed after idle_timeout. Each replica is billed separately while it is active.

Start, stop and delete

Terminal

clockingcloud stop product-shots
clockingcloud start product-shots
clockingcloud rm product-shots --yes

clockingcloud rm deletes the definition but never your volumes.

CI/CD

Create an API key, store it as a secret in your CI system, and run the CLI or call the REST API.

GitHub Actions

name: deploy
on:
  push:
    branches: [main]
    paths: [clockingcloud.yaml]

jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      CLOCKINGCLOUD_API_KEY: ${{ secrets.CLOCKINGCLOUD_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - name: Install CLI
        run: |
          VERSION=0.1.0
          BASE=https://releases.clockingcloud.com/cli/v$VERSION
          curl -fsSLO $BASE/clockingcloud_${VERSION}_linux_amd64.tar.gz
          curl -fsSLO $BASE/SHA256SUMS
          grep linux_amd64 SHA256SUMS | sha256sum -c -
          tar -xzf clockingcloud_${VERSION}_linux_amd64.tar.gz
          sudo install -m 0755 clockingcloud /usr/local/bin/clockingcloud
      - run: clockingcloud plan -f clockingcloud.yaml
      - run: clockingcloud deploy -f clockingcloud.yaml

Pin the CLI version so a release cannot change your pipeline unexpectedly.

Secrets and environment variables

clockingcloud.yaml

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

Plain env values are stored with the definition and visible in the API. Anything sensitive must use ${secrets.NAME}, which is resolved at start and never returned by the API or shown in logs.

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