runpod-exp-setup

This repository helps set up a quick deployment of development environment on RunPod with GPU support using Github Actions.

Why this repository?

I need GPU from time to time to run my ML experiments and I rent it on RunPod. I do not use it really extensively, just a few hours a week, and then I delete the instance because otherwise storage cost could be even more than compute cost. But next time I need it I have to set it up again. This repository helps me to automate this process using RunPod API and GitHub Actions.

Prerequisites

1. Create a RunPod account and get your API key from https://runpod.io/console/user/settings
2. Generate SSH keys for GitHub deployment and RunPod access:

   # Generate GitHub deploy key
   ssh-keygen -t rsa -b 4096 -f gh_deploy_key -N ""
   # Generate SSH key for RunPod access
   ssh-keygen -t rsa -b 4096 -f runpod_ssh_key -N ""

Setting up GitHub Secrets

Add the following secrets to your GitHub repository (Settings → Secrets and variables → Actions):

1. RUNPOD_API_KEY: Your RunPod API key
2. GH_DEPLOY_KEY: Content of gh_deploy_key (private key)
3. SSH_PRIVATE_KEY: Content of runpod_ssh_key (private key)

Also add the public key from gh_deploy_key.pub as a deploy key in your repository settings (Settings → Deploy keys). Go to RunPod console and add the public key from runpod_ssh_key.pub as a SSH key.

Project Configuration

The pod configuration is stored in runpod_configs/default.json. You can create multiple configurations and specify the one to use when running the GitHub action. For available configuration options, refer to the RunPod API documentation.

You can install project dependencies by modifying pyproject.toml or running uv add <package>. And, finally, you need to add code you want to run on RunPod instance. Now, you're ready to deploy your code to RunPod!

Deployment

1. Run the GitHub Action called "Deploy to RunPod"
2. GitHub Actions will automatically:
   • Create a RunPod instance
   • Set up the development environment
   • Clone your repository
   • Install dependencies using uv

Connecting to Your RunPod Instance

After the GitHub Action completes successfully, you'll see an SSH connection string in the workflow output that looks like:

ssh root@<remote_ip> -p <remote_port> -i ~/.ssh/runpod_ssh_key

Your project files will be in /workspace directory.