Chapter 2 — SSH Devices and Connections

The primary workflow in AidaIDE is "open a connection tab, work on a remote device." This chapter walks you through getting that first tab open and keeping it organised as you accumulate hosts.

What this chapter covers

Opening a new SSH connection from the toolbar or menu.
Using Connection Manager to add, edit, and group hosts.
Storing passwords, key files, and key passphrases in the vault.
The anatomy of a connection tab — what each pane does.
Common pitfalls: non-22 ports, key permissions, host-key changes.

Opening a new connection

There are four entry points and they all converge on the same dialog:

Toolbar → New Tab (+). If you have at least one saved host, you get a chooser dropdown; pick a host or click Manage… to open Connection Manager.
File → New Tab (Ctrl+T).
File → Connection Manager — full management UI.
Toolbar → Connections (≡) — same as the menu option.

If this is the very first time, you have no saved hosts. Click Manage… or open Connection Manager directly.

Connection Manager

Connection Manager is the central registry of every host AidaIDE knows about. It has three columns:

Left — group tree (All, Production, Lab, etc.). Right-click to add or rename a group.
Center — table of hosts in the selected group with columns for Name, Host, Port, Username, Last Connected.
Right — editor for the currently selected host.

Adding a host

Click Add (or Add Host in the toolbar of the dialog).
Fill in:
- Name — a friendly label (e.g. pi-lab-01).
- Host — IP address or DNS name.
- Port — 22 is the default, change it if your server listens elsewhere. See Ports and the port-22 trap below.
- Username — Linux user on the remote box.
- Authentication — password, key file, or both.
Click Save. Your secrets go into the vault immediately, encrypted under your master password.
Click Connect (or close the dialog and use New Tab → your host).

Editing a host

Select it on the right, change fields, click Save. AidaIDE re-encrypts any changed secret in place.

Grouping hosts

Drag a host between groups in the left tree, or right-click → Move to Group. Groups have no functional meaning beyond making the New Tab dropdown easier to navigate.

Importing existing SSH config

If you already have a ~/.ssh/config, Connection Manager has an Import… button. It reads Host, HostName, Port, User, and IdentityFile directives and creates entries for each. Passwords and key passphrases still have to be entered manually — they are not in ~/.ssh/config.

Anatomy of a connection tab

A connection tab is the per-host workspace. Once connected, the tab is divided into four regions (defaults shown; you can rearrange them):

┌─────────────────────────────────────────────────────────┐
│ Top toolbar: file controls, run, terminal toggles       │
├──────────────────┬──────────────────────┬───────────────┤
│ File Browser     │   Editor             │  LCOT Panel   │
│  - Remote tree   │   - Tabs of opened   │   READ ▶      │
│  - Local tree    │     remote files     │   WRITE ▶     │
│                  │   - Syntax highlight │               │
├──────────────────┴──────────────────────┤               │
│ Terminal (xterm-compatible, full PTY)   │               │
│ $ _                                     │               │
└─────────────────────────────────────────┴───────────────┘

File Browser (left) — two trees stacked: the remote filesystem over SFTP and your local filesystem. Drag-and-drop between them.
Editor (center, top) — syntax-highlighted text editor with tabs for every file you have open on this host. See Chapter 3 for full editor details.
Terminal (center, bottom) — full PTY into the remote shell. Resizes with the pane.
LCOT Panel (right) — one-click READ/WRITE scripts targeted at this connection. See Chapter 4.
Intel Panel — context info about the host (uptime, OS, IP). Toggle with the panel button on the top toolbar.

The tab title is the host name (or name@host if multiple sessions to the same host are open). A red dot next to the tab name means the connection is down. A spinner means it is reconnecting.

Authentication

Password

Type it in once when adding the host. It is stored in the vault and re-supplied on every connection.

Key file

Pick the private key from your filesystem (~/.ssh/id_ed25519, ~/.ssh/id_rsa, etc.).
If the key is passphrase-protected, AidaIDE prompts for the passphrase once and stores it in the vault.
The public key must already be installed on the remote box in ~/.ssh/authorized_keys. AidaIDE will not push it for you. (See Setting up your first SSH key pair below.)

Both / fallback

You can store both a key and a password. If the key fails (wrong key, host does not accept it), AidaIDE falls back to the password silently.

Keys vs passwords

For anything beyond local lab use, prefer keys. They are stronger, do not transit the wire on every login, and play nicely with sudo. Passwords are easier to set up the first time and are fine for a single Raspberry Pi on your bench.

Ports and the port-22 trap

AidaIDE saves a custom port the moment you set one in Connection Manager, but several places in the codebase have historically hardcoded 22. If a connection fails with "Connection refused" on a non-default port:

Re-open the host in Connection Manager and verify Port is correct.
Check Connection Method (some scan-style tools probe port 22 regardless).
Try ssh -p <port> user@host from your terminal as a sanity check.

The intended probe order in AidaIDE is device.ssh_port → device.port → 22. If you suspect your custom port is being ignored anywhere, file a bug from Help → Report a Bug and attach the connection log — that is a known recurring trap.

Common operations

Run a command quickly

Click in the terminal pane and type it. The terminal is a real PTY, not a wrapper.
Or use LCOT for one-click commands (e.g. Disk Usage, List Services).

