SSH Access

Once a TrainPod instance is running, you connect to it over SSH using your own private key. Podstack only ever stores your public key — the private key stays on your machine and never leaves it.

The podstack CLI is the fastest path: podstack gpu instances ssh <id> reads the connection details from Podstack, picks the right local key, and opens a shell. This page covers registering keys, connecting from every OS, and tunneling ports. Two video walkthroughs at the bottom show the terminal and Windows PowerShell setup step by step.

Prerequisites

• A running instance — see Provision a GPU.
• ssh available on your machine (built in on macOS/Linux; on Windows use PowerShell or Git Bash).
• An SSH key registered with Podstack and injected into the instance.

Step 1 — Register an SSH key

The CLI generates an ed25519 keypair locally, writes it to ~/.ssh/podstack_<name> (private) and ~/.ssh/podstack_<name>.pub (public), and registers only the public key with Podstack.

podstack gpu keys create --name my-key

Registered SSH key "my-key" (id: sshkey_abc123)
Private key (local, keep safe): ~/.ssh/podstack_my-key
Public key  (registered):       ~/.ssh/podstack_my-key.pub

The private key is stored only on this machine and was never uploaded —
podstack holds the public key alone. Launch with: --ssh-key-id sshkey_abc123

Already have a key? Register your existing public key instead of generating a new one:

podstack gpu keys create --name my-key --public-key-file ~/.ssh/id_ed25519.pub

List registered keys — the LOCAL KEY column shows whether this machine holds the matching private key:

podstack gpu keys list

ID            NAME     FINGERPRINT       LOCAL KEY   CREATED
sshkey_abc123 my-key   SHA256:abcd...    yes         2026-07-17T10:00:00Z

Delete a key by id when you no longer need it:

podstack gpu keys delete sshkey_abc123

The key must be injected into the instance at launch — pass its id with --ssh-key-id on podstack gpu instances create, or select it during podstack gpu launch. A key registered after an instance is created is not added retroactively. See Provision a GPU.

Step 2 — Connect with the CLI (recommended)

The simplest way to connect on any OS:

podstack gpu instances ssh gpu-abc123

Run it with no id to arrow-select a running instance interactively:

podstack gpu instances ssh

The CLI fetches the connection details from Podstack, resolves your local private key, installs the Podstack login banner, and opens the shell. When you connect, you’ll see the Podstack welcome banner and land in a root shell on the GPU box.

Choosing which private key to use

The CLI resolves the identity in this order:

1. --identity <path> — an explicit path to a private key file.
2. --key <name> — a Podstack key name, resolved to ~/.ssh/podstack_<name>.
3. A single Podstack-managed key found in ~/.ssh (used automatically when there’s exactly one).

# Use a specific key file
podstack gpu instances ssh gpu-abc123 --identity ~/.ssh/id_ed25519

# Use a named podstack key
podstack gpu instances ssh gpu-abc123 --key my-key

If several Podstack keys exist locally and the right one is ambiguous, the CLI asks you to disambiguate with --key or --identity rather than guessing (which would surface as a confusing “Permission denied”).

Useful flags

Pass native ssh arguments after --. For example, to forward a local port:

podstack gpu instances ssh gpu-abc123 -- -L 6006:localhost:6006

Print the command without connecting:

podstack gpu instances ssh gpu-abc123 --print

Step 3 — Connect with plain ssh (optional)

The connection details are also available directly. podstack gpu instances get <id> prints the ready-made SSH command:

podstack gpu instances get gpu-abc123

SSH:      ssh -p 22 [email protected]

Copy that command and add your private key with -i:

ssh -i ~/.ssh/podstack_my-key -p 22 [email protected]

• The default login user for TrainPod instances is root.
• The host and port come from the instance’s connection details.

Fix key permissions if you see a warning. SSH refuses keys that are too open:

chmod 600 ~/.ssh/podstack_my-key

Step 4 — Expose a port to localhost

To reach a service running on the instance (TensorBoard, a training dashboard, an inference server) from your own browser, open a private SSH tunnel. Nothing is made public — only your machine can reach it.

# instance's :8000 becomes http://localhost:8000
podstack gpu instances expose gpu-abc123 8000

Bind to a different local port, or forward a service the instance reaches internally:

# map instance :8000 to http://localhost:8888
podstack gpu instances expose gpu-abc123 8000 --local 8888

# forward a service on a different host the instance can see
podstack gpu instances expose gpu-abc123 5432 --remote-host db.internal

The tunnel stays open until you press Ctrl-C. Like ssh, expose accepts --identity and --key to choose the private key.

Video walkthroughs

These video guides cover the Podstack SSH experience — registering a key, configuring your local SSH client, and connecting from your terminal. The concepts (a local private key, a terminal on macOS/Linux, PowerShell + OpenSSL on Windows) apply directly to TrainPods; from the CLI, podstack gpu instances ssh <id> handles the connection for you.

macOS, Linux & Git Bash

A complete terminal walkthrough of connecting to a Podstack GPU over SSH — launch, configure your SSH client, and connect. About 5 minutes.

Windows PowerShell

Windows PowerShell needs OpenSSL to route the SSH connection. This guide installs it and writes the config automatically, then connects.

The full-length written versions of both videos live under Pods: SSH tutorial and SSH from PowerShell.

Quick reference

FAQs

Where is my private key stored? In ~/.ssh/podstack_<name> on the machine where you ran podstack gpu keys create. Podstack never sees or stores it — only the matching public key is registered.

I get “Permission denied (publickey)”. Why? The private key you’re offering doesn’t match a public key injected into the instance. Confirm the key was passed at launch with --ssh-key-id, that podstack gpu keys list shows LOCAL KEY: yes, and select the right key with --key/--identity. See Troubleshooting.

Can I connect from a second machine? Yes, but the private key lives on the machine that created it. Copy the private key file over securely, or register a second key and inject it at launch. podstack gpu keys list shows LOCAL KEY: no on machines without the private key.

What user do I log in as? root. The CLI and the podstack gpu instances get SSH command both use it.

Do I need the Windows OpenSSL/proxy setup for TrainPods? No. That proxy setup in the PowerShell video is for container Pods that route through cloud.podstack.ai. TrainPod instances are reached directly, so podstack gpu instances ssh <id> (or plain ssh -i <key> root@<host>) works from PowerShell without the proxy.

How do I add a key to an already-running instance? Keys are injected at launch. Register the key, then re-launch (or manually append the public key to ~/.ssh/authorized_keys on the box while you’re connected with an existing key).

Next steps

• Move data — upload datasets and pull results back.
• Fine-tuning — run managed training jobs.
• Troubleshooting — SSH and connection fixes.