crunr 0.1.0

Run any compute job on AWS with a single command

crunr

Run any compute job on AWS EC2 with a single command — no DevOps required.

crunr run train.py --gpu

crunr provisions an instance, uploads your code, streams live output, downloads results, and terminates the instance automatically. Zero idle cost.

Install

pip install crunr

Requires Python 3.10+ and an AWS account.

Quick start

# 1. Configure AWS credentials (one-time)
crunr auth

# 2. Run a script on the cheapest CPU instance
crunr run script.py

# 3. Run on a GPU instance
crunr run train.py --gpu

# 4. Specify minimum VRAM
crunr run train.py --gpu --memory 24

# 5. Pass environment variables
crunr run train.py --env EPOCHS=50 --env LR=0.001

How it works

1. Provision — selects the cheapest matching spot instance, falls back to on-demand
2. Sync — uploads your local directory to the instance (rsync or scp+tar)
3. Execute — runs your command with live log streaming
4. Collect — downloads any outputs/ directory back to your machine
5. Terminate — instance is always destroyed, even on Ctrl+C or crash

Commands

Command	Description
crunr auth	Configure AWS credentials
crunr run <script>	Run a job on EC2
crunr jobs	Show job history
crunr ps	List running instances
crunr clean	Terminate all orphaned instances

crunr run options

--gpu               Request a GPU instance (cheapest available)
--memory GB         Minimum GPU VRAM or RAM in GB
--instance TYPE     Exact EC2 instance type (e.g. g5.xlarge)
--disk GB           Root EBS volume size (default: 8 GB CPU, 100 GB GPU)
--env KEY=VALUE     Environment variable passed to the job (repeatable)
--dir PATH          Local directory to sync (default: current directory)
--on-demand         Use on-demand pricing instead of spot
--profile NAME      AWS credential profile
--region REGION     Override AWS region

Saving outputs

Your script can write files to an outputs/ directory. crunr automatically downloads it after the job finishes:

import os
os.makedirs("outputs", exist_ok=True)
with open("outputs/result.txt", "w") as f:
    f.write("done")

AWS IAM permissions

The IAM user needs these permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:RunInstances", "ec2:TerminateInstances", "ec2:DescribeInstances",
        "ec2:DescribeImages", "ec2:DescribeSpotPriceHistory",
        "ec2:CreateKeyPair", "ec2:DeleteKeyPair", "ec2:DescribeKeyPairs",
        "ec2:CreateSecurityGroup", "ec2:DescribeSecurityGroups",
        "ec2:AuthorizeSecurityGroupIngress",
        "ec2:CreateTags",
        "sts:GetCallerIdentity"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "iam:CreateServiceLinkedRole",
      "Resource": "arn:aws:iam::*:role/aws-service-role/spot.amazonaws.com/*"
    }
  ]
}

Cost

You only pay for the time the instance runs. Spot instances are typically 60–90% cheaper than on-demand.

Example costs (spot, us-east-1):

• t3.micro CPU job — ~$0.003/hr
• g4dn.xlarge GPU (T4) — ~$0.16/hr
• g5.xlarge GPU (A10G) — ~$0.34/hr

Data transfer into EC2 is free. Transfer out costs ~$0.09/GB.

License

MIT