How to SSH into Pods on Podstack

A complete walkthrough of SSH access to a Podstack GPU pod — launch the pod, set up your SSH client, then connect from your terminal. The full process takes about 5 minutes.

What You’ll Learn

This tutorial covers the three parts of setting up SSH access to a Podstack pod:

1. Launching a Pod — configure GPU, template, storage, and SSH key
2. Configuring the SSH Client — set up your local machine to recognize Podstack’s SSH proxy
3. Accessing the Pod — copy the SSH command and connect from your terminal

Prerequisites

• An active Podstack account with sufficient wallet balance
• A terminal application (Terminal on macOS/Linux, PowerShell or Git Bash on Windows)
• An SSH key pair (you can also generate one inside Podstack — covered below)

Part 1 — Launching a Pod

Step 1: Select Pod Configuration

1. Open the Podstack GPU Cloud Platform dashboard. This is your home base showing current usage at a glance.
2. From the left-side navigation, click Pods.
3. Click the Launch Pod button to begin spinning up a new instance.
4. Pick a GPU that matches your workload. For this walkthrough, select the L40S by clicking its Select button.
5. Choose a template that comes pre-loaded with the tools you need — for example, the PyTorch + OpenCV template.
6. Scroll down through the Configure Your Pod page to set up the remaining details (project, GPU fraction, etc.).
7. Attach storage (optional): under volumes, select an NFS volume such as my-vol.

Step 2: Add Your SSH Key

1. Under SSH Access, pick an existing key from the list (for example, demo).
2. Don’t have a key yet? Click Add New Key to open the key modal. From there you can:
   • Paste a public key from your local machine, or
   • Generate a brand new key pair directly on the platform.
3. Close the modal once your key is selected.

See SSH Keys for full details on managing keys across your account.

Step 3: Enable SSH and Launch

1. Scroll down to the Environment Variables section.
2. Verify that ENABLE_SSH is set to true — this is what allows remote connections to the container.
3. Click Launch Pod to start the instance.
4. Your new pod appears with Pending status while it boots. Click the pod entry to open the detail page and watch its progress.

Part 2 — Configuring the SSH Client

The first time you connect to any Podstack pod, your local machine needs a small one-time configuration so it can route traffic through Podstack’s SSH proxy.

Step 1: Open the First-Time Setup Instructions

1. On the pod detail page, find the SSH Access section.
2. Click the First-time setup required link.
3. The SSH Configuration modal opens with platform-specific guides. By default, macOS instructions are shown — switch tabs for Linux or Windows as needed.
4. The instructions walk through:
   • Creating the ~/.ssh directory (if it doesn’t exist).
   • Adding the Podstack host entry to your SSH config file.
   • Setting up the proxy command for routing connections.
5. Once reviewed, click Done to close the dialog.

Step 2: Verify Your Local SSH Config

Open your terminal and run:

cat ~/.ssh/config

You should see the new Podstack host entry, which confirms the proxy command and host settings are saved.

Tip: If the entry isn’t there, re-open the modal in the dashboard and copy the block into ~/.ssh/config manually. Create the file if it doesn’t exist.

Part 3 — Accessing the Pod

Step 1: Copy the SSH Connection Command

1. Wait until your pod status switches from Pending to Running — this means it’s live and ready.
2. On the pod detail page, scroll to SSH Access.
3. Click the copy icon next to the SSH command to copy it to your clipboard.

Step 2: Connect from Your Terminal

1. Paste the SSH command into your terminal.

2. Update the key path to point to where your private key file actually lives on disk. For example, if you downloaded it to ~/Downloads/, the command might look like:

   ssh -i ~/Downloads/demo podstack@ssh-<subdomain>.cloud.podstack.ai
   

   • podstack is the default username for all Podstack templates.
   • ssh-<subdomain>.cloud.podstack.ai is unique per pod.

3. Hit Enter.

You should see the Podstack welcome banner confirming you’re connected to your remote environment. You can now run commands inside the pod as if it were a local machine.

Quick Reference

Common Issues

Permission denied (publickey)

• The selected SSH key on the pod doesn’t match the private key you’re using locally.
• Check key file permissions: chmod 600 <key_path>.

Connection refused

• The pod isn’t fully running yet — wait for status Running.
• Verify ENABLE_SSH=true was set in environment variables when launching the pod.

Host key verification failed

• Happens when a pod is recreated and reuses the same subdomain. Clear the cached host key:

  ssh-keygen -R ssh-<subdomain>.cloud.podstack.ai
  

For more troubleshooting, see Connecting to Pods.

Next Steps

• Explore Connecting to Pods for Jupyter, web terminal, exposed ports, and file transfer options.
• Set up additional SSH Keys for teammates.
• Save your pod configuration as a Template for one-click relaunch.