Skip to content

RunPod Setup Guide for Developers

This guide will help you set up RunPod and connect to your instances via SSH using VSCode.

Prerequisites

  • A terminal/command line (Linux, macOS, or Windows with Git Bash/WSL)
  • VSCode installed on your local machine
  • Basic familiarity with SSH and command line

Step 1: Create a RunPod Account

  1. Visit runpod.io
  2. Sign up using a personal or work email (avoid using burkimbia email)
  3. Verify your email address

Step 2: Generate and Add SSH Keys

SSH keys allow you to connect securely without typing passwords each time.

Generate SSH Keys and Add to Your Account

If you don't have SSH keys yet, follow the SSH Key Generation Guide.

  1. Copy your public key (usually ~/.ssh/id_ed25519.pub or ~/.ssh/id_rsa.pub).
  2. Go to Settings → SSH Keys in your RunPod dashboard.
  3. Add your public key. This will ensure you can connect to any pod you deploy without passwords.

Step 3: Set Up VSCode Remote SSH

  1. Open VSCode

  2. Install the Remote - SSH extension:

  3. Click Extensions icon (or press Ctrl+Shift+X / Cmd+Shift+X)

  4. Search for "Remote - SSH"

  5. Install the extension by Microsoft

  6. Configure SSH (optional but recommended):

  7. Open your SSH config file: ~/.ssh/config

  8. This will make connections easier to manage

Step 4: Deploy a Pod

  1. Log in to your RunPod dashboard.

  2. Click Pods → Deploy.

  3. Choose your pod configuration:

  4. GPU Type: Select based on your needs (RTX 4090, A100, etc.).

  5. Template: Select a template that matches your project (PyTorch, TensorFlow, etc.).

  6. Choose the On-Demand option.

  7. Environment Variables (Optional but Recommended): Click Edit → Environment Variables (at the bottom) and use the Raw Editor. Paste the following, replacing placeholders with your actual secrets stored in RunPod:

HF_TOKEN=<your_huggingface_token>
AWS_ACCESS_KEY_ID={{ RUNPOD_SECRET_AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY={{ RUNPOD_SECRET_AWS_SECRET_ACCESS_KEY }}
AWS_ENDPOINT_URL_S3={{ RUNPOD_SECRET_AWS_ENDPOINT_URL_S3 }}
AWS_ENDPOINT_URL_IAM={{ RUNPOD_SECRET_AWS_ENDPOINT_URL_IAM }}
AWS_REGION={{ RUNPOD_SECRET_AWS_REGION }}
GITHUB_ACCESS_TOKEN={{ RUNPOD_SECRET_GITHUB_ACCESS_TOKEN }}
WANDB_API_KEY={{ RUNPOD_SECRET_WANDB_API_KEY }}
  1. Click Deploy On-Demand and wait 1-2 minutes for the pod to start.

Step 5: Connect to Your Pod via SSH

Get SSH Connection Details

  1. Once your pod is running, click the Connect button.
  2. Copy the SSH command shown (format: ssh root@<hostname> -p <port> -i ~/.ssh/<key-name>).

Connect via Terminal (Quick Test)

Paste the SSH command in your terminal:

ssh root@<hostname> -p <port> -i ~/.ssh/<key-name>

You should connect without a password prompt if your SSH key was configured correctly.

Connect via VSCode

Method 1: Direct Connection

  1. In VSCode, press F1 or Ctrl+Shift+P (Windows/Linux) / Cmd+Shift+P (macOS)
  2. Type "Remote-SSH: Connect to Host"
  3. Paste your full SSH command: ssh root@your-pod-id.ssh.runpod.io -p 12345
  4. Select platform: Linux
  5. VSCode will connect and open a new window

Method 2: Using SSH Config (Recommended)

  1. Press F1 and select "Remote-SSH: Open SSH Configuration File"
  2. Add your pod configuration: 
    Host <hostname or ip>
    HostName <hostname or ip>
    User root
    Port <port>
  3. Save the file
  4. Press F1 → "Remote-SSH: Connect to Host" → Select ""

Step 6: Start Working

  1. Open a folder: File → Open Folder → /workspace (this is the persistent volume).

  2. Clone the repository:

git clone https://${GITHUB_ACCESS_TOKEN}@github.com/burkimbia/repository.git
cd repository
  1. Set up the environment: You can use uv sync but it is recommended to install directly from system:
# Install dependencies
uv pip install -e . --python /usr/bin/python3 --break-system-packages
  1. Configure Environment Variables: Create a .env file in the root directory:
cp .env.example .env
# Edit .env with your HF_TOKEN and WANDB_API_KEY
  1. Verify GPU Availability: Run this command to ensure the GPU is detected:
nvidia-smi
  1. Start coding!

Important Tips

Managing Costs

  • Stop vs. Terminate:
  • Stop: Releases the GPU (you stop paying for compute) but keeps the disk volume (you still pay a small hourly fee for storage). Your data is safe.
  • Terminate: Deletes the pod and the disk volume. All billing stops, but all data is erased unless it's on a Network Volume.
  • Use Spot instances for cheaper rates (can be interrupted).

Data Persistence

  • Container storage is ephemeral - deleted when pod terminates
  • Use Network Volumes for important data you want to keep
  • Push code changes to Git regularly

Troubleshooting

Connection refused or timeout:

  • Verify pod is in "Running" state (not Starting or Stopped)
  • Check you're using the correct port number
  • Ensure your SSH key was selected when deploying

Permission denied:

  • Verify your public key is correctly added in RunPod settings
  • Check your private key permissions: chmod 600 ~/.ssh/id_ed25519

Pod is expensive:

  • Choose a cheaper GPU or CPU pod for development/testing
  • Remember to stop pods when taking breaks

Useful Resources

Remember: Always stop or terminate your pods when you're done to avoid unnecessary charges!