Skip to content

Commit 698d67a

Browse files
muhsinkingmuhsinking
authored
Connecting Pods + VSCode/Cursor tutorial (#281)
1 parent 2484581 commit 698d67a

File tree

8 files changed

+232
-89
lines changed

8 files changed

+232
-89
lines changed

‎.cursor/rules/rp-styleguide.mdc

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,21 @@ description:
33
globs:
44
alwaysApply: true
55
---
6+
67
Always use sentence case for headings and titles.
78
These are proper nouns: Runpod, Pods, Serverless, Hub, Instant Clusters, Secure Cloud, Community Cloud, Tetra.
89
These are generic terms: endpoint, worker, cluster, template, handler, fine-tune, network volume.
9-
Prefer using paragraphs to bullet points unless specifically requested.
10-
When using bullet points, use hyphens instead of asterisks, and end each line with a period.
10+
11+
Prefer using paragraphs to bullet points unless directly asked.
12+
When using bullet points, end each line with a period.
13+
14+
When creating a tutorial, always include these sections:
15+
16+
- What you'll learn
17+
- Requirements (rather than "prerequisites")
18+
19+
And number steps like this:
20+
21+
"## Step 1: Create a widget"
22+
23+
... and so on.

‎docs.json

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -111,7 +111,8 @@
111111
"pods/configuration/export-data",
112112
"pods/configuration/expose-ports",
113113
"pods/configuration/override-public-keys",
114-
"pods/configuration/use-ssh"
114+
"pods/configuration/use-ssh",
115+
"pods/configuration/connect-to-ide"
115116
]
116117
},
117118
{
@@ -231,7 +232,6 @@
231232
"tutorials/pods/run-fooocus",
232233
"tutorials/pods/run-ollama",
233234
"tutorials/pods/build-docker-images",
234-
"tutorials/pods/connect-to-vscode",
235235
"tutorials/pods/fine-tune-llm-axolotl"
236236
]
237237
},
@@ -516,6 +516,10 @@
516516
},
517517

