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).