Josh: Major update - troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi (58 sections)

2026-01-01T13:44:55Z

Major update - troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi (58 sections)

Josh: Added troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi

2026-01-01T13:28:38Z

Added troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi

New page

= Cursor IDE SSH Connection Setup for Raspberry Pi =

This guide explains how to configure Cursor IDE to connect to a Raspberry Pi through the VPS SSH port forward.

== Overview ==

Cursor IDE (like VS Code) supports remote development via SSH. To connect to your Raspberry Pi through the VPS:

<pre>
Your Computer → Cursor IDE → SSH → VPS:22223 → VPN Tunnel → Raspberry Pi (10.8.0.3:22)
</pre>

== Prerequisites ==

= ✅ '''SSH Port Forward Configured''' (Already done) =
* Port forward: <code>22223</code> → <code>10.8.0.3:22</code>

* Verify: <code>sudo ssh-forward list</code>

= ✅ '''IONOS Firewall Rule''' (Required) =
* Port <code>22223</code> must be allowed in IONOS Cloud Panel

* See: [SSH Port Forwarding Guide](Ssh-Port-Forwarding.md)

= '''Raspberry Pi Requirements''': =
* SSH server enabled

* Root SSH access enabled (see step 1)

* Network connectivity via VPN

== Step-by-Step Configuration ==

=== 1. Enable SSH and Root Access on Raspberry Pi ===

'''Enable SSH server (on Raspberry Pi):'''
<pre class="lang-bash">
sudo systemctl enable ssh
sudo systemctl start ssh
</pre>

'''Or via raspi-config:'''
<pre class="lang-bash">
sudo raspi-config
= Navigate to: Interfacing Options → SSH → Enable =
</pre>

'''Enable root SSH access (on Raspberry Pi):'''
<pre class="lang-bash">
= Set root password (if not already set) =
r

= Enable root login via SSH =
sudo sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/' /etc/ssh/sshd_config
= Or if using password auth: =
sudo sed -i 's/#PermitRootLogin yes/PermitRootLogin yes/' /etc/ssh/sshd_config

= Restart SSH service =
sudo systemctl restart ssh
</pre>

'''Verify SSH is running:'''
<pre class="lang-bash">
sudo systemctl status ssh
= Should show: active (running) =
</pre>

'''Test root SSH access:'''
<pre class="lang-bash">
ssh root@localhost
= Should connect as root =
</pre>

=== 2. Configure SSH on Your Local Machine ===

Create or edit <code>~/.ssh/config</code> on your local machine (where Cursor is installed):

<pre class="lang-bash">
= On your local machine (not the VPS) =
nano ~/.ssh/config
</pre>

Add the following configuration:

<pre>
Host raspberrypi
HostName 87.106.61.62
Port 22223
User root
IdentityFile ~/.ssh/id_rsa
ServerAliveInterval 60
ServerAliveCountMax 3
StrictHostKeyChecking no
UserKnownHostsFile ~/.ssh/known_hosts
</pre>

'''Configuration Options:'''
* <code>Host raspberrypi</code>: Alias name (use any name you prefer)

* <code>HostName 87.106.61.62</code>: Your VPS public IP

* <code>Port 22223</code>: External port for Raspberry Pi forward

* <code>User root</code>: Username on Raspberry Pi (using root for Cursor)

* <code>IdentityFile ~/.ssh/id_rsa</code>: Path to your SSH private key

* <code>ServerAliveInterval 60</code>: Keep connection alive (prevents timeouts)

=== 3. Set Up SSH Key Authentication (Recommended) ===

'''On your local machine:'''

= '''Generate SSH key pair''' (if you don't have one): =
<pre class="lang-bash">
ssh-keygen -t ed25519 -C "cursor-raspberrypi"
# Or use RSA: ssh-keygen -t rsa -b 4096
</pre>

= '''Copy public key to Raspberry Pi (as root):''' =
<pre class="lang-bash">
ssh-copy-id -p 22223 root@87.106.61.62
# Or manually:
cat ~/.ssh/id_ed25519.pub | ssh -p 22223 root@87.106.61.62 "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
</pre>

= '''Test passwordless connection:''' =
<pre class="lang-bash">
ssh -p 22223 root@87.106.61.62
# Should connect without password prompt
</pre>

=== 4. Configure Cursor IDE ===

= '''Install Remote SSH Extension''' (if not already installed): =
* Open Cursor

* Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)

* Search for "Remote - SSH" or "Anysphere Remote SSH"

* Install the extension

= '''Connect to Raspberry Pi''': =
* Press <code>F1</code> or <code>Ctrl+Shift+P</code> (Cmd+Shift+P on Mac)

* Type: <code>Remote-SSH: Connect to Host...</code>

* Select: <code>raspberrypi</code> (or the Host name from your SSH config)

* Or enter directly: <code>root@87.106.61.62:22223</code>

= '''First Connection Setup''': =
* Cursor will install the Cursor server on the Raspberry Pi

* This may take a few minutes on first connection

* You'll see a notification: "Installing Cursor Server..."

= '''Select Platform''' (if prompted): =
* Choose: <code>Linux</code> → <code>arm64</code> or <code>armv7l</code> (depending on your Pi model)

=== 5. Troubleshooting Connection Issues ===

==== Issue: Connection Timeout ====

'''Check IONOS Firewall:'''
* Verify port <code>22223</code> is allowed in IONOS Cloud Panel

* Check rule priority (lower numbers = higher priority)