518518
"redirects": [
519+
{
520+
"source": "/tutorials/pods/connect-to-vscode",
521+
"destination": "/pods/configuration/connect-to-ide"
522+
},
519523
{
520524
"source": "/pods/savings-plans",
521525
"destination": "/pods/pricing"

‎get-started/connect-to-runpod.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -31,9 +31,9 @@ Runpod provides SDKs in Python, JavaScript, Go, and GraphQL to help you integrat
3131

3232
[Explore the SDKs →](/sdks/python/overview)
3333

34-
## VSCode
34+
## VSCode or Cursor
3535

36-
Follow this tutorial to learn how to connect your VSCode environment to a Pod for remote development:
36+
Follow this tutorial to learn how to connect your VSCode or Cursor environment to a Pod for remote development:
3737

38-
[Connect a Pod to VSCode →](/tutorials/pods/connect-to-vscode)
38+
[Connect a Pod to VSCode or Cursor →](/pods/configuration/connect-to-ide)
3939

‎pods/configuration/connect-to-ide.mdx

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
title: "Connect to a Pod with VSCode or Cursor"
3+
sidebarTitle: "Connect to IDE"
4+
description: "Set up remote development on your Pod using VSCode or Cursor."
5+
---
6+
7+
This guide explains how to connect directly to your Pod through VSCode or Cursor using the Remote-SSH extension, allowing you to work within your Pod's volume directories as if the files were stored on your local machine.
8+
9+
## Requirements
10+
11+
Before you begin, you'll need:
12+
13+
- A local development environment with VSCode or Cursor installed.
14+
- [Download VSCode](https://code.visualstudio.com/download).
15+
- [Download Cursor](https://cursor.sh/).
16+
- Familiarity with basic command-line operations and SSH.
17+
18+
## Step 1: Install the Remote-SSH extension
19+
20+
To connect to a Pod, you'll need to install the Remote-SSH extension for your IDE:
21+
22+
1. Open VSCode or Cursor and navigate to the **Extensions** view (Ctrl+Shift+X or Cmd+Shift+X).
23+
24+
2. Search for and install the Remote-SSH extension:
25+
- VSCode: **Remote - SSH** by **ms-vscode-remote**.
26+
- Cursor: **Remote-SSH** by **Anysphere**.
27+
28+
## Step 2: Generate an SSH key
29+
30+
Before you can connect to a Pod, you'll need an SSH key that is paired with your RunPod account. If you don't have one, follow these steps:
31+
1. Generate an SSH key using this command on your local terminal:
32+
33+
```sh
34+
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519 -C "[email protected]"
35+
```
36+
37+
2. To retrieve your public SSH key, run this command:
38+
39+
```sh
40+
cat ~/.ssh/id_ed25519.pub
41+
```
42+
This will output something similar to this:
43+
44+
```sh
45+
ssh-ed25519 AAAAC4NzaC1lZDI1JTE5AAAAIGP+L8hnjIcBqUb8NRrDiC32FuJBvRA0m8jLShzgq6BQ [email protected]
46+
```
47+
48+
3. Copy and paste the output into the **SSH Public Keys** field in your [RunPod user account settings](https://www.runpod.io/console/user/settings).
49+
50+
<Warning>
51+
To enable SSH access, your public key must be present in the `~/.ssh/authorized_keys` file on your Pod. If you upload your public key to the settings page before your Pod starts, the system will automatically inject it into that file at startup.
52+
53+
If your Pod is already running when you upload the key, the system will not perform this injection. To enable SSH access, you'll need to either terminate/redeploy the Pod, or open a [web terminal](/pods/connect-to-a-pod#web-terminal-connection) on the running Pod and run the following commands:
54+
55+
```sh
56+
export PUBLIC_KEY="<the value you cat out locally>"
57+
echo "$PUBLIC_KEY" >> ~/.ssh/authorized_keys
58+
```
59+
</Warning>
60+
61+
## Step 3: Deploy a Pod
62+
63+
Next, deploy the Pod you want to connect to. For detailed deployment instructions, see [Manage Pods -> Create a Pod](/pods/manage-pods#create-a-pod).
64+
65+
To connect with VSCode/Cursor, your Pod template must support SSH over exposed TCP. To determine whether your Pod template supports this, during deployment, after selecting a template, look for a checkbox under **Instance Pricing** labeled **SSH Terminal Access** and make sure it's checked.
66+
67+
<Tip>
68+
All official Runpod Pytorch templates support SSH over exposed TCP.
69+
</Tip>
70+
71+
72+
## Step 4: Configure SSH for your IDE
73+
74+
Next, you'll configure SSH access to your Pod using the Remote-SSH extension. The instructions are different for VSCode and Cursor:
75+
76+
<Tabs>
77+
78+
<Tab title="VSCode">
79+
1. From the [Pods](https://www.runpod.io/console/pods) page, select the Pod you deployed.
80+
2. Select **Connect**, then select the **SSH** tab.
81+
3. Copy the second command, under **SSH over exposed TCP**. It will look similar to this:
82+
83+
```bash
84+
ssh [email protected] -p 12345 -i ~/.ssh/id_ed25519
85+
```
86+
87+
<Warning>
88+
If you only see one command under SSH, then SSH over exposed TCP is not supported by your selected Pod template. This means you won't be able to connect to your Pod directly through VSCode/Cursor, but you can still connect using [basic SSH](/pods/connect-to-a-pod#basic-ssh-connection) via the terminal.
89+
</Warning>
90+
91+
4. In VSCode, open the **Command Palette** (Ctrl+Shift+P or Cmd+Shift+P) and choose **Remote-SSH: Connect to Host**, then select **Add New SSH Host**.
92+
5. Enter the copied SSH command from step 3 (`ssh root@***.***.***.** -p ***** -i ~/.ssh/id_ed25519`) and press **Enter**. This will add a new entry to your SSH config file.
93+
94+
</Tab>
95+
96+
<Tab title="Cursor">
97+
98+
1. From the [Pods](https://www.runpod.io/console/pods) page, select the Pod you deployed.
99+
100+
2. Select **Connect**.
101+
3. Under **Direct TCP Ports**, look for a line similar to:
102+
103+
```
104+
TCP port -> 69.48.159.6:25634 -> :22
105+
```
106+
107+
<Warning>
108+
If you don't see a **Direct TCP Ports** section, then SSH over exposed TCP is not supported by your selected Pod template. This means you won't be able to connect to your Pod directly through VSCode/Cursor, but you can still connect using [basic SSH](/pods/connect-to-a-pod#basic-ssh-connection) via the terminal.
109+
</Warning>
110+
111+
Here's what these values mean:
112+
- `69.48.159.6` is the IP address of your Pod.
113+
- `25634` is the port number for the Pod's SSH service.
114+
115+
Make a note of these values (they will likely be different for your Pod), as you'll need them for the following steps.
116+
117+
4. In Cursor, open the **Command Palette** (Ctrl+Shift+P or Cmd+Shift+P) and choose **Remote-SSH: Connect to Host**, then select **Add New SSH Host**. This opens the SSH config file in Cursor.
118+
119+
5. Add the following to the SSH config file:
120+
121+
```
122+
Host POD_NAME
123+
HostName POD_IP
124+
User root
125+
Port POD_PORT
126+
IdentityFile ~/.ssh/id_ed25519
127+
```
128+
129+
Replace:
130+
- `POD_NAME` with a descriptive name for your Pod. This will be used to identify your Pod in the SSH config file, and does not need to match the name you gave your Pod in the RunPod console.
131+
- `POD_IP` with the IP address of your Pod from step 3.
132+
- `POD_PORT` with the port number of your Pod from step 3.
133+
134+
So, for the example Pod, the SSH config file will look like:
135+
136+
```
137+
Host my-pod
138+
HostName 69.48.159.6
139+
User root
140+
Port 25634
141+
IdentityFile ~/.ssh/id_ed25519
142+
```
143+
144+
<Note>
145+
If you are using a custom SSH key, replace `~/.ssh/id_ed25519` with the path to your SSH key.
146+
</Note>
147+
148+
6. Save and close the file.
149+
150+
</Tab>
151+
152+
</Tabs>
153+
154+
## Step 5: Connect to your Pod
155+
156+
Now you can connect to your Pod with the Remote-SSH extension.
157+
158+
1. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P).
159+
2. Select **Remote-SSH: Connect to Host**.
160+
3. Choose your Pod from the list (either by IP or custom name if you configured one).
161+
4. VSCode/Cursor will open a new window and connect to your Pod.
162+
5. When prompted, select the platform (Linux).
163+
6. Once connected, click **Open Folder** and navigate to your workspace directory (typically `/workspace`).
164+
165+
You should now be connected to your Pod instance, where you can edit files in your volume directories as if they were local.
166+
167+
<Warning >
168+
If you stop and then resume your Pod, the port numbers may change. If so, you'll need to go back to the previous step and update your SSH config file using the new port numbers before reconnecting.
169+
</Warning>
170+
171+
## Working with your Pod
172+
173+
Once connected through Remote-SSH, you can:
174+
175+
- Edit files with full IntelliSense and language support.
176+
- Run and debug applications with access to GPU resources.
177+
- Use integrated terminal for command execution.
178+
- Install extensions that run on the remote host.
179+
- Forward ports to access services locally.
180+
- Commit and push code using integrated Git support.
181+
182+
Here are some important directories to be aware of:
183+
184+
- `/workspace`: Default [persistent storage](/pods/storage/types) directory.
185+
- `/tmp`: Temporary files (cleared when Pod stops).
186+
- `/root`: Home directory for the root user.
187+
188+
## Troubleshooting
189+
190+
If you can't connect to your Pod:
191+
192+
1. Verify your Pod is running and fully initialized.
193+
2. Check that your SSH key is properly configured in RunPod settings.
194+
3. Ensure the Pod has SSH enabled in its template.
195+
196+
If the VSCode/Cursor server fails to install:
197+
198+
1. Check that your Pod has sufficient disk space.
199+
2. Ensure your Pod has internet connectivity.
200+
3. Try manually removing the `.vscode-server` or `.cursor-server` directory and reconnecting:
201+
```sh
202+
rm -rf ~/.vscode-server
203+
```

‎pods/connect-to-a-pod.mdx

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -109,8 +109,8 @@ If you're prompted for a password when attempting to connect, this indicates an
109109

110110
</Note>
111111

112-
## Connect via VSCode
112+
## Connect to VSCode or Cursor
113113

114-
For a more integrated development experience, you can connect directly to your Pod instance through Visual Studio Code (VSCode). This allows you to work within your Pod's volume directory as if the files were stored on your local machine, leveraging VSCode's powerful editing and debugging features.
114+
For a more integrated development experience, you can connect directly to your Pod instance through Visual Studio Code (VSCode) or Cursor. This allows you to work within your Pod's volume directory as if the files were stored on your local machine, leveraging VSCode's or Cursor's powerful editing and debugging features.
115115

116-
For a step-by-step guide, see [Connect to a Pod through VSCode](/tutorials/pods/connect-to-vscode).
116+
For a step-by-step guide, see [Connect to a Pod with VSCode or Cursor](/pods/configuration/connect-to-ide).

‎pods/overview.mdx

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -56,7 +56,7 @@ Once deployed, you can [connect to your Pod](/pods/connect-to-a-pod) through:
5656
- **Web proxy**: HTTP access to [exposed web services](/pods/configuration/expose-ports) via URLs in the format `https://[pod-id]-[port].proxy.runpod.net`.
5757
- **API**: Programmatic access and control through the [Runpod API](/api-reference/pods/POST/pods).
5858
- **JupyterLab**: A web-based IDE for data science and machine learning.
59-
- **VSCode**: [Connect to your Pod through VSCode](/tutorials/pods/connect-to-vscode), working within your volume directory as if the files were stored on your local machine.
59+
- **VSCode/Cursor**: [Connect to your Pod with VSCode or Cursor](/pods/configuration/connect-to-ide), working within your volume directory as if the files were stored on your local machine.
6060

6161
## Data transfer
6262

‎tutorials/introduction/overview.mdx

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,9 @@ Discover how to leverage Runpod Pods to run and manage your AI applications.
2626

2727
* [Fine tune an LLM with Axolotl on Runpod](/tutorials/pods/fine-tune-llm-axolotl): Learn how to fine-tune large language models with Axolotl on Runpod, a streamlined workflow for configuring and training AI models with GPU resources, and explore examples for LLaMA2, Gemma, LLaMA3, and Jamba.
2828
* [Run Fooocus in Jupyter Notebook](/tutorials/pods/run-fooocus): Learn how to run Fooocus, an open-source image generating model, in a Jupyter Notebook and launch the Gradio-based interface in under 5 minutes, with minimal requirements of 4GB Nvidia GPU memory and 8GB system memory.
29-
* [How To Connect to a Pod Instance through VSCode](/tutorials/pods/connect-to-vscode): Learn how to connect to a Runpod Pod instance through VSCode for seamless development and management.
3029
* [Build Docker Images on Runpod with Bazel](/tutorials/pods/build-docker-images): Learn how to build Docker images on Runpod using Bazel, a powerful build tool for creating consistent and efficient builds.
3130
* [Set up Ollama on your GPU Pod](/tutorials/pods/run-ollama): Set up Ollama, a powerful language model, on a GPU Pod using Runpod, and interact with it through HTTP API requests, harnessing the power of GPU acceleration for your AI projects.
32-
* [Run your first Fast Stable Diffusion with Jupyter Notebook](/tutorials/pods/run-your-first): Deploy a Jupyter Notebook to Runpod and generate your first image with Stable Diffusion in just 20 minutes, requiring Hugging Face user access token, Runpod infrastructure, and basic familiarity with the platform.
31+
* [Run your first Fast Stable Diffusion with Jupyter Notebook](/tutorials/pods/run-your-first): Deploy a Jupyter Notebook to Runpod and generate your first image with Stable Diffusion in just 20 minutes, requiring Hugging Face user access token, RunPod infrastructure, and basic familiarity with the platform.
3332

3433
## Containers
3534

‎tutorials/pods/connect-to-vscode.mdx

Lines changed: 0 additions & 76 deletions
This file was deleted.

0 commit comments

Comments
 (0)