Editing Cursor SSH:Setup

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]]