by iterative.ai
Get started
Edit on GitHub

Command Reference: runner

cml runner [options]

Starts a runner (either via any supported cloud compute provider or locally on-premise).

Options

Any generic option in addition to:

  • --labels=<...>: One or more (comma-delimited) labels for this runner [default: cml].
  • --name=<...>: Runner name displayed in the CI [default: cml-{ID}].
  • --idle-timeout=<seconds>: Seconds to wait for jobs before terminating. Set to -1 to disable timeout [default: 300].
  • --no-retry: Don't restart the workflow when terminated due to instance disposal or GitHub Actions timeout.
  • --single: Terminate runner after one workflow run.
  • --reuse: Don't launch a new runner if an existing one has the same name or overlapping labels. If an existing matching (same name or overlapping labels) instance is busy, it'll still be reused.
  • --cloud={aws,azure,gcp,kubernetes}: Cloud compute provider to host the runner.
  • --cloud-type={m,l,xl,m+k80,m+v100,...}: Instance type. Also accepts native types such as t2.micro.
  • --cloud-gpu={nogpu,k80,v100,tesla}: GPU type.
  • --cloud-hdd-size=<...>: Disk storage in GB.
  • --cloud-spot: Request a preemptible spot instance.
  • --cloud-spot-price=<...>: Maximum spot instance USD bidding price, [default: current price].
  • --cloud-region={us-west,us-east,eu-west,eu-north,...}: Region where the instance is deployed. Also accepts native AWS/Azure region or GCP zone [default: us-west].
  • --cloud-permission-set=<...>: AWS instance profile or GCP instance service account.
  • --cloud-metadata=<...>: key=value pair to associate with cloud runner instances. May be specified multiple times.
  • --cloud-startup-script=<...>: Run the provided Base64-encoded Linux shell script during the instance initialization.
  • --cloud-ssh-private=<key>: Private SSH RSA key [default: auto-generate throwaway key]. Only supported on AWS and Azure; intended for debugging purposes.
  • --cloud-aws-security-group=<...>: AWS security group identifier.
  • --cloud-aws-subnet=<...>: AWS subnet identifier.
  • --docker-volumes=<...>: Volume mount to pass to Docker, e.g. /var/run/docker.sock:/var/run/docker.sock for Docker-in-Docker support. May be specified multiple times. Only supported by GitLab.

FAQs and Known Issues

  • GitHub Actions by default timeout after a few hours. You can request up to 72 hours via timeout-minutes: 4320. CML will helpfully restart GitHub Actions workflows approaching 72 hours (you'd need to write your code to save intermediate results to take advantage of this).

Examples

Using --cloud-ssh-private

  1. Generate a new RSA PEM private key for debugging purposes:

    ssh-keygen -t rsa -m pem -b 4096 -f key.pem
  2. Pass the contents of the generated private key file when invoking the cml runner command:

    cml runner --cloud=... --cloud-ssh-private="$(cat key.pem)"
  3. Access the instance from your local system by using the generated key as an identity file:

    ssh -i key.pem ubuntu@IP_ADDRESS

    replacing the IP_ADDRESS placeholder with the instance address returned by cml runner (search the output logs for instanceIp).

Content

🐛 Found an issue? Let us know! Or fix it:

Edit on GitHub

Have a question? Join our chat, we will help you:

Discord Chat