Edit a remote file

In the remote File Browser tree, double-click the file.
It opens in the editor with the path prefixed by the host name.
Save with Ctrl+S. AidaIDE writes back over SFTP. Save will not fall back to a local file if SFTP fails — you will see an error dialog. This is intentional to prevent silent wrong-filesystem data loss.

Drag a local file to the remote

In the local File Browser tree, click and drag the file onto a folder in the remote tree.
AidaIDE uploads it via SFTP. A progress notification appears in the status bar.

Reconnect after the connection drops

The tab shows a red dot and a Reconnect button. Click it. If the host is genuinely gone, the reconnect button stays and the terminal pane is preserved (so you do not lose what was on screen).

Open multiple sessions to the same host

New Tab → same host → New Session. Each session is independent — they do not share the working directory, environment, or terminal scrollback.

Recent connections

File → Recent Connections lists the last 10 hosts you connected to with one-click reconnect. The list survives across launches.

Terms & Setup

SSH (Secure Shell)

An encrypted protocol for logging into another machine and running commands. AidaIDE speaks SSH (and SFTP, which rides on top of SSH) using a Python implementation, so you do not need a separate ssh client installed.

SFTP

SSH File Transfer Protocol. Lets AidaIDE read and write files on the remote box without opening a shell. The remote file browser and the editor's save mechanism both use SFTP.

Host key

The remote server's identity fingerprint. The first time you connect, AidaIDE asks you to trust it. If a host key changes on a subsequent connection (e.g. the server was reinstalled), AidaIDE refuses to connect and shows the old vs. new fingerprint. This is a security feature, not a bug — verify with the server admin before clicking Accept New Key.

Public key vs private key

The private key stays on your machine. The public key (one short line ending in your email or username) goes on the remote server in ~/.ssh/authorized_keys. Anyone with the public key can verify a signature made with the private key, but cannot forge one.

"I do not have an SSH server" — setup paths

Windows local (for testing AidaIDE itself):
1. Settings → Apps → Optional Features → Add → OpenSSH Server.
2. Open Services (services.msc), find OpenSSH SSH Server, set it to Automatic and click Start.
3. Allow port 22 in Windows Firewall (a popup may appear; click Allow).
4. Connect AidaIDE to localhost:22 with your Windows username.

Raspberry Pi (Pi OS):
1. Insert the SD card on your PC. In the boot partition, create an empty file named ssh (no extension). When the Pi boots it will enable SSH.
2. Or on the running Pi, sudo raspi-config → Interface Options → SSH → Enable.
3. Default username on Pi OS is whatever you set in Imager (or pi on older images).
4. Connect AidaIDE to the Pi's IP, port 22.

Linux server / cloud VM:
- The provider (DigitalOcean, AWS, GCP, Azure) usually delivers an Ubuntu/Debian VM with SSH enabled and key-only authentication preconfigured. They give you a key file and an IP — feed both into Connection Manager.

WSL on Windows (no extra box):
1. wsl --install in PowerShell as admin. Reboot.
2. Inside WSL, sudo apt install openssh-server, sudo systemctl enable --now ssh, set a password with passwd.
3. Find WSL's IP with ip addr (eth0). Connect AidaIDE there. Note: WSL2's IP changes on every Windows reboot.

Setting up your first SSH key pair

If your remote box requires keys (or you simply want to use them), here is the shortest path:

Generate a key on your local machine:
- Windows PowerShell or macOS/Linux terminal: ssh-keygen -t ed25519 -C "your_email@example.com"
- Accept the default path (~/.ssh/id_ed25519).
- Set a passphrase (recommended). AidaIDE will store it in the vault so you only type it once.
Copy the public key to the server:
- Easiest: ssh-copy-id user@host (works on macOS/Linux/WSL).
- On Windows without ssh-copy-id: type %USERPROFILE%\.ssh\id_ed25519.pub | ssh user@host "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys"
- Or just paste the contents of id_ed25519.pub into ~/.ssh/authorized_keys on the server by hand.
Tell AidaIDE about the key: In Connection Manager, set Authentication → Key File and point at the private key (no .pub). Connect.

Key permissions errors

If SSH refuses your key with a permissions complaint, on the remote server run:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys

On Windows, key file permissions are checked by OpenSSH. If you see a "WARNING: UNPROTECTED PRIVATE KEY FILE" error, right-click the key in Explorer → Properties → Security → Advanced → Disable inheritance and remove all users except your own account.

Saved credential security

Every secret stored in Connection Manager is encrypted with a multi-layer scheme (PBKDF2/Scrypt-derived keys, per-credential salts). Only your master password unlocks the chain. If you suspect compromise, rotate the secret on the server and update it in Connection Manager — there is no replay protection beyond the encryption itself.

Recurring traps to know

These bugs have shipped before and may resurface. If a connection behaves oddly, suspect them first:

Hardcoded port 22 — even when Connection Manager has the right port. Symptom: "Connection refused" or "Connection timed out" on a non-22 port that you can clearly reach with the system ssh.
Silent SFTP fallback to local open() — fixed, but if a save appears to succeed but the remote file is unchanged, check that you are not editing the local mirror.
Decrypt failure returning empty string — fixed; should now surface an error dialog. If you ever see a password field that mysteriously goes blank, file a bug.