'''Test SSH connection manually:'''
<pre class="lang-bash">
ssh -v -p 22223 root@87.106.61.62
</pre>

'''Check port forward on VPS:'''
<pre class="lang-bash">
= On VPS =
sudo ssh-forward list
iptables -t nat -L PREROUTING -n | grep 22223
</pre>

==== Issue: "Permission Denied" ====

'''Verify SSH key is authorized:'''
<pre class="lang-bash">
= On Raspberry Pi =
cat ~/.ssh/authorized_keys
= Should contain your public key =
</pre>

'''Check SSH server logs:'''
<pre class="lang-bash">
= On Raspberry Pi =
sudo tail -f /var/log/auth.log
= Attempt connection and watch for errors =
</pre>

'''Verify user permissions:'''
<pre class="lang-bash">
= On Raspberry Pi =
ls -la ~/.ssh/
= Should be: drwx------ (700) for .ssh directory =
= Should be: -rw------- (600) for authorized_keys =
</pre>

==== Issue: Cursor Server Installation Fails ====

'''Clear Cursor server cache:'''
<pre class="lang-bash">
= On Raspberry Pi =
rm -rf ~/.cursor-server
</pre>

'''Check disk space:'''
<pre class="lang-bash">
= On Raspberry Pi =
df -h
</pre>

'''Check Python/Node.js availability:'''
<pre class="lang-bash">
= On Raspberry Pi =
python3 --version
node --version # If available
</pre>

==== Issue: Slow Connection ====

'''Optimize SSH config:'''
Add to <code>~/.ssh/config</code>:
<pre>
Host raspberrypi
Compression yes
IPQoS throughput
</pre>

'''Use SSH multiplexing:'''
<pre>
Host raspberrypi
ControlMaster auto
ControlPath ~/.ssh/control-%h-%p-%r
ControlPersist 10m
</pre>

=== 6. Verify Complete Setup ===

'''Test checklist:'''

* [ ] SSH port forward is active: <code>sudo ssh-forward list</code>

* [ ] IONOS firewall allows port 22223

* [ ] Can SSH manually: <code>ssh -p 22223 root@87.106.61.62</code>

* [ ] SSH key authentication works (no password prompt)

* [ ] Cursor can connect via Remote SSH

* [ ] Cursor server installed on Raspberry Pi

* [ ] Can open files and use terminal in Cursor

=== 7. Multiple Devices Configuration ===

If you have multiple devices, add separate entries in <code>~/.ssh/config</code>:

<pre>
Host synology
HostName 87.106.61.62
Port 22222
User admin
IdentityFile ~/.ssh/id_rsa

Host raspberrypi
HostName 87.106.61.62
Port 22223
User root
IdentityFile ~/.ssh/id_rsa

Host device-03
HostName 87.106.61.62
Port 22223
User user
IdentityFile ~/.ssh/id_rsa
</pre>

== Security Best Practices ==

'''Note''': This guide uses root user for Cursor connections to avoid permission issues. While convenient for development, be aware of security implications.

= '''Use SSH Keys''': Always use key-based authentication instead of passwords =
= '''Disable Password Auth for Root''': On Raspberry Pi, edit <code>/etc/ssh/sshd_config</code>: =
<pre>
PermitRootLogin prohibit-password
PasswordAuthentication no
PubkeyAuthentication yes
</pre>
This allows root login only with SSH keys, not passwords.
Then restart: <code>sudo systemctl restart ssh</code>

= '''Use Strong Keys''': Use ED25519 or RSA 4096-bit keys =
= '''Limit Access''': Consider restricting SSH access to specific IPs if possible =
= '''Keep Updated''': Regularly update Raspberry Pi OS and SSH server =
= '''Root Access Consideration''': Using root avoids permission issues in Cursor but increases security risk. Consider using a dedicated user with sudo if security is a concern. =

== Advanced Configuration ==

=== SSH Config with Jump Host (Alternative) ===

If you want to connect through the VPS as a jump host:

<pre>
Host vps
HostName 87.106.61.62
User root
IdentityFile ~/.ssh/id_rsa

Host raspberrypi
HostName 10.8.0.3
User root
ProxyJump vps
IdentityFile ~/.ssh/id_rsa
</pre>

=== Port Forwarding in SSH Config ===

You can also create local port forwards in your SSH config:

<pre>
Host raspberrypi
HostName 87.106.61.62
Port 22223
User root
LocalForward 8080 localhost:8080 # Forward local port 8080 to Pi's 8080
</pre>

== Quick Reference ==

{| class="wikitable"
|-
| Component || Value
|-
| VPS Public IP || 87.106.61.62
|-
| Raspberry Pi External Port || 22223
|-
| Raspberry Pi VPN IP || 10.8.0.3
|-
| Raspberry Pi SSH Port || 22
|-
| Default User || root
|}
'''SSH Command:'''
<pre class="lang-bash">
ssh -p 22223 root@87.106.61.62
</pre>

'''Cursor Connection:'''
* Host: <code>raspberrypi</code> (from SSH config)

* Or: <code>root@87.106.61.62:22223</code>

== Related Documentation ==

* [SSH Port Forwarding Management](index.md)

* [OpenVPN Server Configuration](index.md)

* [Port Forwarding Troubleshooting](port-forwarding-troubleshooting.md)

----

[[Category:Documentation]]
[[Category:Documentation/Cursor SSH]]

Cursor SSH:Setup - Revision history

Josh: Major update - troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi (58 sections)

Josh: Added troubleshooting guide: Cursor IDE SSH Connection Setup for Raspberry Pi