SSH Unreachable Playbook

Who this is for

Users who are seeing SSH-related errors when CloudAIPilot tries to connect to a server: backups fail, deployments fail, or terminal access is unavailable — with errors like "SSH_NOT_CONFIGURED", "Connection refused", or "Connection timed out".

Understanding SSH in CloudAIPilot

CloudAIPilot SSH-es to your server as the cloudpilot user (not root). It uses an SSH key pair:

• The private key is stored encrypted in CloudAIPilot.
• The public key must be present in /home/cloudpilot/.ssh/authorized_keys on the server.

Provisioned servers have this configured automatically. Imported servers require manual SSH setup.

Step 1 — Check the Server's SSH Status

1. Open Server detail.
2. Check if there is an SSH error or warning banner.
3. Look at the SSH field in the server info sidebar — it may show "Not configured" or a recent error.

Step 2 — Identify the Error Type

Playbook A: SSH_NOT_CONFIGURED

This means no SSH key pair exists in CloudAIPilot for this server.

1. Go to Server detail → SSH tab (or the Settings panel).
2. Click Set Up SSH.
3. CloudAIPilot generates a new key pair.
4. Copy the public key shown.
5. Log in to the server via your cloud provider's console (EC2 SSM, GCP Cloud Shell, Azure Serial Console, or DigitalOcean Recovery Console).
6. Add the public key to /home/cloudpilot/.ssh/authorized_keys.
7. Return to CloudAIPilot and click Test Connection.

See KB-02-08: SSH Setup and Repair for step-by-step instructions.

Playbook B: Connection Refused

SSH service is not running on the server.

1. Access the server via your cloud provider's console (not SSH — it's not working).
2. Start or restart the SSH service:

   sudo systemctl restart sshd

1. Verify SSH is listening: ss -tlnp | grep 22
2. If SSH is on a non-standard port, update the SSH port in CloudAIPilot's server settings.

Playbook C: Connection Timed Out

A firewall or security group is blocking port 22.

1. Check your cloud provider's firewall rules:

• AWS: EC2 Security Group → Inbound rules → Port 22
• GCP: VPC Firewall Rules → Allow TCP port 22
• Azure: Network Security Group → Inbound security rules → Port 22
• DigitalOcean: Droplet Firewall → Inbound → Port 22

1. Add an inbound rule to allow TCP port 22 from CloudAIPilot's IP range (or 0.0.0.0/0 if open access is acceptable).
2. Also check the CloudAIPilot server firewall settings — make sure port 22 is allowed.

Playbook D: Permission Denied (publickey)

The server does not have CloudAIPilot's public key in authorized_keys.

1. Go to Server detail → SSH tab.
2. Click Copy Public Key.
3. Access the server via cloud provider console (emergency access).
4. Append the public key to /home/cloudpilot/.ssh/authorized_keys:

   echo "ssh-rsa AAAA..." >> /home/cloudpilot/.ssh/authorized_keys
   chmod 600 /home/cloudpilot/.ssh/authorized_keys

1. Test connection in CloudAIPilot.

Playbook E: Host Key Verification Failed

The server was rebuilt or re-provisioned and its SSH host key changed.

1. In CloudAIPilot server settings, click Reset Host Key (or Re-verify).
2. Accept the new host key.

Related Articles

• KB-02-08: SSH Setup and Repair
• KB-12-01: Deployment Failed Playbook