Metadata-Version: 2.4
Name: crunr
Version: 0.1.0
Summary: Run any compute job on AWS with a single command
License-Expression: MIT
Keywords: aws,ec2,cloud,gpu,machine-learning,spot
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: boto3>=1.34
Requires-Dist: botocore>=1.34
Requires-Dist: rich>=13.7
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: moto[ec2,sts]>=5.0; extra == "dev"
Requires-Dist: ruff>=0.3; extra == "dev"
Requires-Dist: mypy>=1.8; extra == "dev"
Requires-Dist: boto3-stubs[ec2,sts]>=1.34; extra == "dev"

# 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

```bash
pip install crunr
```

Requires Python 3.10+ and an AWS account.

## Quick start

```bash
# 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:

```python
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:

```json
{
  "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
